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

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

Zanim zaczniesz

Wymagania wstępne

  • Zainstaluj Unity 2021 LTS lub nowszą. Obsługa Unity 2020 jest uznawana za przestarzałą i po kolejnej głównej wersji nie będzie już aktywnie obsługiwana. Wcześniejsze wersje mogą być również zgodne, ale nie będą aktywnie obsługiwane.

  • (Tylko platformy 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 w Unity spełnia te wymagania:

    • iOS – kierowanie na urządzenia z systemem iOS 13 lub nowszym.
    • tvOS – docelowa wersja tvOS to 13 lub nowsza.
    • W przypadku Androida – kierowanie na interfejs API na poziomie 21 (Lollipop) lub wyższym.

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

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

      • Uzyskaj klucz uwierzytelniania usługi Apple Push Notification na koncie dewelopera Apple.
      • Włącz powiadomienia push w XCode w sekcji App (Aplikacja) > Capabilities (Możliwości).

    • Android – emulatory muszą używać obrazu emulatora z Google Play.

Jeśli nie masz jeszcze projektu Unity, a chcesz tylko wypróbować usługę Firebase, możesz pobrać jeden z naszych przykładów kodu umożliwiających szybkie rozpoczęcie pracy.

Krok 1. Utwórz projekt Firebase

Zanim dodasz Firebase do projektu Unity, musisz utworzyć projekt Firebase, aby połączyć go z projektem Unity. Więcej informacji o projektach Firebase znajdziesz w artykule Informacje o projektach Firebase.

Krok 2. Zarejestruj aplikację w Firebase

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

  1. Otwórz Firebasekonsolę.

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

    Jeśli masz już aplikację w projekcie Firebase, kliknij Dodaj aplikację, aby wyświetlić opcje platformy.

  3. Wybierz cel kompilacji projektu Unity, który chcesz zarejestrować. Możesz też zarejestrować oba cele jednocześnie.

  4. Wpisz identyfikatory projektu Unity dla poszczególnych platform.

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

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

  5. (Opcjonalnie) Wpisz pseudonimy specyficzne dla platformy w projekcie Unity.
    Te pseudonimy są wewnętrznymi identyfikatorami ułatwiającymi pracę i są widoczne tylko w Firebase konsoli.

  6. Kliknij Zarejestruj aplikację.

Krok 3. Dodaj pliki konfiguracyjne Firebase

  1. Uzyskaj pliki konfiguracyjne Firebase dla konkretnej platformy w ramach Firebasekonfiguracji konsoli.

    • iOS – kliknij Pobierz GoogleService-Info.plist.

    • Android – kliknij Download google-services.json (Pobierz google-services.json).

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

  3. Wróć do konsoli Firebase i w przepływie pracy konfiguracji kliknij Dalej.

Krok 4. Dodaj pakiety SDK Firebase Unity

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

    • W dowolnym momencie możesz ponownie pobrać Firebase Unity SDK.

    • Pakiet SDK Firebase Unity nie jest przeznaczony dla konkretnej platformy.

  2. W otwartym projekcie Unity kliknij Assets (Zasoby) > Import Package (Importuj pakiet) > Custom Package (Własny pakiet).

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

    Aby korzystanie z usługi Firebase Cloud Messaging było jak najbardziej optymalne, zalecamy włączenie Google Analytics w projekcie. W ramach konfiguracji Analytics musisz też dodać do aplikacji pakiet Firebase dla Analytics.

    Włączono: Analytics

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

    Nie włączono Analytics

    Dodaj pakiet dla Firebase Cloud Messaging:FirebaseMessaging.unitypackage

  4. W oknie Import Unity Package (Importowanie pakietu dla Unity) kliknij Import (Importuj).

  5. Wróć do konsoli Firebase i w przepływie pracy konfiguracji kliknij Dalej.

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

Niektóre usługi w pakiecie Firebase Unity SDK na Androida wymagają Google Play services. Dowiedz się, które usługi mają tę zależność. Aby można było korzystać z tych usług, aplikacja Google Play services musi być aktualna.

Dodaj na początku aplikacji ten kod inicjowania i instrukcję using. Przed wywołaniem innych metod w pakiecie SDK możesz sprawdzić i opcjonalnie zaktualizować Google Play services do wymaganej wersji.

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.
  }
});

Projekt Unity jest zarejestrowany i skonfigurowany do korzystania z Firebase.

Prześlij klucz uwierzytelniania APNs do pomocy Apple

Prześlij klucz uwierzytelniania APNs do Firebase. Jeśli nie masz jeszcze klucza uwierzytelniania APNs, utwórz go w Centrum dla deweloperów Apple.

  1. W projekcie w Firebase konsoli kliknij ikonę koła zębatego, wybierz Ustawienia projektu, a następnie kliknij kartę Cloud Messaging.

  2. W sekcji Klucz uwierzytelniania APNs w obszarze Konfiguracja aplikacji na iOS kliknij przycisk Prześlij.

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

