Richten Sie eine Firebase Cloud Messaging-Client-App mit Unity ein

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

Bevor Sie beginnen

Voraussetzungen

• Installieren Sie Unity 2019.1 oder höher. Frühere Versionen sind möglicherweise auch kompatibel, werden jedoch nicht aktiv unterstützt. Die Unterstützung für Unity 2019.1 gilt als veraltet und wird nach der nächsten Hauptversion nicht mehr aktiv unterstützt.

• (Nur Apple-Plattformen) Installieren Sie Folgendes:

  • Xcode 13.3.1 oder höher
  • CocoaPods 1.10.0 oder höher

• Stellen Sie sicher, dass Ihr Unity-Projekt diese Anforderungen erfüllt:

  • Für iOS – zielt auf iOS 11 oder höher ab
  • Für tvOS – zielt auf tvOS 12 oder höher ab
  • Für Android – zielt auf API-Level 19 (KitKat) oder höher ab

• 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 zum Ausführen Ihrer App ein und führen Sie die folgenden Aufgaben aus:

    • Besorgen Sie sich einen Apple-Push-Benachrichtigungs-Authentifizierungsschlüssel für Ihr Apple-Entwicklerkonto .
    • Aktivieren Sie Push-Benachrichtigungen in XCode unter App > Capabilities .

  • Für Android : Emulatoren müssen ein Emulator-Image bei Google Play verwenden.

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

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

Schritt 1: Erstellen Sie ein Firebase-Projekt

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. Besuchen Sie „Firebase-Projekte verstehen“ , um mehr über Firebase-Projekte zu erfahren.

Schritt 2: Registrieren Sie Ihre App bei Firebase

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

1. Gehen Sie zur Firebase-Konsole .

2. Klicken Sie in der Mitte der Projektübersichtsseite auf das Unity- Symbol ( plat_unity ), um den Setup-Workflow zu starten.

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

3. Wählen Sie aus, welches Build-Ziel Ihres Unity-Projekts Sie registrieren möchten, oder Sie können sogar beide Ziele jetzt gleichzeitig registrieren.

4. Geben Sie die plattformspezifischen ID(s) 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 häufig synonym verwendet.

   Wo finden Sie die ID Ihres Unity-Projekts?

   Öffnen Sie Ihr Unity-Projekt in Ihrer Unity-IDE und navigieren Sie dann zum Abschnitt „Einstellungen“ für jede Plattform:

   • Für iOS : Navigieren Sie zu Build-Einstellungen > iOS .

   • Für Android : Navigieren Sie zu Android > Player-Einstellungen > Andere Einstellungen .

   Die ID Ihres Unity-Projekts ist der Bundle-Identifier- Wert (Beispiel-ID: com.yourcompany.yourproject ).

5. (Optional) Geben Sie die plattformspezifischen Spitznamen Ihres Unity-Projekts ein.
   Bei diesen Spitznamen handelt es sich um interne, praktische Kennungen, die nur für Sie in der Firebase-Konsole sichtbar sind.

6. Klicken Sie auf App registrieren .

Schritt 3: Firebase-Konfigurationsdateien hinzufügen

1. Rufen Sie Ihre plattformspezifischen Firebase-Konfigurationsdateien im Einrichtungsworkflow der Firebase-Konsole ab.

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

   • Für Android : Klicken Sie auf „Google-services.json herunterladen“ .

   Was müssen Sie über diese Konfigurationsdatei wissen?

   • Die Firebase-Konfigurationsdatei enthält eindeutige, aber nicht geheime Kennungen für Ihr Projekt. Weitere Informationen zu dieser Konfigurationsdatei finden Sie unter „Grundlegendes zu Firebase-Projekten“ .

   • Sie können Ihre Firebase-Konfigurationsdatei jederzeit erneut herunterladen.

   • Stellen Sie sicher, dass an den Namen der Konfigurationsdatei keine zusätzlichen Zeichen wie (2) angehängt werden.

2. Öffnen Sie das Projektfenster Ihres Unity-Projekts und verschieben Sie dann Ihre Konfigurationsdatei(en) in den Ordner Assets .

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

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

   • Das Firebase Unity SDK ist nicht plattformspezifisch.

2. Navigieren Sie in Ihrem geöffneten Unity-Projekt zu 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 ein optimales Erlebnis mit 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 „Unity-Paket importieren“ auf „Importieren“ .

5. Klicken Sie zurück in der Firebase-Konsole im Setup-Workflow auf Weiter .

Schritt 5: Bestätigen Sie die Versionsanforderungen für die Google Play-Dienste

Das Firebase Unity SDK für Android erfordert Google Play-Dienste , die auf dem neuesten Stand sein müssen, bevor das SDK verwendet werden kann.

Fügen Sie am Anfang Ihrer Anwendung den folgenden Code hinzu. Sie können vor dem Aufrufen anderer Methoden im SDK nach Google Play-Diensten suchen und diese optional auf die für das Firebase Unity SDK erforderliche Version aktualisieren.

