Konfiguracja aplikacji mobilnej

ECDP umożliwia wysyłanie powiadomień push do użytkowników Twojej aplikacji mobilnej, z wykorzystaniem usługi Firebase Cloud Messaging (FCM). Nie musisz instalować żadnego SDK – Twoja aplikacja komunikuje się z ECDP bezpośrednio przez API, wykorzystując ten sam projekt Firebase, którego już używasz do wysyłania powiadomień z własnego backendu.

Ten artykuł opisuje, jak połączyć aplikację z ECDP: konfigurację Firebase, dodanie aplikacji w ECDP, rejestrację urządzeń klientów oraz odnajdywanie danych o urządzeniach w profilach klientów. Informacje o tworzeniu i wysyłaniu samych powiadomień znajdziesz w artykule Powiadomienia mobile push.

Wymagania

Upewnij się, że masz przygotowane:

• Projekt Google Cloud z włączonym Firebase i Cloud Messaging dla Twojej aplikacji na Androida i/lub iOS.
• Konto (service account) Firebase z uprawnieniem do wysyłki wiadomości oraz jego plik JSON.
• Dostęp do kodu swojej aplikacji, żeby Twój deweloper mógł dodać wywołania API potrzebne do rejestrowania urządzeń w ECDP oraz raportowania wyświetleń i kliknięć powiadomień.

Skonfiguruj Firebase dla swojej aplikacji

Zanim dodasz aplikację mobilną w ECDP, utwórz w Google Cloud konto usługi, z którego ECDP będzie korzystać do wysyłki wiadomości przez projekt Firebase.

1. W Google Cloud wybierz projekt używany przez Twoją aplikację mobilną.
2. Włącz Firebase Cloud Messaging API.
3. Utwórz konto usługi z uprawnieniem do wysyłki wiadomości – użyj roli Firebase Cloud Messaging API Admin albo roli niestandardowej z uprawnieniem  cloudmessaging.messages.create.
4. Wygeneruj klucz JSON dla tego konta usługi i pobierz plik. Prześlesz go w ECDP w kolejnym kroku.

Dodaj aplikację mobilną w ECDP

Gdy masz już gotowe konto usługi Firebase, utwórz odpowiadającą mu aplikację mobilną w ECDP.

1. Przejdź do Ustawienia > Aplikacje mobilne.
2. Kliknij Skonfiguruj aplikację mobilną.
3. Wprowadź nazwę aplikacji (wymagane, maksymalnie 100 znaków) oraz opcjonalnie opis.
4. Prześlij wygenerowany plik JSON Firebase:
   • Jeśli plik jest prawidłowy, ECDP odczytuje z niego client_email, private_key, oraz project_id i automatycznie uzupełnia te pola (tylko do odczytu).
   • Jeśli w pliku brakuje wymaganych danych, ECDP wyświetla błąd i zaznacza brakujące pola.
   • Jeśli usuniesz przesłany plik, automatycznie uzupełnione pola zostają wyczyszczone.
5. Kliknij Zapisz.

Po zapisaniu ECDP nadaje aplikacji unikalne ID, widoczny na liście aplikacji w Ustawienia > Aplikacje mobilne. Twój deweloper potrzebuje tego ID razem z adresem API i kluczem API Twojego konta, żeby połączyć aplikację przez API. Oba znajdziesz w Ustawienia > API.

Co dzieje się automatycznie po dodaniu aplikacji mobilnej

• ECDP tworzy dedykowaną zgodę na kanał mobile push dla tej aplikacji, tak samo jak w przypadku web push.
• Ta zgoda jest aktywna od razu.

Połącz swoją aplikację z ECDP

Gdy aplikacja mobilna jest już utworzona w ECDP, Twój deweloper łączy kod Twojej aplikacji, żeby mogła rejestrować urządzenia i raportować aktywność powiadomień. Na Androidzie nadal wymaga to dodania do aplikacji standardowego pliku google-services.json, tak jak w każdej integracji z Firebase.

