Wprowadzenie do Komunikacji w chmurze Firebase


Ten przewodnik zawiera informacje o konfigurowaniu Firebase Cloud Messaging w aplikacjach klienckich na urządzenia mobilne i w internecie, aby można było niezawodnie wysyłać wiadomości. W przypadku środowisk serwerowych zapoznaj się z sekcją Środowisko serwerowe i FCM.

Konfigurowanie Firebase Cloud Messagingaplikacji klienckiej w Unity

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

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 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 poszczególnych platform w ramach Firebaseprocesu konfiguracji konsoli.

    • iOS – kliknij Pobierz GoogleService-Info.plist.

    • Android – kliknij 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ć, czy Google Play services jest w wymaganej wersji, i w razie potrzeby zaktualizować ją do tej 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.

Konfigurowanie platform Apple

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

Prześlij klucz uwierzytelniający APNs

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 Konfiguracji aplikacji na iOS kliknij przycisk Prześlij, aby przesłać klucz uwierzytelniania środowiska deweloperskiego lub klucz uwierzytelniania środowiska produkcyjnego albo oba te klucze. Wymagany jest co najmniej 1 element.

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

Włączanie powiadomień push na platformach Apple

  1. W Xcode kliknij projekt, a następnie w obszarze edytora wybierz kartę Ogólne.
  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 potem kliknij Dodaj.
  4. W Xcode kliknij projekt, a następnie w obszarze edytora wybierz kartę Capabilities (Możliwości).
  5. Ustaw przełącznik Powiadomienia push w pozycji Włączone.
  6. Przewiń do sekcji Tryby tła i włącz ją.
  7. 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 użycia. 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.

Konfiguracja będzie 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 platform Androida

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

Konfigurowanie aktywności punktu wejścia Androida

Firebase Cloud Messaging jest dostarczana z niestandardowym punktem wejścia, który zastępuje domyślny UnityPlayerActivity. Jeśli nie używasz niestandardowego punktu wejścia, ta zamiana następuje automatycznie i nie musisz podejmować żadnych dodatkowych działań.

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

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 używa 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 Androida (przykład, jak to zrobić, znajdziesz poniżej). Jeśli Twoja aktywność niestandardowa rozszerza klasę UnityPlayerActivity, możesz zamiast tego rozszerzyć klasę UnityPlayerActivity, która implementuje wszystkie niezbędne metody.com.google.firebase.MessagingUnityPlayerActivity

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 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 SDK Firebase C++ (od 7.1.0) 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="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 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.

W przypadku wiadomości odebranych, gdy aplikacja działa w tle, do wypełnienia powiadomienia w obszarze powiadomień używana jest zawartość pola powiadomienia, ale ta zawartość nie jest przekazywana do FCM. Oznacza to, że wartość FirebaseMessage.Notification będzie równa 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.

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 Twojej aplikacji. Filtr intencji powinien wykrywać precyzyjne linki do 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 schematu i hosta, które określisz, Twoja 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). Wartość metadanych możesz dodać do Info.plist (nie do GoogleService-Info.plist) na urządzeniu Apple lub do 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.

Dalsze kroki

Po wykonaniu czynności konfiguracyjnych możesz skorzystać z tych opcji, aby zacząć korzystać z FCM w Unity: