Konfigurowanie aplikacji klienckiej Komunikacja w chmurze Firebase (FCM) w Unity

Aby napisać aplikację klienta Firebase Cloud Messaging na wiele platform za pomocą Unity, użyj interfejsu API Firebase Cloud Messaging. Pakiet SDK Unity działa zarówno na Androidzie, jak i na urządzeniach Apple. W przypadku każdej z tych platform wymagana jest dodatkowa konfiguracja.

Zanim zaczniesz

Wymagania wstępne

  • Zainstaluj Unity 2021 LTS lub nowszą. Obsługa Unity 2020 została wycofana i nie będzie już aktywnie obsługiwana po następnej dużej aktualizacji. Wcześniejsze wersje mogą być zgodne, ale nie będą aktywnie obsługiwane.

  • (Dotyczy tylko platform Apple) Zainstaluj te elementy:

    • Xcode 13.3.1 lub nowsza wersja
    • CocoaPods w wersji 1.12.0 lub nowszej

  • Upewnij się, że Twój projekt Unity spełnia te wymagania:

    • iOS – jest kierowana na system iOS 13 lub nowszy.
    • W przypadku tvOS: docelowy tvOS 13 lub nowszy.
    • Na Androida – kieruj aplikację na poziom API 21 (Lollipop) lub wyższy.

  • Skonfiguruj urządzenie lub użyj emulatora, aby uruchomić projekt w Unity.

    • iOS lub tvOS – skonfiguruj urządzenie fizyczne, na którym będzie działać aplikacja, i wykonaj te czynności:

      • Uzyskaj klucz uwierzytelniający Apple Push Notification dla swojego konta Apple Developer.
      • Włącz powiadomienia push w XCode w sekcji Aplikacja > Możliwości.

    • Android – Emulatory muszą używać obrazu emulatora w Google Play.

Jeśli nie masz jeszcze projektu Unity, ale chcesz wypróbować produkt Firebase, możesz pobrać jeden z naszych próbnych przykładów kodu.

Krok 1. Utwórz projekt Firebase

Zanim dodasz Firebase do projektu Unity, musisz utworzyć projekt Firebase, który połączysz z projektem Unity. Więcej informacji o projektach Firebase znajdziesz w artykule Zrozumienie projektów Firebase.

Krok 2. Zarejestruj aplikację w Firebase

Możesz zarejestrować co najmniej 1 aplikację lub grę, aby połączyć ją z projektem Firebase.

  1. Otwórz konsolę Firebase.

  2. W centrum strony „Opis” projektu kliknij ikonę Unity (), aby uruchomić proces konfiguracji.

    Jeśli aplikacja została już dodana do projektu Firebase, kliknij Dodaj aplikację, aby wyświetlić opcje platformy.

  3. Wybierz cel kompilacji projektu Unity, który chcesz zarejestrować, lub wybierz opcję rejestracji obu celów jednocześnie.

  4. Wpisz identyfikatory platformy swojego projektu Unity.

    • W przypadku iOS: w polu Identyfikator pakietu na iOS wpisz identyfikator iOS Twojego projektu Unity.

    • Android – w polu Nazwa pakietu Androida wpisz identyfikator Androida Twojego projektu Unity.
      Terminy nazwa pakietu i identyfikator aplikacji są często używane zamiennie.

  5. (Opcjonalnie) Wpisz pseudonimy platformowe projektu Unity.
    Te pseudonimy to wewnętrzne identyfikatory ułatwiające pracę, które są widoczne tylko w konsoli Firebase.

  6. Kliknij Zarejestruj aplikację.

Krok 3. Dodaj pliki konfiguracji Firebase

  1. Pobierz pliki konfiguracji Firebase dla poszczególnych platform w procesie konfiguracji konsoli Firebase.

    • iOS – kliknij Pobierz plik GoogleService-Info.plist.

    • Android – kliknij Pobierz google-services.json.

  2. Otwórz okno Projekt w projekcie Unity, a potem przenieś pliki konfiguracji do folderu Assets.

  3. Wróć do konsoli Firebase i w procesie konfiguracji kliknij Dalej.

