了解 2023 年 Google I/O 大会上介绍的 Firebase 亮点。了解详情

Skonfiguruj aplikację kliencką Firebase Cloud Messaging w Unity

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

Zanim zaczniesz

Wymagania wstępne

  • Zainstaluj Unity 2019.1 lub nowszy. Wcześniejsze wersje mogą być również 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 następnej głównej wersji.

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

    • Xcode 13.3.1 lub nowszy
    • CocoaPods 1.10.0 lub nowszy

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

    • Dla iOS — celuje w system iOS 11 lub nowszy
    • Dla systemu tvOS — jest przeznaczony dla systemu tvOS 12 lub nowszego
    • Dla Androida — celuje w API na poziomie 19 (KitKat) lub wyższym

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

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

      • Uzyskaj klucz Apple Push Notification Authentication Key dla swojego konta programisty Apple .
      • Włącz powiadomienia push w XCode w obszarze App > Capabilities .

    • Dla Androida — emulatory muszą używać obrazu emulatora z Google Play.

Jeśli nie masz jeszcze projektu Unity i chcesz tylko wypróbować produkt Firebase, możesz pobrać jedną z naszych próbek 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ę 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ć proces konfiguracji.

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

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

  4. Wprowadź identyfikatory specyficzne dla platformy projektu Unity.

    • Dla 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 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 konfiguracyjne Firebase

  1. Uzyskaj pliki konfiguracyjne Firebase specyficzne dla platformy w przepływie pracy konfiguracji konsoli Firebase.

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

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

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

  3. Wróć do konsoli Firebase, w przepływie pracy instalacji kliknij Dalej .

Krok 4. Dodaj zestawy SDK Firebase Unity

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

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

    • Pakiet Firebase Unity SDK nie jest specyficzny dla platformy.

  2. W otwartym projekcie Unity przejdź do pozycji Assets > Import Package > Custom Package .

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

    Aby zapewnić optymalne działanie usługi Firebase Cloud Messaging, zalecamy włączenie Google Analytics w Twoim projekcie. Ponadto w ramach konfigurowania 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 przycisk Importuj .

  5. Wróć do konsoli Firebase, w przepływie pracy instalacji kliknij Dalej .

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

Pakiet SDK Firebase Unity na Androida wymaga usług Google Play , które muszą być aktualne, zanim będzie można korzystać z pakietu SDK.

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

Firebase.FirebaseApp.CheckAndFixDependenciesAsync().ContinueWith(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 ramkę powiadomień użytkownika

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

  2. Przewiń w dół do Linked Frameworks and Libraries , a następnie kliknij przycisk + , aby dodać platformę.

  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 kartę Możliwości z obszaru Edytora .

  2. Przełącz Powiadomienia push na Włączone .

  3. Przewiń w dół do Tryby w tle , a następnie przełącz na Wł .

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

Zainicjuj obsługę wiadomości w chmurze Firebase

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

Podczas inicjowania żądany jest token rejestracji dla wystąpienia aplikacji klienckiej. Aplikacja otrzyma token ze zdarzeniem OnTokenReceived , które powinno zostać zapisane w pamięci podręcznej do późniejszego użycia. Będziesz potrzebować tego tokena, jeśli chcesz kierować wiadomości na to konkretne urządzenie.

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

Cały setup 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 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 korzystasz z niestandardowego punktu wejścia, zamiana 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 Plugin na Androida jest dostarczana w pakiecie z dwoma dodatkowymi plikami:

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

Te pliki są udostępniane, ponieważ domyślna UnityPlayerActivity nie obsługuje przejść cyklu życia aktywności onStop , onRestart ani nie implementuje onNewIntent , który jest niezbędny, aby usługa Firebase Cloud Messaging poprawnie obsługiwała wiadomości przychodzące.

Konfigurowanie niestandardowego punktu wejścia Działanie

Jeśli Twoja aplikacja nie korzysta z domyślnej UnityPlayerActivity musisz usunąć dostarczony AndroidManifest.xml i upewnić się, że Twoja niestandardowa aktywność prawidłowo obsługuje wszystkie przejścia cyklu życia działania systemu Android (przykład, jak to zrobić, pokazano 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 korzystasz z niestandardowego działania i nie rozszerzasz com.google.firebase.MessagingUnityPlayerActivity , powinieneś dołączyć do działania następujące 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 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 na Androidzie

Gdy aplikacja w ogóle nie działa, a użytkownik dotknie powiadomienia, wiadomość domyślnie nie jest kierowana przez wbudowane wywołania zwrotne FCM. W takim przypadku ładunki komunikatów są odbierane za pośrednictwem Intent używanej do uruchamiania aplikacji.

Wiadomości otrzymane, gdy aplikacja działa w tle, mają zawartość swojego pola powiadomienia używaną do wypełnienia powiadomienia w zasobniku systemowym, ale ta treść powiadomienia nie zostanie przekazana do FCM. Oznacza to, że FirebaseMessage.Notification będzie miało 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 rejestracji na potrzeby kierowania na urządzenia. Po wygenerowaniu tokena biblioteka przesyła identyfikator i dane konfiguracyjne do Firebase. Jeśli chcesz uzyskać wyraźną zgodę przed użyciem tokena, możesz zapobiec generowaniu w czasie konfiguracji, wyłączając FCM (oraz w Androidzie, Analytics). Aby to zrobić, dodaj wartość metadanych do Info.plist (nie GoogleService-Info.plist ) na 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>

Szybki

FirebaseMessagingAutoInitEnabled = NO

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

Firebase.Messaging.FirebaseMessaging.TokenRegistrationOnInitEnabled = true;

Ta wartość utrzymuje się po ponownym uruchomieniu 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 obsługującego precyzyjne linki do Twojej aplikacji. Filtr intencji powinien przechwytywać precyzyjne linki z Twojej domeny. Jeśli Twoje wiadomości nie zawierają głębokiego linku, ta konfiguracja nie jest konieczna. W 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 dotkną powiadomienia zawierającego link do określonego schematu i hosta, 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ę funkcję.

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

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