Firebase Cloud Messaging-Client-App mit Unity einrichten

Verwenden Sie zum Schreiben einer plattformübergreifenden Firebase Cloud Messaging-Clientanwendung mit Unity 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. Der Support für Unity 2020 wird eingestellt und 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: Ausrichtung auf iOS 13 oder höher
  • Für tvOS: Ausrichtung auf 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.

  • iOS oder tvOS: Richten Sie ein physisches Gerät zum Ausführen Ihrer App ein und führen Sie die folgenden Aufgaben aus:

    • Fordern Sie einen Apple Push Notification-Authentifizierungsschlüssel für Ihr Apple-Entwicklerkonto an.
    • Aktivieren Sie Push-Benachrichtigungen in XCode unter App > Funktionen.

  • Android: Emulatoren müssen ein Emulator-Image mit Google Play verwenden.

• Melden Sie sich mit Ihrem Google-Konto in Firebase an.

Wenn Sie noch kein Unity-Projekt haben und nur ein Firebase-Produkt ausprobieren möchten, können Sie eines unserer Beispiele für den Schnellstart 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 finden Sie unter Firebase-Projekte verstehen.

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 Console auf.

2. Klicken Sie in der Mitte der Projektübersicht auf das Symbol Unity (plat_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.

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

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

   Wo finden Sie die ID Ihres Unity-Projekts?

   Öffnen Sie Ihr Unity-Projekt in der Unity-IDE und rufen Sie für jede Plattform den Bereich „Einstellungen“ auf:

   • iOS: Gehen Sie zu Build-Einstellungen > iOS.

   • Für Android: Navigiere zu Android > Player-Einstellungen > Weitere Einstellungen.

   Die ID Ihres Unity-Projekts ist der Wert für die Bundle-ID (Beispiel-ID: com.yourcompany.yourproject).

5. Optional: Geben Sie den oder die plattformspezifischen Alias für Ihr Unity-Projekt ein.
   Diese Aliasse sind interne, praktische Kennungen und sind nur in der Firebase-Konsole für Sie sichtbar.

6. Klicken Sie auf App registrieren.

Schritt 3: Firebase-Konfigurationsdateien hinzufügen

1. Rufen Sie die platformspezifischen Firebase-Konfigurationsdateien im Firebase Workflow zur Einrichtung der Konsole ab.

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

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

   Was müssen Sie über diese Konfigurationsdatei wissen?

   • Die Firebase-Konfigurationsdatei enthält eindeutige, aber nicht verborgene Kennungen für Ihr Projekt. Weitere Informationen zu dieser Konfigurationsdatei finden Sie unter Firebase-Projekte.

   • Sie können die Firebase-Konfigurationsdatei jederzeit wieder herunterladen.

   • Achten Sie darauf, dass der Name der Konfigurationsdatei keine zusätzlichen Zeichen wie z. B. (2) enthält.

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

3. Klicken Sie in der Firebase-Konsole im Einrichtungsworkflow 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 an einem geeigneten Ort.

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

   • Das Firebase Unity SDK ist nicht plattformspezifisch.

2. Gehen Sie in Ihrem geöffneten Unity-Projekt zu Assets > Import Package > Custom Package (Assets > Paket importieren > Benutzerdefiniertes Paket).

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 bei 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 Einrichtungsworkflow auf Weiter.

Schritt 5: Versionsanforderungen der Google Play-Dienste bestätigen

Für das Firebase Unity SDK for Android ist Google Play services erforderlich. Dieses muss auf dem neuesten Stand sein, damit das SDK verwendet werden kann.

Fügen Sie am Anfang Ihrer Anwendung die folgende using-Anweisung und den Initialisierungscode ein. Sie können prüfen, ob Google Play services auf die Version aktualisiert wird, die für das Firebase Unity SDK erforderlich ist, bevor Sie andere Methoden im SDK aufrufen.

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 für die Verwendung von Firebase registriert und konfiguriert.

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

Laden Sie Ihren APNs-Authentifizierungsschlüssel in Firebase hoch. Wenn du noch keinen APNs-Authentifizierungsschlüssel hast, erstelle einen im Apple Developer Member Center.

1. Klicken Sie in der Firebase Console in Ihrem Projekt auf das Zahnradsymbol, dann auf Projekteinstellungen und dann auf den Tab Cloud Messaging.

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

3. Rufen Sie den Speicherort auf, 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. Scrollen Sie nach unten zu Verknüpfte Frameworks und Bibliotheken und klicken Sie 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 Add (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 An.

3. Scrollen Sie nach unten zu Hintergrundmodi und aktivieren Sie die Option.

4. Setzen Sie unter Hintergrundmodi ein Häkchen in das Kästchen Remote-Benachrichtigungen.

Firebase Cloud Messaging initialisieren

Die Firebase Cloud Message-Bibliothek wird initialisiert, wenn Sie Handler für die Ereignisse TokenReceived oder MessageReceived hinzufügen.

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

Außerdem müssen Sie sich für das Ereignis OnMessageReceived 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-Einstiegspunktaktivität konfigurieren

Unter Android ist Firebase Cloud Messaging mit einer benutzerdefinierten Aktivität für den Einstiegspunkt verknüpft, die den Standard-UnityPlayerActivity ersetzt. Wenn Sie keinen benutzerdefinierten Einstiegspunkt verwenden, erfolgt dieser Ersatz automatisch und Sie müssen keine weiteren Maßnahmen ergreifen. Anwendungen, die nicht die Standardeinstiegspunktaktivität verwenden oder ihre eigene 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 geliefert:

• Assets/Plugins/Android/libmessaging_unity_player_activity.jar enthält eine Aktivität mit dem Namen MessagingUnityPlayerActivity, die den standardmäßigen UnityPlayerActivity ersetzt.
• Assets/Plugins/Android/AndroidManifest.xml weist die App an, MessagingUnityPlayerActivity als Einstiegspunkt zu verwenden.

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

Benutzerdefinierte Einstiegspunktaktivität konfigurieren

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

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

Neue Versionen des Firebase C++ SDK (ab 7.1.0) verwenden JobIntentService, was zusätzliche Änderungen an der Datei AndroidManifest.xml erfordert.

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

Hinweis zur Nachrichtenübermittlung unter Android

Wenn die App 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 ein Intent empfangen, das zum Starten der Anwendung verwendet wird.

Nachrichten, die empfangen werden, während die App im Hintergrund ausgeführt wird, werden im Benachrichtigungsfeld angezeigt. Der Inhalt dieser Benachrichtigung wird jedoch nicht an FCM gesendet. Das heißt, FirebaseMessage.Notification ist null.

Zusammenfassung:

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 ausdrückliche Zustimmung einholen möchten, können Sie die Generierung während der Konfiguration verhindern, indem Sie FCM (und unter Android Analytics) deaktivieren. Fügen Sie dazu auf Apple-Geräten einen Metadatenwert zu Info.plist (nicht GoogleService-Info.plist) und auf Android-Geräten zu AndroidManifest.xml hinzu:

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

Mit einem Laufzeitaufruf können Sie FCM wieder aktivieren:

Firebase.Messaging.FirebaseMessaging.TokenRegistrationOnInitEnabled = true;

Dieser Wert bleibt bei App-Neustarts erhalten, sobald dieser festgelegt ist.

Nachrichten mit Deeplinks auf Android verarbeiten

Mit FCM können Nachrichten mit einem Deeplink an Ihre 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 erfassen. Wenn Ihre Nachrichten keinen Deeplink enthalten, ist diese Konfiguration nicht erforderlich. In 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 mit einem Link zu dem von Ihnen angegebenen Schema und Host tippen, 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 mit Firebase Downstream- und Topic-Nachrichten senden. Weitere Informationen finden Sie im Beispiel für den Schnellstart, in dem diese Funktion veranschaulicht wird.

Wenn Sie Ihrer App weitere, erweiterte Funktionen hinzufügen möchten, lesen Sie die Anleitungen zum Senden von Nachrichten von einem App-Server:

• Themennachrichten senden
• An Gerätegruppen senden
• Upstream-Nachrichten senden

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