Krok 4. Dodaj pakiety SDK Firebase dla Unity

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

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

    • Pakiet SDK Firebase Unity nie jest związany z konkretną platformą.

  2. W otwartym projekcie Unity przejdź do Assets (Zasoby) i wybierz Import Package (Importuj pakiet) > Custom Package (Pakiet niestandardowy).

  3. W rozpakowanym pakiecie SDK wybierz obsługiwane usługi Firebase, których chcesz używać w aplikacji.

    Aby uzyskać optymalną jakość usługi Firebase Cloud Messaging, zalecamy włączenie w projekcie Google Analytics. W ramach konfigurowania Analytics musisz też dodać do aplikacji pakiet Firebase dla Analytics.

    Włączono kryterium Analytics

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

    Analytics nie jest włączona

    Dodaj pakiet dla Firebase Cloud Messaging: FirebaseMessaging.unitypackage

  4. W oknie Import Unity Package (Importuj pakiet Unity) kliknij Import (Importuj).

  5. Wróć do konsoli Firebase i w procesie konfiguracji kliknij Dalej.

Krok 5. Sprawdź wymagania dotyczące wersji Usług Google Play

Pakiet SDK Firebase Unity na Androida wymaga pakietu Google Play services, który musi być zaktualizowany, zanim będzie można używać pakietu SDK.

Na początku aplikacji dodaj instrukcję using i kod inicjowania. Przed wywołaniem innych metod w pakiecie SDK możesz sprawdzić, czy Google Play services jest równe wymaganej przez pakiet SDK Firebase Unity wersji, i jeśli nie, zaktualizować go.

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.

Przesyłanie klucza uwierzytelniania APNs do zespołu pomocy Apple

Prześlij klucz uwierzytelniania APNs do Firebase. Jeśli nie masz jeszcze klucza uwierzytelniania APNs, utwórz go w Apple Developer Member Center.

  1. W swoim projekcie w konsoli Firebase kliknij ikonę koła zębatego, wybierz Ustawienia projektu, a następnie otwórz kartę Komunikacja w chmurze.

  2. W sekcji Konfiguracja aplikacji na iOS kliknij Prześlij obok Klucz uwierzytelniania APNs.

  3. Przejdź do lokalizacji, w której został zapisany klucz, wybierz go i kliknij Otwórz. Dodaj identyfikator klucza (dostępny w Centrum dla deweloperów Apple) i kliknij Prześlij.

Włączanie powiadomień push na platformach Apple

Krok 1. Dodaj system powiadomień dla użytkowników

  1. Kliknij projekt w Xcode, a następnie na obszarze Edytujący kliknij kartę Ogólne.

  2. Przewiń w dół do sekcji Połączone platformy i biblioteki, a potem kliknij przycisk +, aby dodać platformę.

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

Krok 2. Włącz powiadomienia push

  1. Kliknij projekt w Xcode, a potem na obszarze Edytowanie kliknij kartę Możliwości.

  2. Przełącz Powiadomienia push w pozycję Wł..

  3. Przewiń w dół do sekcji Tryby w tle i ustaw przełącznik w pozycji Wł.

  4. W sekcji Tryby w tle zaznacz pole wyboru Powiadomienia zdalne.

Zainicjuj instancję Firebase Cloud Messaging

Biblioteka Firebase Cloud Message zostanie zainicjowana podczas dodawania elementów obsługi zdarzeń TokenReceived lub MessageReceived.

Podczas inicjowania żąda się tokenu rejestracji dla instancji aplikacji klienta. Aplikacja otrzyma token ze zdarzeniem OnTokenReceived, który powinien zostać zapisany w pamięci podręcznej na potrzeby późniejszego użycia. Będzie Ci on potrzebny, jeśli chcesz kierować wiadomości na konkretne urządzenie.

Jeśli chcesz otrzymywać wiadomości, musisz też zarejestrować się w zdarzeniu OnMessageReceived.

Cała konfiguracja wygląda tak:

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 punktu wejścia w aplikacji na Androida

Na Androidzie Firebase Cloud Messaging jest dostarczany z niestandardową aktywnością punktu wejścia, która zastępuje domyślną aktywność UnityPlayerActivity. Jeśli nie używasz niestandardowego punktu wejścia, ta zmiana zostanie wprowadzona automatycznie i nie musisz nic robić. Aplikacje, które nie korzystają z domyślnego punktu wejścia Aktywność lub które podają własne wartości Assets/Plugins/AndroidManifest.xml, wymagają dodatkowej konfiguracji.

W pakiecie z wtyczką Unity Firebase Cloud Messaging na Androida są dostarczane 2 dodatkowe pliki:

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

Te pliki zostały udostępnione, ponieważ domyślna właściwość UnityPlayerActivity nie obsługuje procesów onStop i przejścia w cyklu życia aktywności onRestart ani nie implementuje funkcji onNewIntent, która jest niezbędna do prawidłowej obsługi wiadomości przychodzących przez Firebase Cloud Messaging.

Konfigurowanie działania niestandardowego punktu wejścia

Jeśli Twoja aplikacja nie używa domyślnego UnityPlayerActivity, musisz usunąć dostarczony AndroidManifest.xml i upewnić się, że jej niestandardowa aktywność odpowiednio obsługuje wszystkie przejścia w cyklu życia aktywności Androida (poniżej znajdziesz przykład tego, jak to zrobić). Jeśli Twoja niestandardowa aktywność rozszerza klasę UnityPlayerActivity, możesz zamiast tego rozszerzyć klasę com.google.firebase.MessagingUnityPlayerActivity, która implementuje wszystkie niezbędne metody.

Jeśli używasz niestandardowej aktywności, a nie rozszerzasz klasy com.google.firebase.MessagingUnityPlayerActivity, musisz uwzględnić w niej te fragmenty kodu.

/**
 * 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 pakietu SDK Firebase w C++ (od wersji 7.1.0) korzystają z poziomu JobIntentService, co wymaga wprowadzenia 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 na urządzeniach z Androidem

Gdy aplikacja nie jest w ogóle uruchomiona, a użytkownik kliknie powiadomienie, wiadomość nie jest domyślnie kierowana przez wbudowane wywołania zwrotne FCM. W takim przypadku ładunki wiadomości są odbierane przez Intentużywany do uruchamiania aplikacji.

Wiadomości odbierane, gdy aplikacja działa w tle, mają treść w polu powiadomienia, która jest używana do wypełniania powiadomienia w obszarze powiadomień, ale treść tego powiadomienia nie jest przekazywana do FCM. Oznacza to, że FirebaseMessage.Notification będzie puste.

W skrócie:

Stan aplikacji Powiadomienie Dane Oba rodzaje
Pierwszy plan Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived
Tło obszar powiadomień. Firebase.Messaging.FirebaseMessaging.MessageReceived Powiadomienie: w obszarze powiadomień
Dane: w elementach dodatkowych intencji.

Zapobieganie automatycznej inicjalizacji

FCM generuje token rejestracji na potrzeby kierowania na urządzenia. Gdy wygenerowany zostanie token, biblioteka prześle do Firebase identyfikator i dane konfiguracji. Jeśli chcesz uzyskać wyraźną zgodę przed użyciem tokena, możesz zapobiec generowaniu go w momencie konfiguracji, wyłączając FCM (a w przypadku Androida – Analytics). Aby to zrobić, dodaj wartość metadanych do Info.plist (a nie GoogleService-Info.plist) w Apple lub 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>

Swift

FirebaseMessagingAutoInitEnabled = NO

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

Firebase.Messaging.FirebaseMessaging.TokenRegistrationOnInitEnabled = true;

Po ustawieniu ta wartość będzie się utrzymywać w przypadku ponownych uruchomień aplikacji.

FCM umożliwia wysyłanie wiadomości zawierających precyzyjny link do Twojej aplikacji. Aby otrzymywać wiadomości zawierające precyzyjny link, musisz dodać nowy filtr intencji do działania, które obsługuje precyzyjne linki do Twojej aplikacji. Filtr intencji powinien przechwytywać precyzyjne linki do Twojej domeny. Jeśli Twoje wiadomości nie zawierają precyzyjnego 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żesz też określić symbol wieloznaczny, aby zwiększyć elastyczność filtra intencji. 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 za pomocą filtra intencji, aby obsłużyć ten link.

Dalsze kroki

Po skonfigurowaniu aplikacji klienta możesz wysyłać wiadomości do urządzeń podrzędnych i wiadomości na tematy za pomocą Firebase. Aby dowiedzieć się więcej, zapoznaj się z przykładem pliku quickstart, który demonstruje tę funkcję.

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

Pamiętaj, że aby korzystać z tych funkcji, musisz mieć implementację serwera.