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

Aby napisać za pomocą Unity aplikację kliencką Komunikacja w chmurze Firebase, która działa na wielu platformach, użyj interfejsu API Komunikacji w chmurze Firebase (FCM). Pakiet Unity SDK działa zarówno na urządzenia z Androidem, jak i na urządzenia Apple, ale wymagana jest dodatkowa konfiguracja na każdej platformie.

Zanim zaczniesz

Wymagania wstępne

  • Zainstaluj Unity w wersji 2019.1 lub nowszej. Wcześniejsze wersje również mogą być zgodne, ale nie będą aktywnie obsługiwane. Obsługa Unity 2019.1 jest uważana za wycofaną i nie będzie aktywnie obsługiwana po kolejnej dużej wersji.

  • (Tylko platformy Apple) Zainstaluj te elementy:

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

  • Sprawdź, czy Twój projekt w Unity spełnia te wymagania:

    • iOS – jest kierowana na system iOS 11 lub nowszy.
    • tvOS – jest kierowana na system tvOS w wersji 12 lub nowszej
    • Android – kierowanie na interfejs API na poziomie 19 (KitKat) lub wyższym

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

    • iOS lub tvOS – skonfiguruj urządzenie fizyczne do uruchomienia aplikacji i wykonaj te czynności:

      • Uzyskaj klucz uwierzytelniania Apple Push Notification na swoim koncie dewelopera Apple.
      • Włącz powiadomienia push w XCode w sekcji App > Capabilities (Aplikacja > Funkcje).

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

Jeśli nie masz jeszcze projektu Unity, a chcesz tylko wypróbować usługę Firebase, możesz pobrać krótkie wprowadzenie (przykłady).

Krok 1. Utwórz projekt Firebase

Zanim dodasz Firebase do projektu w Unity, musisz utworzyć projekt Firebase i połączyć go z tym projektem w Unity. W artykule Omówienie projektów Firebase dowiesz się więcej o projektach Firebase.

Krok 2. Zarejestruj aplikację w Firebase

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

  1. Otwórz konsolę Firebase.

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

    Jeśli masz już aplikację dodaną do projektu Firebase, kliknij Dodaj aplikację, aby wyświetlić opcje platformy.

  3. Wybierz środowisko docelowe kompilacji swojego projektu w Unity, które chcesz zarejestrować. Możesz też zarejestrować oba środowiska docelowe jednocześnie.

  4. Wpisz identyfikatory projektów Unity dla danej platformy.

    • iOS – wpisz identyfikator iOS projektu Unity w polu Identyfikator pakietu na iOS.

    • Na urządzeniu z Androidem – w polu Nazwa pakietu na Androida wpisz identyfikator Androida projektu Unity.
      Terminy nazwa pakietu i identyfikator aplikacji są często używane wymiennie.

  5. (Opcjonalnie) Wpisz pseudonimy związane z platformą projektu Unity.
    Te pseudonimy to wewnętrzne, wygodne identyfikatory, które są widoczne tylko dla Ciebie w konsoli Firebase.

  6. Kliknij Zarejestruj aplikację.

Krok 3. Dodaj pliki konfiguracji Firebase

  1. Uzyskaj pliki konfiguracji Firebase dotyczące konkretnej platformy w procesie konfiguracji konsoli Firebase.

    • iOS – kliknij Pobierz GoogleService-Info.plist.

    • Android – kliknij Pobierz google-services.json.

  2. Otwórz okno Project(Projekt) w projekcie Unity, a następnie przenieś pliki konfiguracyjne do folderu Assets.

  3. Gdy wrócisz do konsoli Firebase, w procesie konfiguracji kliknij Dalej.

Krok 4. Dodaj pakiety SDK Firebase Unity

  1. W konsoli Firebase kliknij Pobierz pakiet Firebase Unity SDK i rozpakuj pakiet SDK w dowolnym miejscu.

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

    • 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 zapewnić optymalne działanie Komunikacji w chmurze Firebase (FCM), zalecamy włączenie Google Analytics w projekcie. Podczas konfigurowania Analytics musisz też dodać do swojej aplikacji pakiet Firebase dla Analytics.

    Analityka włączona

    • Dodaj pakiet Firebase dla Google Analytics: FirebaseAnalytics.unitypackage
    • Dodaj pakiet do Komunikacji w chmurze Firebase: FirebaseMessaging.unitypackage

    Statystyki nie są włączone

    Dodaj pakiet do Komunikacji w chmurze Firebase: FirebaseMessaging.unitypackage

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

  5. Gdy wrócisz do konsoli Firebase, w procesie konfiguracji kliknij Dalej.

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

Pakiet SDK Firebase Unity SDK na Androida wymaga Usług Google Play, które muszą być aktualne, aby można było korzystać z pakietu SDK.

Na początku aplikacji dodaj instrukcję using i kod inicjowania. Możesz sprawdzić, czy Usługi Google Play są w wersji wymaganej przez pakiet Firebase Unity SDK, i opcjonalnie zaktualizować je do wersji wymaganej przed wywołaniem innych metod w pakiecie 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 w Unity jest zarejestrowany i skonfigurowany do używania Firebase.

Włącz powiadomienia push na platformach Apple

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

  1. Kliknij projekt w Xcode, a następnie w obszarze edytora wybierz kartę General (Ogólne).

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

  3. W wyświetlonym oknie przewiń do sekcji UserPowiadomienia.framework, kliknij ten wpis i wybierz Dodaj.

Krok 2. Włącz powiadomienia push

  1. Kliknij projekt w Xcode, a następnie w obszarze edytora wybierz kartę Capabilities (Możliwości).

  2. Ustaw Powiadomienia push w pozycji Włączone.

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

  4. Zaznacz pole wyboru Powiadomienia zdalne w sekcji Tryby w tle.

Inicjowanie Komunikacji w chmurze Firebase (FCM)

Biblioteka wiadomości w chmurze Firebase zostanie zainicjowana podczas dodawania modułów obsługi zdarzeń TokenReceived lub MessageReceived.

Podczas zainicjowania instancji aplikacji klienckiej wysyłane jest żądanie tokena rejestracji. Aplikacja otrzyma token ze zdarzeniem OnTokenReceived, który należy zapisać w pamięci podręcznej do późniejszego użycia. Będzie Ci on potrzebny, jeśli chcesz kierować wiadomości na konkretne urządzenie.

Musisz też zarejestrować się na wydarzenie OnMessageReceived, jeśli chcesz otrzymywać wiadomości przychodzące.

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 aktywności punktu wejścia Androida

Na Androidzie Komunikacja w chmurze Firebase (FCM) jest w pakiecie z niestandardową aktywnością punktu wejścia, która zastępuje domyślną funkcję UnityPlayerActivity. Jeśli nie używasz niestandardowego punktu wejścia, zastąpienie następuje automatycznie i nie musisz nic więcej robić. Aplikacje, które nie używają domyślnego punktu wejścia Aktywność lub dostarczają własne Assets/Plugins/AndroidManifest.xml, będą wymagać dodatkowej konfiguracji.

Do wtyczki Firebase Cloud Messaging Unity na Androida dostajesz 2 dodatkowe pliki:

  • 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 nakazuje aplikacji używanie MessagingUnityPlayerActivity jako punktu wejścia do niej.

Te pliki są udostępniane, ponieważ domyślna UnityPlayerActivity nie obsługuje procesów onStop i 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 elementu UnityPlayerActivity, musisz usunąć podany element AndroidManifest.xml i upewnić się, że niestandardowa aktywność prawidłowo obsługuje wszystkie przejścia w cyklu życia aktywności na Androidzie (przykład znajdziesz poniżej). Jeśli Twoje działanie niestandardowe obejmuje zakres UnityPlayerActivity, możesz zamiast tego rozszerzyć zakres com.google.firebase.MessagingUnityPlayerActivity, który implementuje wszystkie niezbędne metody.

Jeśli używasz aktywności niestandardowej bez rozszerzenia com.google.firebase.MessagingUnityPlayerActivity, uwzględnij w swojej aktywności 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 C++ (od wersji 7.1.0) używają parametru JobIntentService, który 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 na temat dostarczania wiadomości w Androidzie

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

W wiadomościach odbieranych, gdy aplikacja działa w tle, zawartość pola powiadomień jest wypełniana w obszarze powiadomień w obszarze powiadomień, ale treść tych powiadomień nie jest przekazywana do FCM. Oznacza to, że FirebaseMessage.Notification ma wartość null.

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 Zasobnik systemowy Firebase.Messaging.FirebaseMessaging.MessageReceived Powiadomienie: w obszarze powiadomień
Dane: w elementach dodatkowych intencji.

Zapobiegaj automatycznemu inicjowaniu

FCM generuje token rejestracji na potrzeby kierowania na urządzenia. Po wygenerowaniu tokena biblioteka przesyła identyfikator i dane konfiguracji do Firebase. Jeśli przed użyciem tokena chcesz uzyskać wyraźną zgodę, możesz zapobiec generowaniu danych podczas konfiguracji, wyłączając FCM (a na Androidzie i w Analytics). Aby to zrobić, dodaj wartość metadanych do Info.plist (nie GoogleService-Info.plist) na urządzeniu Apple lub do 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 wykonać wywołanie w czasie działania aplikacji:

Firebase.Messaging.FirebaseMessaging.TokenRegistrationOnInitEnabled = true;

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

FCM zezwala na 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 w Twojej aplikacji. Filtr intencji powinien przechwytywać precyzyjne linki w Twojej domenie. Jeśli 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>

Aby zwiększyć elastyczność filtra intencji, możesz też określić symbol wieloznaczny. 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żytkownik kliknie powiadomienie zawierające link do określonego schematu i hosta, aplikacja rozpocznie aktywność za pomocą tego filtra intencji, aby obsłużyć link.

Dalsze kroki

Po skonfigurowaniu aplikacji klienckiej możesz wysyłać w Firebase wiadomości podrzędne i wiadomości tematyczne. Więcej informacji znajdziesz w krótkim wprowadzeniu, w którym omówiono tę funkcję.

Aby dodać do aplikacji inne, bardziej zaawansowane funkcje, zapoznaj się z przewodnikami po wysyłaniu wiadomości z serwera aplikacji:

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