Wprowadzenie do Komunikacji w chmurze Firebase w aplikacjach w Unity

Z tego przewodnika dowiesz się, jak zacząć korzystać z Firebase Cloud Messaging w aplikacjach klienckich Unity, aby niezawodnie wysyłać wiadomości.

Aby napisać aplikację kliencką Firebase Cloud Messaging na wielu platformach w Unity, użyj interfejsu API Firebase Cloud Messaging. Pakiet SDK Unity działa zarówno na Androidzie, jak i na urządzeniach Apple, ale na każdej platformie wymaga dodatkowej konfiguracji.

Zanim zaczniesz

Wymagania wstępne

• Zainstaluj Unity 2021 LTS lub nowszą wersję. Wcześniejsze wersje też mogą być zgodne, ale nie będą aktywnie obsługiwane.

• (Tylko platformy Apple) Zainstaluj te elementy:

  • Xcode 26.2 lub nowszy,
  • CocoaPods w wersji 1.12.0 lub nowszej,

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

  • Na urządzeniu z iOS – kieruje reklamy na urządzenia z systemem iOS 15 lub nowszym.
  • tvOS – kierowanie na tvOS 15 lub nowszy.
  • Android – kierowanie na interfejs API na poziomie 24 (Nougat) 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ć Twoja 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ą korzystać z obrazu emulatora z Google Play.

Jeśli nie masz jeszcze projektu Unity i chcesz tylko wypróbować usługę Firebase, możesz pobrać jeden z naszych przykładów z krótkiego przewodnika.

Krok 1. Utwórz projekt w Firebase

Zanim dodasz Firebase do projektu Unity, musisz utworzyć projekt Firebase, aby połączyć go z projektem Unity. Więcej informacji o projektach w Firebase znajdziesz w artykule Informacje o projektach 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 przeglądu projektu kliknij ikonę Unity (plat_unity), aby uruchomić proces konfiguracji.

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

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

4. Wpisz identyfikatory projektu Unity na poszczególnych platformach.

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

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

   Gdzie znajdziesz identyfikator projektu Unity?

   Otwórz projekt Unity w środowisku IDE Unity, a następnie przejdź do sekcji ustawień dla każdej platformy:

   • iOS – kliknij Ustawienia kompilacji > iOS.

   • Android – kliknij Android > Player Settings > Other Settings (Android > Ustawienia odtwarzacza > Inne ustawienia).

   Identyfikator projektu Unity to wartość Identyfikator pakietu (przykładowy identyfikator: com.yourcompany.yourproject).

5. (Opcjonalnie) Wpisz nazwy projektu Unity na poszczególnych platformach.
   Te pseudonimy są wewnętrznymi identyfikatorami ułatwiającymi pracę i są widoczne tylko dla Ciebie w Firebase konsoli.

6. Kliknij Zarejestruj aplikację.

Krok 3. Dodaj pliki konfiguracyjne Firebase

1. Uzyskaj pliki konfiguracji Firebase dla swojej platformy w ramach procesu konfiguracji konsoli Firebase.

   • iOS – kliknij Pobierz GoogleService-Info.plist.

   • Android – kliknij Pobierz google-services.json.

   Co musisz wiedzieć o tym pliku konfiguracji?

   • Plik konfiguracyjny Firebase zawiera unikalne, ale nie tajne identyfikatory projektu i aplikacji. Więcej informacji o tym pliku konfiguracyjnym znajdziesz w artykule Informacje o projektach Firebase.

   • W każdej chwili możesz ponownie pobrać plik konfiguracyjny Firebase.

   • Sprawdź, czy nazwa pliku konfiguracyjnego nie zawiera dodatkowych znaków, np. (2).

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

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

Krok 4. Dodaj pakiety Firebase Unity SDK

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

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

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

2. W otwartym projekcie Unity kliknij Assets (Zasoby) > 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 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.

   Model Analytics został włączony

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

   Analytics nie jest włączony

   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 procesie 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, Google Play services musi być aktualna.

Dodaj na początku aplikacji instrukcję using i kod inicjowania. Zanim wywołasz inne metody 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.
  }
});

Twój projekt Unity jest zarejestrowany i skonfigurowany do korzystania z Firebase.

Konfigurowanie platform Apple

Aby skonfigurować FCM na platformach Unity i Apple, postępuj zgodnie z podanymi niżej instrukcjami.

Przesyłanie klucza uwierzytelniania APNs

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 konsoli Firebase kliknij settings Ustawienia > Ogólne. Następnie kliknij kartę Komunikacja w chmurze.
2. W sekcji Klucz uwierzytelniania APNs w obszarze Konfiguracja aplikacji na iOS kliknij Prześlij, aby przesłać klucz uwierzytelniania programistycznego lub klucz uwierzytelniania produkcyjnego (albo oba te klucze). Trzeba podać co najmniej 1 formę kontaktu.
3. Przejdź do lokalizacji, w której zapisano 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

1. Kliknij projekt w Xcode, a następnie wybierz kartę General (Ogólne) w obszarze edytora.
2. Przewiń do sekcji Linked Frameworks and Libraries (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 następnie kliknij Add (Dodaj).
4. Kliknij swój projekt w Xcode, a następnie wybierz kartę Capabilities (Możliwości) w obszarze edytora.
5. Ustaw Powiadomienia push w pozycji Włączone.
6. Przewiń do opcji Tryby w tle i włącz ją.
7. W sekcji Tryby działania w tle zaznacz pole wyboru Powiadomienia zdalne.

Zainicjuj Firebase Cloud Messaging

Włączanie rejestracji za pomocą identyfikatora instalacji Firebase

Aby umożliwić rejestrowanie instancji aplikacji w Firebase Cloud Messaging za pomocą identyfikatora instalacji Firebase (FID), musisz najpierw włączyć identyfikatory FID w konfiguracji aplikacji na platformach Android i Apple:

<meta-data android:name="firebase_messaging_installation_id_enabled"
           android:value="true" />

FirebaseMessagingInstallationIdEnabled = YES

Rejestracja na wydarzenia FCM

Biblioteka Firebase Cloud Messaging zostanie zainicjowana podczas dodawania modułów obsługi zdarzeń RegistrationReceived lub MessageReceived.

Podczas inicjowania Firebase Cloud Messaging rejestruje instancję aplikacji klienta, aby otrzymywać wiadomości za pomocą identyfikatora instalacji Firebase (FID). Aplikacja otrzymuje identyfikator FID ze zdarzeniem RegistrationReceived, które należy zapisać w pamięci podręcznej na serwerze, aby kierować wiadomości na to konkretne urządzenie.

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

Konfiguracja będzie wyglądać tak:

public void Start() {
  Firebase.Messaging.FirebaseMessaging.RegistrationReceived +=
      OnRegistrationReceived;
  Firebase.Messaging.FirebaseMessaging.MessageReceived +=
      OnMessageReceived;
}

public void OnRegistrationReceived(
    object sender,
    Firebase.Messaging.RegistrationReceivedEventArgs e) {
  UnityEngine.Debug.Log("Received Firebase Installation ID: " +
                        e.InstallationId);
  // TODO: Send the Firebase Installation ID (FID) to your app server to target
  // this device for messages.
}

public void OnMessageReceived(
    object sender,
    Firebase.Messaging.MessageReceivedEventArgs e) {
  UnityEngine.Debug.Log("Received a new message from: " + e.Message.From);
}

Po uzyskaniu identyfikatora instalacji Firebase wyślij go na serwer aplikacji i zapisz za pomocą wybranej metody.

Ręczna rejestracja, gdy automatyczna inicjalizacja jest wyłączona

Rejestrację możesz też wywołać ręcznie za pomocą FCM w czasie działania programu, używając tego kodu:RegisterAsync()

// Manually register with FCM
Firebase.Messaging.FirebaseMessaging.RegisterAsync().ContinueWith(task => {
  if (task.IsCompleted) {
    // Note: The registered Installation ID is delivered to the
    // RegistrationReceived event handler.
    UnityEngine.Debug.Log("Registered with FCM");
  }
});

Uzyskiwanie dostępu do tokena rejestracji FCM (wycofane)

Jeśli Twoja aplikacja nadal używa wycofanych interfejsów API tokenów, możesz nasłuchiwać TokenReceived:

// Deprecated: Use RegistrationReceived instead
public void Start() {
  Firebase.Messaging.FirebaseMessaging.TokenReceived += OnTokenReceived;
}

public void OnTokenReceived(
    object sender,
    Firebase.Messaging.TokenReceivedEventArgs token) {
  UnityEngine.Debug.Log("Received Registration Token: " + token.Token);
}

Konfigurowanie platform Androida

Aby skonfigurować FCM na platformach Unity i Android, postępuj zgodnie z tymi instrukcjami.

Konfigurowanie aktywności punktu wejścia Androida

Firebase Cloud Messaging zawiera niestandardową aktywność punktu wejścia, która zastępuje domyślną aktywność UnityPlayerActivity. Jeśli nie używasz niestandardowego punktu wejścia, zastąpienie następuje automatycznie i nie musisz podejmować żadnych dodatkowych działań.

Wtyczka Unity Firebase Cloud Messaging na Androida zawiera 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 informuje aplikację, że ma używać MessagingUnityPlayerActivity jako punktu wejścia do aplikacji.

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

Konfigurowanie aktywności niestandardowego punktu wejścia

Jeśli Twoja aplikacja nie korzysta z domyślnego UnityPlayerActivity, musisz usunąć dostarczony AndroidManifest.xml i upewnić się, że Twoja niestandardowa aktywność prawidłowo obsługuje wszystkie przejścia cyklu życia aktywności na Androidzie (przykład, jak to zrobić, znajdziesz poniżej). Jeśli Twoja aktywność niestandardowa 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 i nie rozszerzasz com.google.firebase.MessagingUnityPlayerActivity, w aktywności 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 earlier 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 makes sure 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 Firebase C++ SDK (od wersji 7.1.0) używają JobIntentService, co wymaga dodatkowych zmian w pliku AndroidManifest.xml.

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

Dostarczanie wiadomości na Androidzie

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

Wiadomości otrzymane, gdy aplikacja działa w tle, mają treść pola powiadomienia, która jest używana do wypełnienia powiadomienia w obszarze powiadomień, ale ta treść powiadomienia nie zostanie przekazana do FCM. Oznacza to, że FirebaseMessage.Notification będzie mieć wartość null.

W skrócie:

Obsługa wiadomości z precyzyjnymi linkami na Androidzie

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 aktywności, która obsługuje precyzyjne linki w aplikacji. Filtr intencji powinien przechwytywać precyzyjne linki z Twojej domeny. 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 określonego przez Ciebie schematu i hosta, aplikacja rozpocznie działanie z tym filtrem intencji, aby obsłużyć link.

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). Możesz dodać wartość metadanych do Info.plist (nie do GoogleService-Info.plist) na urządzeniu Apple lub do AndroidManifest.xml na urządzeniu z Androidem:

<?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>

FirebaseMessagingAutoInitEnabled = NO

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

Firebase.Messaging.FirebaseMessaging.RegistrationOnInitEnabled = true;

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

Dalsze kroki

Po wykonaniu czynności konfiguracyjnych możesz skorzystać z tych opcji, aby kontynuować pracę z FCM w Unity:

• Wysyłanie wiadomości na urządzenia
• Odbieranie wiadomości w kliencie Unity
• Wysyłanie wiadomości dotyczących tematów