1. Twoja aplikacja pobiera token FCM z Firebase, jak zwykle.
2. Twoja aplikacja wysyła dane urządzenia i token do ECDP: POST /customermobiledevices.
   • Wymagane:
     • ID aplikacji mobilnej,
     • ID urządzenia – stabilny identyfikator, który nie zmienia się przy aktualizacjach aplikacji, np. installation ID,
     • token FCM.
   • Opcjonalne dane urządzenia: system operacyjny, wersja systemu, marka urządzenia, model urządzenia, wersja aplikacji, język.
   • Opcjonalne identyfikatory klienta: e-mail, telefon lub CRM ID. Zalecane jest przekazywanie jednego, głównego identyfikatora, na przykład adresu e-mail.
3. Żeby usunąć rejestrację urządzenia – na przykład po tym, jak klient cofnie zgodę na powiadomienia – wyślij DELETE /customermobiledevices z tymi samymi identyfikatorami.

Pełne informacje o żądaniach i odpowiedziach API znajdziesz w dokumentacji Swagger – CustomerMobileDevices.

Jak ECDP identyfikuje klientów na wielu urządzeniach

Urządzenie może być aktywnie przypisane tylko do jednego klienta naraz. Gdy rejestracja urządzenia zawiera identyfikator klienta, który nie zgadza się z tym, co jest już zapisane, ECDP ustala, co się zmieniło:

• Jeśli urządzenie należy obecnie do klienta anonimowego, a nowy identyfikator pasuje do istniejącego, rozpoznanego klienta, ECDP łączy te dwa rekordy: urządzenie (wraz z historią) zostaje przeniesione do rozpoznanego klienta, a klient anonimowy zostaje dezaktywowany.
• Jeśli urządzenie należy do rozpoznanego klienta, ale w żądaniu pojawia się inny identyfikator, ECDP traktuje to jako inną osobę korzystającą z tego samego urządzenia: przenosi urządzenie do tego innego klienta (tworząc go, jeśli trzeba), podczas gdy pierwotny klient zachowuje swoją historię.

Zgoda na mobile push

Rejestrowanie i usuwanie urządzeń przez API obsługuje zgody automatycznie, bez żadnych ręcznych działań z Twojej strony.

• Każda aplikacja mobilna ma jedną dedykowaną zgodę, wspólną dla wszystkich urządzeń tej aplikacji przypisanych do danego klienta.
• Zgoda jest udzielona, dopóki klient ma przynajmniej jedno aktywne urządzenie w tej aplikacji.
• Usunięcie urządzenia przez API cofa zgodę, jeśli było to ostatnie aktywne urządzenie klienta w tej aplikacji.
• ECDP dezaktywuje też urządzenie i automatycznie cofa jego zgodę, gdy Firebase zgłosi, że token przestał być prawidłowy:
  • token nieprawidłowy (invalid) – widoczny w statystykach dostarczenia jako Zwrócone (Bounced).
  • token niezarejestrowany (unregistered) – widoczny w statystykach dostarczenia jako Wypisani (Unsubscribed).

Śledź dostarczanie i zaangażowanie w powiadomienia

Każde powiadomienie wysłane przez ECDP jest oznaczone identyfikatorem messageGuid, unikalnym identyfikatorem tego konkretnego powiadomienia, przekazywanym w payloadzie, który Twoja aplikacja otrzymuje z Firebase. Twoja aplikacja odczytuje tę wartość i odsyła ją do ECDP, żeby każde wyświetlenie lub kliknięcie można było powiązać z konkretnym powiadomieniem, którego dotyczy.

• Wysyłka jest zapisywana automatycznie przez ECDP w momencie przekazania wiadomości do Firebase. Twoja aplikacja nie musi nic robić w tym przypadku. Sposób reprezentacji zdarzeń wysyłki opisano w dokumentacji API.
• Wyświetlenie – Twoja aplikacja powinna zgłosić je, gdy system operacyjny faktycznie wyświetli powiadomienie użytkownikowi: POST /events/mobile/push/views. Dokładny format żądania znajdziesz w dokumentacji API.
• Kliknięcie – Twoja aplikacja powinna zgłosić je tylko wtedy, gdy klient stuknie w powiadomienie: POST /events/mobile/push/clicks. Dokładny format żądania znajdziesz w dokumentacji API.

Oba endpointy wymagają ID aplikacji mobilnej oraz wartości messageGuid z payloadu powiadomienia. Nie musisz przesyłać urządzenia ani klienta, ponieważ ECDP już wie, kto otrzymał powiadomienie. Każde zdarzenie zgłaszaj tylko raz na powiadomienie.

