Skonfiguruj aplikację kliencką Firebase Cloud Messaging za pomocą Unity

Aby napisać wieloplatformową aplikację kliencką Firebase Cloud Messaging w Unity, użyj interfejsu API Firebase Cloud Messaging . Zestaw Unity SDK działa zarówno na Androidzie, jak i na Apple, a dla każdej platformy wymagana jest dodatkowa konfiguracja.

Zanim zaczniesz

Warunki wstępne

  • Zainstaluj Unity 2019.1 lub nowszą. Wcześniejsze wersje mogą również być kompatybilne, ale nie będą aktywnie obsługiwane. Wsparcie dla Unity 2019.1 jest uważane za przestarzałe i nie będzie już aktywnie wspierane po wydaniu następnej głównej wersji.

  • (Tylko platformy Apple) Zainstaluj następujące elementy:

    • Xcode 13.3.1 lub nowszy
    • CocoaPods 1.12.0 lub nowszy
  • Upewnij się, że Twój projekt Unity spełnia następujące wymagania:

    • Dla systemu iOS — przeznaczony dla systemu iOS 11 lub nowszego
    • Dla systemu tvOS — przeznaczony dla systemu tvOS 12 lub nowszego
    • Dla Androida — docelowy poziom API 19 (KitKat) lub wyższy
  • Skonfiguruj urządzenie lub użyj emulatora, aby uruchomić projekt Unity.

    • W systemie iOS lub tvOS — skonfiguruj urządzenie fizyczne do uruchamiania aplikacji i wykonaj następujące zadania:

      • Uzyskaj klucz uwierzytelniający powiadomienia Apple Push dla swojego konta programisty Apple .
      • Włącz powiadomienia push w XCode w obszarze Aplikacja > Możliwości .
    • Dla Androidaemulatory muszą używać obrazu emulatora z Google Play.

Jeśli nie masz jeszcze projektu Unity i chcesz po prostu wypróbować produkt Firebase, możesz pobrać jeden z naszych przykładów szybkiego startu .

Krok 1: Utwórz projekt Firebase

Zanim będziesz mógł dodać Firebase do swojego projektu Unity, musisz utworzyć projekt Firebase, aby połączyć się z projektem Unity. Odwiedź stronę Poznaj projekty Firebase, aby dowiedzieć się więcej o projektach Firebase.

Krok 2: Zarejestruj swoją aplikację w Firebase

Możesz zarejestrować jedną lub więcej aplikacji lub gier, aby połączyć się z projektem Firebase.

  1. Przejdź do konsoli Firebase .

  2. Na środku strony przeglądu projektu kliknij ikonę Unity ( ), aby uruchomić przepływ pracy instalacji.

    Jeśli dodałeś już aplikację do projektu Firebase, kliknij Dodaj aplikację , aby wyświetlić opcje platformy.

  3. Wybierz, który cel kompilacji swojego projektu Unity chcesz zarejestrować, lub możesz nawet zarejestrować oba cele jednocześnie.

  4. Wprowadź identyfikatory specyficzne dla platformy projektu Unity.

    • W przypadku systemu iOS — wprowadź identyfikator iOS projektu Unity w polu Identyfikator pakietu iOS .

    • Dla systemu Android — wprowadź identyfikator systemu Android projektu Unity w polu nazwy pakietu systemu Android .
      Terminy nazwa pakietu i identyfikator aplikacji są często używane zamiennie.

  5. (Opcjonalnie) Wprowadź pseudonimy specyficzne dla platformy projektu Unity.
    Te pseudonimy są wewnętrznymi, wygodnymi identyfikatorami i są widoczne tylko dla Ciebie w konsoli Firebase.

  6. Kliknij opcję Zarejestruj aplikację .

Krok 3: Dodaj pliki konfiguracyjne Firebase

  1. Uzyskaj pliki konfiguracyjne Firebase specyficzne dla platformy w procesie konfiguracji konsoli Firebase.

    • W systemie iOS — kliknij Pobierz plik GoogleService-Info.plist .

    • W systemie Android — kliknij Pobierz plik google-services.json .

  2. Otwórz okno Projekt swojego projektu Unity, a następnie przenieś pliki konfiguracyjne do folderu Assets .

  3. W konsoli Firebase, w procesie konfiguracji, kliknij Dalej .

