Firebase Cloud Messaging-Client-App mit Unity einrichten

Wenn Sie Ihre plattformübergreifende Firebase Cloud Messaging-Client-App mit Unity schreiben möchten, verwenden Sie die Firebase Cloud Messaging API. Das Unity SDK funktioniert sowohl für Android als auch für Apple. Für jede Plattform ist jedoch eine zusätzliche Einrichtung erforderlich.

Hinweis

Vorbereitung

  • Installieren Sie Unity 2021 LTS oder höher. Die Unterstützung für Unity 2020 gilt als eingestellt und wird nach der nächsten Hauptversion nicht mehr aktiv unterstützt. Ältere Versionen sind möglicherweise auch kompatibel, werden aber nicht aktiv unterstützt.

  • Nur Apple-Plattformen: Installieren Sie Folgendes:

    • Xcode 13.3.1 oder höher
    • CocoaPods 1.12.0 oder höher
  • Ihr Unity-Projekt muss die folgenden Anforderungen erfüllen:

    • Für iOS: Zielgruppe sind Geräte mit iOS 13 oder höher.
    • Für tvOS: Ziel ist tvOS 13 oder höher
    • Für Android: Ausrichtung auf API‑Level 21 (Lollipop) oder höher
  • Richten Sie ein Gerät ein oder verwenden Sie einen Emulator, um Ihr Unity-Projekt auszuführen.

    • Für iOS oder tvOS: Richten Sie ein physisches Gerät ein, auf dem Ihre App ausgeführt werden soll, und führen Sie die folgenden Aufgaben aus:

      • Rufen Sie einen Apple Push Notification-Authentifizierungsschlüssel für Ihr Apple-Entwicklerkonto ab.
      • Aktivieren Sie Push-Benachrichtigungen in Xcode unter App > Capabilities.
    • Für Android: Emulatoren müssen ein Emulator-Image mit Google Play verwenden.

Wenn Sie noch kein Unity-Projekt haben und nur ein Firebase-Produkt ausprobieren möchten, können Sie eines unserer Schnellstartbeispiele herunterladen.

Schritt 1: Firebase-Projekt erstellen

Bevor Sie Firebase zu Ihrem Unity-Projekt hinzufügen können, müssen Sie ein Firebase-Projekt erstellen, um eine Verbindung zu Ihrem Unity-Projekt herzustellen. Weitere Informationen zu Firebase-Projekten

Schritt 2: App bei Firebase registrieren

Sie können eine oder mehrere Apps oder Spiele registrieren, um eine Verbindung zu Ihrem Firebase-Projekt herzustellen.

  1. Rufen Sie die Firebase-Konsole auf.

  2. Klicken Sie in der Mitte der Projektübersicht auf das Symbol Unity (), um den Einrichtungsworkflow zu starten.

    Wenn Sie Ihrem Firebase-Projekt bereits eine App hinzugefügt haben, klicken Sie auf App hinzufügen, um die Plattformoptionen aufzurufen.

  3. Wählen Sie das Build-Ziel Ihres Unity-Projekts aus, das Sie registrieren möchten. Sie können auch beide Ziele gleichzeitig registrieren.

  4. Geben Sie die plattformspezifischen IDs Ihres Unity-Projekts ein.

    • Für iOS: Geben Sie die iOS-ID Ihres Unity-Projekts in das Feld iOS-Bundle-ID ein.

    • Für Android: Geben Sie die Android-ID Ihres Unity-Projekts in das Feld Android-Paketname ein.
      Die Begriffe Paketname und Anwendungs-ID werden oft synonym verwendet.

  5. (Optional) Geben Sie die plattformspezifischen Aliasnamen Ihres Unity-Projekts ein.
    Diese Aliasse sind interne, praktische Kennungen und sind nur für Sie in der Firebase-Konsole sichtbar.

  6. Klicken Sie auf App registrieren.

Schritt 3: Firebase-Konfigurationsdateien hinzufügen

  1. Rufen Sie Ihre plattformspezifischen Firebase-Konfigurationsdateien im Firebase-Konsoleneinrichtungsworkflow ab.

    • Für iOS: Klicken Sie auf GoogleService-Info.plist herunterladen.

    • Für Android: Klicken Sie auf google-services.json herunterladen.

  2. Öffnen Sie das Fenster Project Ihres Unity-Projekts und verschieben Sie die Konfigurationsdatei(en) in den Ordner Assets.

  3. Klicken Sie in der Firebase-Konsole im Einrichtungs-Workflow auf Weiter.

Schritt 4: Firebase Unity SDKs hinzufügen

  1. Klicken Sie in der Firebase-Konsole auf Firebase Unity SDK herunterladen und entpacken Sie das SDK dann an einem geeigneten Ort.

    • Sie können das Firebase Unity SDK jederzeit wieder herunterladen.

    • Das Firebase Unity SDK ist nicht plattformspezifisch.

  2. Rufen Sie in Ihrem geöffneten Unity-Projekt Assets > Import Package > Custom Package auf.

  3. Wählen Sie im entpackten SDK die unterstützten Firebase-Produkte aus, die Sie in Ihrer App verwenden möchten.

    Für eine optimale Nutzung von Firebase Cloud Messaging empfehlen wir, Google Analytics in Ihrem Projekt zu aktivieren. Außerdem müssen Sie im Rahmen der Einrichtung von Analytics das Firebase-Paket für Analytics zu Ihrer App hinzufügen.

    Analytics aktiviert

    • Fügen Sie das Firebase-Paket für Google Analytics hinzu: FirebaseAnalytics.unitypackage
    • Fügen Sie das Paket für Firebase Cloud Messaging hinzu: FirebaseMessaging.unitypackage

    Analytics nicht aktiviert

    Fügen Sie das Paket für Firebase Cloud Messaging hinzu: FirebaseMessaging.unitypackage

  4. Klicken Sie im Fenster Import Unity Package (Unity-Paket importieren) auf Import (Importieren).

  5. Klicken Sie in der Firebase-Konsole im Einrichtungs-Workflow auf Weiter.

Schritt 5: Anforderungen an die Version der Google Play-Dienste bestätigen

Für einige Produkte im Firebase Unity SDK for Android ist Google Play services erforderlich. Weitere Informationen Google Play services muss auf dem neuesten Stand sein, bevor diese Produkte verwendet werden können.

Fügen Sie am Anfang Ihrer Anwendung die folgende using-Anweisung und den Initialisierungscode hinzu. Sie können vor dem Aufrufen anderer Methoden im SDK prüfen, ob Google Play services die erforderliche Version hat, und sie gegebenenfalls aktualisieren.

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

Ihr Unity-Projekt ist registriert und für die Verwendung von Firebase konfiguriert.

APNs-Authentifizierungsschlüssel für Apple-Support hochladen

Laden Sie Ihren APNs-Authentifizierungsschlüssel in Firebase hoch. Wenn Sie noch keinen APNs-Authentifizierungsschlüssel haben, müssen Sie einen im Apple Developer Member Center erstellen.

  1. Wählen Sie in Ihrem Projekt in der Firebase-Konsole das Zahnradsymbol aus, dann Projekteinstellungen und schließlich den Tab Cloud Messaging.

  2. Klicken Sie unter Konfiguration der iOS-App bei APNs-Authentifizierungsschlüssel auf die Schaltfläche Hochladen.

  3. Suchen Sie nach dem Speicherort, an dem Sie den Schlüssel gespeichert haben, wählen Sie ihn aus und klicken Sie auf Öffnen. Fügen Sie die Schlüssel-ID für den Schlüssel hinzu (verfügbar im Apple Developer Member Center) und klicken Sie auf Hochladen.

Push-Benachrichtigungen auf Apple-Plattformen aktivieren

Schritt 1: Framework für Nutzerbenachrichtigungen hinzufügen

  1. Klicken Sie in Xcode auf das Projekt und wählen Sie dann im Editorbereich den Tab Allgemein aus.

  2. Scrolle nach unten zu Linked Frameworks and Libraries (Verknüpfte Frameworks und Bibliotheken) und klicke dann auf die Schaltfläche +, um ein Framework hinzuzufügen.

  3. Scrollen Sie im angezeigten Fenster zu UserNotifications.framework, klicken Sie auf diesen Eintrag und dann auf Hinzufügen.

Schritt 2: Push-Benachrichtigungen aktivieren

  1. Klicken Sie in Xcode auf das Projekt und wählen Sie im Editorbereich den Tab Funktionen aus.

  2. Stellen Sie Push-Benachrichtigungen auf Ein.

  3. Scrolle nach unten zu Hintergrundmodi und aktiviere die Option.

  4. Wählen Sie unter Hintergrundmodi das Kästchen Remote-Benachrichtigungen aus.

Firebase Cloud Messaging initialisieren

Die Firebase Cloud Messaging-Bibliothek wird initialisiert, wenn Handler für die Ereignisse TokenReceived oder MessageReceived hinzugefügt werden.

Bei der Initialisierung wird ein Registrierungstoken für die Client-App-Instanz angefordert. Die App empfängt das Token mit dem OnTokenReceived-Ereignis, das für die spätere Verwendung im Cache gespeichert werden sollte. Sie benötigen dieses Token, wenn Sie Nachrichten an dieses Gerät senden möchten.

Außerdem müssen Sie sich für das OnMessageReceived-Ereignis registrieren, wenn Sie eingehende Nachrichten empfangen möchten.

Die gesamte Einrichtung sieht so aus:

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

Android-Einstiegs-Activity konfigurieren

Unter Android ist Firebase Cloud Messaging in einer benutzerdefinierten Einstiegspunkt-Aktivität enthalten, die die Standard-UnityPlayerActivity ersetzt. Wenn Sie keinen benutzerdefinierten Einstiegspunkt verwenden, erfolgt dieser Ersatz automatisch und Sie müssen nichts weiter tun. Apps, die nicht die Standard-Einstiegspunkt-Aktivität verwenden oder einen eigenen Assets/Plugins/AndroidManifest.xml bereitstellen, erfordern eine zusätzliche Konfiguration.

Das Firebase Cloud Messaging Unity-Plug-in für Android wird mit zwei zusätzlichen Dateien ausgeliefert:

  • Assets/Plugins/Android/libmessaging_unity_player_activity.jar enthält eine Aktivität namens MessagingUnityPlayerActivity, die den Standard-UnityPlayerActivity ersetzt.
  • Assets/Plugins/Android/AndroidManifest.xml weist die App an, MessagingUnityPlayerActivity als Einstiegspunkt für die App zu verwenden.

Diese Dateien werden bereitgestellt, da die Standard-UnityPlayerActivity die Übergänge des Aktivitätslebenszyklus von onStop und onRestart nicht verarbeitet und die onNewIntent nicht implementiert, die für die korrekte Verarbeitung eingehender Nachrichten durch Firebase Cloud Messaging erforderlich ist.

Benutzerdefinierte Einstiegspunkt-Aktivität konfigurieren

Wenn Ihre App nicht die Standard-UnityPlayerActivity verwendet, müssen Sie die bereitgestellte AndroidManifest.xml entfernen und dafür sorgen, dass Ihre benutzerdefinierte Aktivität alle Übergänge des Android-Aktivitätslebenszyklus korrekt verarbeitet (ein Beispiel dafür finden Sie unten). Wenn Ihre benutzerdefinierte Aktivität UnityPlayerActivity erweitert, können Sie stattdessen com.google.firebase.MessagingUnityPlayerActivity erweitern, das alle erforderlichen Methoden implementiert.