Włączanie powiadomień push na platformach Apple

Krok 1. Dodaj platformę powiadomień użytkownika

  1. W Xcode kliknij projekt, a następnie w obszarze edytora wybierz kartę 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 pozycji UserNotifications.framework, kliknij ją, a potem kliknij Dodaj.

Krok 2. Włącz powiadomienia push

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

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

  3. Przewiń w dół do sekcji Tryby tła i włącz ją.

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

Zainicjuj Firebase Cloud Messaging

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

Po zainicjowaniu wysyłane jest żądanie tokena rejestracji dla instancji aplikacji klienta. Aplikacja otrzyma token ze zdarzeniem OnTokenReceived, który należy zapisać w pamięci podręcznej do późniejszego wykorzystania. Ten token jest potrzebny, jeśli chcesz kierować wiadomości na to konkretne urządzenie.

Jeśli chcesz otrzymywać wiadomości przychodzące, musisz też zarejestrować się na wydarzenie 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 aktywności punktu wejścia Androida

Na Androidzie Firebase Cloud Messaging jest dostarczany z niestandardowym punktem wejścia, który zastępuje domyślny UnityPlayerActivity. Jeśli nie używasz niestandardowego punktu wejścia, ta zamiana nastąpi automatycznie i nie musisz podejmować żadnych dodatkowych działań. Aplikacje, które nie używają domyślnego punktu wejścia Activity lub dostarczają własny element Assets/Plugins/AndroidManifest.xml, wymagają dodatkowej konfiguracji.

Wtyczka Unity Firebase Cloud Messaging na Androida jest dostarczana z 2 dodatkowymi plikami:

  • Assets/Plugins/Android/libmessaging_unity_player_activity.jar zawiera działanie o nazwie MessagingUnityPlayerActivity, które zastępuje standardowe działanie UnityPlayerActivity.
  • Assets/Plugins/Android/AndroidManifest.xml informuje aplikację, że ma używać MessagingUnityPlayerActivity jako punktu wejścia.

Te pliki są udostępniane, ponieważ domyślny UnityPlayerActivity nie obsługuje onStop, onRestart przejść cyklu życia aktywności ani nie implementuje onNewIntent, co jest niezbędne do prawidłowego obsługiwania przychodzących wiadomości przez Firebase Cloud Messaging.

Konfigurowanie niestandardowego punktu wejścia Activity

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

Jeśli używasz niestandardowego działania i nie rozszerzasz elementu com.google.firebase.MessagingUnityPlayerActivity, w działaniu powinny się znaleźć 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++ (7.1.0 i nowsze) używają JobIntentService, co wymaga dodatkowych modyfikacji w pliku AndroidManifest.xml.

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

Uwaga dotycząca dostarczania wiadomości na Androidzie

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 za pomocą Intent, które służy do uruchamiania aplikacji.

Wiadomości otrzymane, gdy aplikacja działa w tle, mają treść pola powiadomienia używaną do wypełniania powiadomienia w obszarze powiadomień, ale ta treść powiadomienia nie będzie przekazywana do FCM. Oznacza to, że FirebaseMessage.Notification będzie wartością 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 Obszar powiadomień Firebase.Messaging.FirebaseMessaging.MessageReceived Powiadomienie: zasobnik systemowy
Dane: w dodatkach do intencji.

Zapobieganie automatycznej inicjalizacji

FCM generuje token rejestracji na potrzeby kierowania na urządzenia. Gdy token zostanie wygenerowany, biblioteka przesyła identyfikator i dane konfiguracyjne do Firebase. Jeśli przed użyciem tokena chcesz uzyskać wyraźną zgodę użytkownika, możesz zapobiec jego wygenerowaniu w momencie konfiguracji, wyłączając FCM (a na Androidzie także Analytics). Aby to zrobić, dodaj wartość metadanych do regionu Info.plist (nie do regionu GoogleService-Info.plist) na urządzeniu Apple lub do regionu AndroidManifest.xml na urządzeniu z Androidem:

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 programu:

Firebase.Messaging.FirebaseMessaging.TokenRegistrationOnInitEnabled = true;

Po ustawieniu ta wartość jest zachowywana po ponownym uruchomieniu aplikacji.

FCM umożliwia wysyłanie wiadomości zawierających precyzyjny link do 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 wykrywać 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 filtr intencji był bardziej elastyczny. 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 schematu i hosta, które określisz, Twoja aplikacja rozpocznie działanie z tym filtrem intencji, aby obsłużyć link.

Dalsze kroki

Po skonfigurowaniu aplikacji klienta możesz wysyłać wiadomości do poszczególnych urządzeń i tematów za pomocą Firebase. Więcej informacji znajdziesz w przykładowym przewodniku, który pokazuje tę funkcję.

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

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