Wysyłasz dużo zdarzeń? Użyj POST /events/mobile/batch, żeby zgłosić do 1000 zdarzeń wyświetlenia/kliknięcia w jednym żądaniu, zamiast wywoływać pojedyncze endpointy jeden po drugim.

Linki bezpośrednie

Powiadomienie push może zawierać link bezpośredni, który po kliknięciu otwiera konkretny ekran w Twojej aplikacji. Link bezpośredni ustawiasz podczas tworzenia treści powiadomienia.

ECDP przekazuje link bezpośredni jako zwykłe dane w payloadzie powiadomienia, w polu deep_link. Nie waliduje formatu linku ani go nie otwiera, to w całości leży po stronie Twojej aplikacji.

• Upewnij się, że Twoja aplikacja poprawnie interpretuje i otwiera linki bezpośrednie, których planujesz używać.
• Dodaj zabezpieczenie, np. otwarcie ekranu głównego, na wypadek, gdyby link bezpośredni nie został rozpoznany.

Zobacz urządzenia mobilne klienta

Sekcja Urządzenia mobilne w profilu Klient 360 zawiera listę wszystkich urządzeń przypisanych do klienta, na których zainstalowana jest Twoja aplikacja.

• Każde urządzenie jest wyświetlane jako karta z: ikoną platformy, identyfikatorem urządzenia, statusem (Aktywne lub Nieaktywne), aplikacją, do której należy, oraz marką i modelem urządzenia.
• Token na karcie jest skrócony – najedź na niego, żeby zobaczyć pełną wartość, albo użyj przycisku kopiowania.
• Kliknij kartę, żeby rozwinąć dodatkowe szczegóły: system operacyjny, wersję systemu, język aplikacji i wersję aplikacji.
• Karty są posortowane od najnowszych, po dwie w rzędzie. Brakujące wartości są oznaczone jako „–”.
• Jeśli klient nie ma zarejestrowanych urządzeń, sekcja pokazuje stan pusty.

Znajdź klientów po urządzeniu mobilnym

Domyślnie tabela Klienci nie pokazuje klientów, którzy mają wyłącznie urządzenie mobilne, bez adresu e-mail, telefonu ani CRM ID. Gdy skonfigurowana jest przynajmniej jedna aplikacja mobilna, nad tabelą pojawia się nowe pole wyboru: Uwzględnij klientów posiadających wyłącznie urządzenie mobilne. Domyślnie opcja ta jest odznaczona, a Twój wybór jest zapamiętywany, tak samo jak w przypadku pola wyboru dla klientów posiadających wyłącznie web push.

Zarządzaj aplikacją mobilną

W Ustawienia > Aplikacje mobilne wybierz Dezaktywuj przy aplikacji, żeby przestać jej używać do wysyłki powiadomień. Pojawi się informacja, że po dezaktywacji nie będzie można zbierać zgód, śledzić zachowania ani wysyłać powiadomień do klientów przez tę aplikację.

Zdezaktywowaną aplikację możesz w dowolnym momencie ponownie włączyć z tej samej listy, używając akcji Aktywuj. Usuwanie aplikacji mobilnej nie jest jeszcze możliwe.

Często zadawane pywania

Czy mogę dodać aplikację mobilną bez pliku konfiguracyjnego Firebase?

Tak. Plik JSON Firebase jest opcjonalny podczas pierwszego tworzenia aplikacji mobilnej – możesz zapisać aplikację i dodać plik później. Aplikacja w obu przypadkach zostaje zapisana ze statusem Aktywna, ale ECDP nie może wysyłać dla niej powiadomień push, dopóki nie ma prawidłowej konfiguracji Firebase.

Co się stanie, jeśli usunę przesłany plik Firebase?

Jeśli usuniesz plik podczas konfigurowania lub edycji aplikacji mobilnej, ECDP czyści pola client_email, private_key, oraz project_id. Możesz następnie przesłać inny plik albo zapisać aplikację bez konfiguracji Firebase i dodać ją później.

Informacje o tym, jak tworzyć i wysyłać powiadomienia mobile push po połączeniu aplikacji, znajdziesz w artykule Powiadomienia mobile push.