Wenn Sie eine benutzerdefinierte Aktivität verwenden und com.google.firebase.MessagingUnityPlayerActivity nicht erweitern, sollten Sie die folgenden Snippets in Ihre Aktivität einfügen.

/**
 * 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);
}

In neuen Versionen des Firebase C++ SDK (ab Version 7.1.0) wird JobIntentService verwendet. Dies erfordert zusätzliche Änderungen in der Datei AndroidManifest.xml.

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

Hinweis zur Nachrichtenzustellung unter Android

Wenn die App überhaupt nicht ausgeführt wird und ein Nutzer auf eine Benachrichtigung tippt, wird die Nachricht standardmäßig nicht über die integrierten Callbacks von FCM weitergeleitet. In diesem Fall werden Nachrichtennutzlasten über einen Intent empfangen, der zum Starten der Anwendung verwendet wird.

Bei Nachrichten, die empfangen werden, während die App im Hintergrund ausgeführt wird, wird der Inhalt des Benachrichtigungsfelds verwendet, um die Benachrichtigung in der Taskleiste zu füllen. Dieser Benachrichtigungsinhalt wird jedoch nicht an FCM weitergegeben. Das heißt, FirebaseMessage.Notification ist null.

Zusammenfassung:

App-Status Benachrichtigung Daten Beides
Vordergrund Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived
Hintergrund Taskleiste Firebase.Messaging.FirebaseMessaging.MessageReceived Benachrichtigung: Taskleiste
Daten: in den Extras des Intents.

Automatische Initialisierung verhindern

FCM generiert ein Registrierungstoken für die Geräteausrichtung. Wenn ein Token generiert wird, lädt die Bibliothek die Kennung und die Konfigurationsdaten in Firebase hoch. Wenn Sie vor der Verwendung des Tokens eine explizite Einwilligung einholen möchten, können Sie die Generierung bei der Konfiguration verhindern, indem Sie FCM (und unter Android Analytics) deaktivieren. Fügen Sie dazu einen Metadatenwert zu Ihrem Info.plist (nicht zu Ihrem GoogleService-Info.plist) auf Apple oder zu Ihrem AndroidManifest.xml auf Android hinzu:

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

Wenn Sie FCM wieder aktivieren möchten, können Sie einen Laufzeitaufruf ausführen:

Firebase.Messaging.FirebaseMessaging.TokenRegistrationOnInitEnabled = true;

Dieser Wert bleibt nach dem Festlegen auch nach dem Neustart der App erhalten.

Mit FCM können Nachrichten mit einem Deeplink zu Ihrer App gesendet werden. Wenn Sie Nachrichten mit einem Deeplink empfangen möchten, müssen Sie der Aktivität, die Deeplinks für Ihre App verarbeitet, einen neuen Intent-Filter hinzufügen. Der Intent-Filter sollte Deeplinks Ihrer Domain abfangen. Wenn Ihre Nachrichten keinen Deeplink enthalten, ist diese Konfiguration nicht erforderlich. In der Datei „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>

Sie können auch einen Platzhalter angeben, um den Intent-Filter flexibler zu gestalten. Beispiel:

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

Wenn Nutzer auf eine Benachrichtigung tippen, die einen Link zum von Ihnen angegebenen Schema und Host enthält, startet Ihre App die Aktivität mit diesem Intent-Filter, um den Link zu verarbeiten.

Nächste Schritte

Nachdem Sie die Client-App eingerichtet haben, können Sie Downstream- und Themennachrichten mit Firebase senden. Weitere Informationen finden Sie im Kurzanleitung-Beispiel, in dem diese Funktion demonstriert wird.

Wenn Sie Ihrer App weitere, komplexere Funktionen hinzufügen möchten, finden Sie in den folgenden Anleitungen Informationen zum Senden von Nachrichten von einem App-Server:

Für die Nutzung dieser Funktionen ist eine Serverimplementierung erforderlich.