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 Unity SDK działa zarówno na Androidzie, jak i na urządzeniach Apple. W przypadku każdej platformy wymagana jest jednak 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 w wersji 13.3.1 lub nowszej
    • CocoaPods w wersji 1.12.0 lub nowszej

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

    • Na urządzeniach z iOS – wersja na iOS 13 lub nowszy
    • W przypadku tvOS: docelowy tvOS 13 lub nowszy.
    • Na Androida – kieruj aplikację na poziom API 21 (Lollipop) lub wyższy.

  • Aby uruchomić projekt Unity, skonfiguruj urządzenie lub użyj emulatora.

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

      • Uzyskaj klucz uwierzytelniający powiadomienia push Apple na swoje konto Apple Developer.
      • Włącz powiadomienia push w XCode w sekcji Aplikacja > Możliwości.

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

Jeśli nie masz jeszcze projektu Unity, ale chcesz wypróbować produkt Firebase, możesz pobrać jeden z naszych próbnych projektó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. Aby dowiedzieć się więcej o projektach Firebase, zapoznaj się z artykułem 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 go w dogodnym miejscu.

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

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

  2. W otwartym projekcie Unity kliknij Zasoby > Importuj pakiet > Pakiet niestandardowy.

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

    Aby uzyskać optymalne wyniki w usłudze Firebase Cloud Messaging, zalecamy włączenie Google Analytics w projekcie. W ramach konfigurowania 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

    Analytics nie jest włączona

    Dodaj pakiet dla Firebase Cloud Messaging: FirebaseMessaging.unitypackage

  4. W oknie Importowanie pakietu dla Unity kliknij Importuj.

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

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

Niektóre produkty w pakiecie SDK Firebase Unity na Androida wymagają Google Play services. Dowiedz się, które produkty mają tę zależność. Zanim będzie można korzystać z tych usług, musisz zaktualizować aplikację Google Play services.

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 dostępna (opcjonalnie możesz też ją zaktualizować) 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.
  }
});

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 APN, utwórz go w Centrum dla deweloperów Apple.

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

  2. W sekcji Klucz uwierzytelniania APNs w sekcji 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  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 pozycji Wł..

  3. Przewiń w dół do sekcji Tryby działania w tle, a potem ustaw ją na Wł..

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

Inicjowanie 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. Potrzebujesz tego tokena, jeśli chcesz kierować wiadomości na to 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 aktywności punktu wejścia na Androidzie

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.

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

  • 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 są udostępniane, ponieważ domyślna usługa UnityPlayerActivity nie obsługuje przejść onStop i onRestart w cyklu życia aktywności ani nie implementuje funkcji onNewIntent, która jest niezbędna, aby usługa Firebase Cloud Messaging mogła prawidłowo obsługiwać przychodzące wiadomości.

Konfigurowanie niestandardowej aktywności punktu wejścia

Jeśli Twoja aplikacja nie używa domyślnego UnityPlayerActivity, musisz usunąć dostarczony AndroidManifest.xml i upewnić się, że Twoja 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 uruchomiona, a użytkownik kliknie powiadomienie, domyślnie wiadomość nie jest 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 jej treść 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: pasek systemowy
Dane: w dodatkowych informacjach 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 – też Analytics). Aby to zrobić, dodaj wartość metadanych do Info.plist (a nie GoogleService-Info.plist) w Apple lub do AndroidManifest.xml w 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ść jest zachowywana 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 aktywności, która obsługuje precyzyjne linki w aplikacji. Filtr intencji powinien przechwytywać precyzyjne linki do Twojej domeny. Jeśli Twoje wiadomości nie zawierają precyzyjnych linków, 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 tematyczne 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 do korzystania z tych funkcji musisz mieć implementację na serwerze.