Krok 4: Dodaj pakiety SDK Firebase Unity

  1. W konsoli Firebase kliknij Pobierz pakiet SDK Firebase Unity , a następnie rozpakuj pakiet SDK w dogodnym miejscu.

    • W dowolnej chwili możesz ponownie pobrać pakiet SDK Firebase Unity .

    • Zestaw SDK Firebase Unity nie jest specyficzny dla platformy.

  2. W otwartym projekcie Unity przejdź do opcji Zasoby > Importuj pakiet > Pakiet niestandardowy .

  3. Z rozpakowanego pakietu SDK wybierz obsługiwane produkty Firebase , których chcesz używać w swojej aplikacji.

    Aby zapewnić optymalne działanie Firebase Cloud Messaging, zalecamy włączenie Google Analytics w Twoim projekcie. Ponadto w ramach konfiguracji Analytics musisz dodać do swojej aplikacji pakiet Firebase dla Analytics.

    Analityka włączona

    • Dodaj pakiet Firebase dla Google Analytics: FirebaseAnalytics.unitypackage
    • Dodaj pakiet dla Firebase Cloud Messaging: FirebaseMessaging.unitypackage

    Analityka nie jest włączona

    Dodaj pakiet dla Firebase Cloud Messaging: FirebaseMessaging.unitypackage

  4. W oknie Importuj pakiet Unity kliknij opcję Importuj .

  5. W konsoli Firebase, w procesie konfiguracji, kliknij Dalej .

Krok 5: Potwierdź wymagania dotyczące wersji usług Google Play

Zestaw SDK Firebase Unity dla Androida wymaga usług Google Play , które muszą być aktualne, aby móc korzystać z zestawu SDK.

Dodaj następującą instrukcję using i kod inicjujący na początku aplikacji. Możesz sprawdzić i opcjonalnie zaktualizować Usługi Google Play do wersji wymaganej przez zestaw SDK Firebase Unity przed wywołaniem jakichkolwiek innych metod w zestawie SDK.

using Firebase.Extensions;
Firebase.FirebaseApp.CheckAndFixDependenciesAsync().ContinueWithOnMainThread(task => {
  var dependencyStatus = task.Result;
  if (dependencyStatus == Firebase.DependencyStatus.Available) {
    // Create and hold a reference to your FirebaseApp,
    // where app is a Firebase.FirebaseApp property of your application class.
       app = Firebase.FirebaseApp.DefaultInstance;

    // Set a flag here to indicate whether Firebase is ready to use by your app.
  } else {
    UnityEngine.Debug.LogError(System.String.Format(
      "Could not resolve all Firebase dependencies: {0}", dependencyStatus));
    // Firebase Unity SDK is not safe to use here.
  }
});

Twój projekt Unity jest zarejestrowany i skonfigurowany do korzystania z Firebase.

Włącz powiadomienia push na platformach Apple

Krok 1: Dodaj strukturę powiadomień dla użytkowników

  1. Kliknij projekt w Xcode, a następnie wybierz zakładkę Ogólne z obszaru Edytora .

  2. Przewiń w dół do opcji Połączone struktury i biblioteki , a następnie kliknij przycisk + , aby dodać strukturę.

  3. W wyświetlonym oknie przewiń do UserNotifications.framework , kliknij ten wpis, a następnie kliknij Dodaj .

Krok 2: Włącz powiadomienia push

  1. Kliknij projekt w Xcode, a następnie wybierz zakładkę Możliwości z obszaru Edytor .

  2. Przełącz opcję Powiadomienia push na wartość Włączone .

  3. Przewiń w dół do opcji Tryby tła , a następnie przełącz ją na opcję Włączone .

  4. Zaznacz pole wyboru Powiadomienia zdalne w obszarze Tryby tła .

Zainicjuj komunikację w chmurze Firebase

Biblioteka komunikatów w chmurze Firebase zostanie zainicjowana podczas dodawania programów obsługi zdarzeń TokenReceived lub MessageReceived .

Po inicjalizacji żądany jest token rejestracji dla instancji aplikacji klienckiej. Aplikacja otrzyma token ze zdarzeniem OnTokenReceived , który powinien zostać zbuforowany do późniejszego wykorzystania. Będziesz potrzebować tego tokena, jeśli chcesz kierować wiadomości na to konkretne urządzenie.

Ponadto, jeśli chcesz móc odbierać wiadomości przychodzące, musisz zarejestrować się w zdarzeniu OnMessageReceived .

Cała konfiguracja wygląda następująco:

public void Start() {
  Firebase.Messaging.FirebaseMessaging.TokenReceived += OnTokenReceived;
  Firebase.Messaging.FirebaseMessaging.MessageReceived += OnMessageReceived;
}

public void OnTokenReceived(object sender, Firebase.Messaging.TokenReceivedEventArgs token) {
  UnityEngine.Debug.Log("Received Registration Token: " + token.Token);
}

public void OnMessageReceived(object sender, Firebase.Messaging.MessageReceivedEventArgs e) {
  UnityEngine.Debug.Log("Received a new message from: " + e.Message.From);
}

Konfigurowanie działania punktu wejścia systemu Android

W systemie Android usługa Firebase Cloud Messaging jest dostarczana w pakiecie z niestandardową aktywnością punktu wejścia, która zastępuje domyślną UnityPlayerActivity . Jeśli nie używasz niestandardowego punktu wejścia, wymiana odbywa się automatycznie i nie musisz podejmować żadnych dodatkowych działań. Aplikacje, które nie korzystają z domyślnego działania punktu wejścia lub dostarczają własne Assets/Plugins/AndroidManifest.xml będą wymagały dodatkowej konfiguracji.

Wtyczka Firebase Cloud Messaging Unity na Androida jest dostarczana w zestawie z dwoma dodatkowymi plikami:

  • Assets/Plugins/Android/libmessaging_unity_player_activity.jar zawiera działanie o nazwie MessagingUnityPlayerActivity , które zastępuje standardową UnityPlayerActivity .
  • Assets/Plugins/Android/AndroidManifest.xml instruuje aplikację, aby używała MessagingUnityPlayerActivity jako punktu wejścia do aplikacji.

Pliki te są dostarczane, ponieważ domyślna UnityPlayerActivity nie obsługuje onStop , onRestart przejść w cyklu życia aktywności ani nie implementuje onNewIntent , który jest niezbędny, aby Firebase Cloud Messaging poprawnie obsługiwał wiadomości przychodzące.

Konfigurowanie niestandardowego działania punktu wejścia

Jeśli Twoja aplikacja nie korzysta z domyślnej UnityPlayerActivity musisz usunąć dostarczony AndroidManifest.xml i upewnić się, że niestandardowe działanie prawidłowo obsługuje wszystkie przejścia cyklu życia aktywności systemu Android (przykład, jak to zrobić pokazano poniżej). Jeśli Twoje niestandardowe działanie rozszerza UnityPlayerActivity możesz zamiast tego rozszerzyć com.google.firebase.MessagingUnityPlayerActivity , który implementuje wszystkie niezbędne metody.

Jeśli używasz niestandardowego działania i nie rozszerzasz com.google.firebase.MessagingUnityPlayerActivity , powinieneś zawrzeć w swoim działaniu następujące fragmenty.

/**
 * Workaround for when a message is sent containing both a Data and Notification payload.
 *
 * When the app is in the background, if a message with both a data and notification payload is
 * received the data payload is stored on the Intent passed to onNewIntent. By default, that
 * intent does not get set as the Intent that started the app, so when the app comes back online
 * it doesn't see a new FCM message to respond to. As a workaround, we override onNewIntent so
 * that it sends the intent to the MessageForwardingService which forwards the message to the
 * FirebaseMessagingService which in turn sends the message to the application.
 */
@Override
protected void onNewIntent(Intent intent) {
  Intent message = new Intent(this, MessageForwardingService.class);
  message.setAction(MessageForwardingService.ACTION_REMOTE_INTENT);
  message.putExtras(intent);
  message.setData(intent.getData());
  // For older versions of Firebase C++ SDK (< 7.1.0), use `startService`.
  // startService(message);
  MessageForwardingService.enqueueWork(this, message);
}

/**
 * Dispose of the mUnityPlayer when restarting the app.
 *
 * This ensures that when the app starts up again it does not start with stale data.
 */
@Override
protected void onCreate(Bundle savedInstanceState) {
  if (mUnityPlayer != null) {
    mUnityPlayer.quit();
    mUnityPlayer = null;
  }
  super.onCreate(savedInstanceState);
}

Nowe wersje Firebase C++ SDK (od 7.1.0) korzystają z JobIntentService , która wymaga dodatkowych modyfikacji w pliku AndroidManifest.xml .

<service android:name="com.google.firebase.messaging.MessageForwardingService"
     android:permission="android.permission.BIND_JOB_SERVICE"
     android:exported="false" >