Firebase.FirebaseApp.CheckAndFixDependenciesAsync().ContinueWith(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.

Aktivieren Sie Push-Benachrichtigungen auf Apple-Plattformen

Schritt 1: Benutzerbenachrichtigungs-Framework hinzufügen

1. Klicken Sie in Xcode auf das Projekt und wählen Sie dann im Editorbereich die Registerkarte „Allgemein“ aus.

2. Scrollen Sie nach unten zu „Verknüpfte Frameworks und Bibliotheken“ und klicken Sie 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 dann im Editorbereich die Registerkarte „Funktionen“ aus.

2. Schalten Sie Push-Benachrichtigungen auf Ein .

3. Scrollen Sie nach unten zu „Hintergrundmodi“ und schalten Sie es dann auf „Ein“ .

4. Aktivieren Sie unter „Hintergrundmodi“ das Kontrollkästchen „Fernbenachrichtigungen“ .

Firebase Cloud Messaging initialisieren

Die Firebase Cloud Message-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 erhält das Token mit dem OnTokenReceived Ereignis, das zur späteren Verwendung zwischengespeichert werden sollte. Sie benötigen dieses Token, wenn Sie Nachrichten gezielt auf dieses Gerät senden möchten.

Darüber hinaus müssen Sie sich für das OnMessageReceived Ereignis registrieren, wenn Sie eingehende Nachrichten empfangen möchten.

Das gesamte Setup 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);
}

Konfigurieren einer Android-Einstiegspunktaktivität

Unter Android wird Firebase Cloud Messaging mit einer benutzerdefinierten Einstiegspunktaktivität gebündelt, die die standardmäßige UnityPlayerActivity ersetzt. Wenn Sie keinen benutzerdefinierten Einstiegspunkt verwenden, erfolgt diese Ersetzung automatisch und Sie sollten keine zusätzlichen Maßnahmen ergreifen müssen. Apps, die nicht die Standardeinstiegspunktaktivität verwenden oder ihre eigenen Assets/Plugins/AndroidManifest.xml bereitstellen, benötigen eine zusätzliche Konfiguration.

Das Firebase Cloud Messaging Unity Plugin für Android wird mit zwei zusätzlichen Dateien geliefert:

• Assets/Plugins/Android/libmessaging_unity_player_activity.jar enthält eine Aktivität namens MessagingUnityPlayerActivity , die die standardmäßige 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 standardmäßige UnityPlayerActivity keine onStop und onRestart Aktivitätslebenszyklusübergänge verarbeitet oder den onNewIntent implementiert, der für Firebase Cloud Messaging erforderlich ist, um eingehende Nachrichten korrekt zu verarbeiten.

Konfigurieren einer benutzerdefinierten Einstiegspunktaktivität

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

Wenn Sie eine benutzerdefinierte Aktivität verwenden und com.google.firebase.MessagingUnityPlayerActivity nicht erweitern, sollten Sie die folgenden Snippets in Ihre Aktivität einschließen.

/**
 * 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 in 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 Nachrichtenzustellung auf Android

Wenn die App überhaupt nicht ausgeführt wird und ein Benutzer auf eine Benachrichtigung tippt, wird die Nachricht standardmäßig nicht über die integrierten Rückrufe 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 zum Ausfüllen der Taskleistenbenachrichtigung verwendet. Dieser Benachrichtigungsinhalt wird jedoch nicht an FCM übermittelt. Das heißt, FirebaseMessage.Notification wird eine Null sein.

In Summe:

Verhindern Sie die automatische Initialisierung

FCM generiert ein Registrierungstoken für das Geräte-Targeting. Wenn ein Token generiert wird, lädt die Bibliothek die Kennung und Konfigurationsdaten in Firebase hoch. Wenn Sie vor der Verwendung des Tokens eine explizite Einwilligung einholen möchten, können Sie die Generierung zum Zeitpunkt der Konfiguration verhindern, indem Sie FCM (und auf Android Analytics) deaktivieren. Fügen Sie dazu einen Metadatenwert zu Ihrer Info.plist (nicht zu Ihrer GoogleService-Info.plist ) auf Apple oder Ihrer AndroidManifest.xml auf Android 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

Um FCM wieder zu aktivieren, können Sie einen Laufzeitaufruf durchführen:

Firebase.Messaging.FirebaseMessaging.TokenRegistrationOnInitEnabled = true;

Dieser Wert bleibt über App-Neustarts hinweg bestehen, sobald er festgelegt wurde.

Umgang mit Nachrichten mit Deep Links auf Android

Mit FCM können Nachrichten gesendet werden, die einen Deep-Link zu Ihrer App enthalten. Um Nachrichten zu empfangen, die einen Deep-Link enthalten, müssen Sie der Aktivität, die Deep-Links für Ihre App verarbeitet, einen neuen Absichtsfilter hinzufügen. Der Intent-Filter sollte Deep-Links Ihrer Domain erfassen. Wenn Ihre Nachrichten keinen Deep Link enthalten, ist diese Konfiguration nicht notwendig. 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>

Es ist auch möglich, einen Platzhalter anzugeben, um den Intent-Filter flexibler zu gestalten. Zum 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 Benutzer auf eine Benachrichtigung tippen, die einen Link zu dem von Ihnen angegebenen Schema und Host enthält, startet Ihre App die Aktivität mit diesem Absichtsfilter, 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 Schnellstartbeispiel , das diese Funktionalität demonstriert.

Informationen zum Hinzufügen weiterer, erweiterter Verhaltensweisen zu Ihrer App finden Sie in den Anleitungen zum Senden von Nachrichten von einem App-Server:

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

Beachten Sie, dass Sie eine Serverimplementierung benötigen, um diese Funktionen nutzen zu können.