</service>

Uwaga dotycząca dostarczania wiadomości w systemie Android

Gdy aplikacja w ogóle nie jest uruchomiona, a użytkownik kliknie powiadomienie, wiadomość nie jest domyślnie kierowana przez wbudowane wywołania zwrotne FCM. W tym przypadku ładunki komunikatów są odbierane poprzez Intent używaną do uruchomienia aplikacji.

Wiadomości otrzymane, gdy aplikacja działa w tle, zawierają treść pola powiadomień służącą do wypełnienia powiadomienia w zasobniku systemowym, ale treść powiadomienia nie będzie przekazywana do FCM. Oznacza to, że FirebaseMessage.Notification będzie mieć wartość null.

W podsumowaniu:

Stan aplikacji Powiadomienie Dane Obydwa
Pierwszoplanowy Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived
Tło Taca systemowa Firebase.Messaging.FirebaseMessaging.MessageReceived Powiadomienie: zasobnik systemowy
Dane: w dodatkach intencji.

Zapobiegaj automatycznej inicjalizacji

FCM generuje token rejestracyjny do kierowania na urządzenia. Po wygenerowaniu tokenu biblioteka przesyła identyfikator i dane konfiguracyjne do Firebase. Jeśli chcesz uzyskać wyraźną zgodę przed użyciem tokena, możesz uniemożliwić generowanie w czasie konfiguracji, wyłączając FCM (oraz w systemie Android Analytics). Aby to zrobić, dodaj wartość metadanych do pliku Info.plist (nie do pliku GoogleService-Info.plist ) na Apple lub do pliku AndroidManifest.xml na Androidzie:

Android

<?xml version="1.0" encoding="utf-8"?>
<application>
  <meta-data android:name="firebase_messaging_auto_init_enabled"
             android:value="false" />
  <meta-data android:name="firebase_analytics_collection_enabled"
             android:value="false" />
</application>

Szybki

FirebaseMessagingAutoInitEnabled = NO

Aby ponownie włączyć FCM, możesz wykonać wywołanie w czasie wykonywania:

Firebase.Messaging.FirebaseMessaging.TokenRegistrationOnInitEnabled = true;

Po ustawieniu ta wartość będzie obowiązywać po ponownym uruchomieniu aplikacji.

FCM umożliwia wysyłanie wiadomości zawierających głęboki link do Twojej aplikacji. Aby otrzymywać wiadomości zawierające precyzyjny link, musisz dodać nowy filtr intencji do działania obsługującego precyzyjne linki dla Twojej aplikacji. Filtr intencji powinien wychwytywać głębokie linki Twojej domeny. Jeśli Twoje wiadomości nie zawierają głębokiego linku, ta konfiguracja nie jest konieczna. W pliku AndroidManifest.xml:

<intent-filter>
  <action android:name="android.intent.action.VIEW"/>
  <category android:name="android.intent.category.DEFAULT"/>
  <category android:name="android.intent.category.BROWSABLE"/>
  <data android:host="CHANGE_THIS_DOMAIN.example.com" android:scheme="http"/>
  <data android:host="CHANGE_THIS_DOMAIN.example.com" android:scheme="https"/>
</intent-filter>

Możliwe jest również określenie symbolu wieloznacznego, aby filtr intencji był bardziej elastyczny. Na przykład:

<intent-filter>
  <action android:name="android.intent.action.VIEW"/>
  <category android:name="android.intent.category.DEFAULT"/>
  <category android:name="android.intent.category.BROWSABLE"/>
  <data android:host="*.example.com" android:scheme="http"/>
  <data android:host="*.example.com" android:scheme="https"/>
</intent-filter>

Gdy użytkownicy klikną powiadomienie zawierające link do określonego schematu i hosta, Twoja aplikacja rozpocznie działanie z tym filtrem intencji, aby obsłużyć link.

Następne kroki

Po skonfigurowaniu aplikacji klienckiej możesz wysyłać wiadomości podrzędne i tematyczne za pomocą Firebase. Aby dowiedzieć się więcej, zobacz przykład szybkiego startu , który demonstruje tę funkcjonalność.

Aby dodać inne, bardziej zaawansowane zachowanie do swojej aplikacji, zapoznaj się z przewodnikami dotyczącymi wysyłania wiadomości z serwera aplikacji:

Pamiętaj, że aby móc korzystać z tych funkcji, będziesz potrzebować implementacji serwera .