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 einige zusätzliche Einstellungen erforderlich sind.

Bevor Sie beginnen

Voraussetzungen

• Installieren Sie Unity 2019.1 oder höher. Frühere Versionen können ebenfalls kompatibel sein, werden aber 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 ein, um Ihre App auszuführen, und führen Sie diese Aufgaben aus:

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

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

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

Wenn Sie noch kein Unity-Projekt haben und nur ein Firebase-Produkt ausprobieren möchten, können Sie eines unserer Quickstart-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 jetzt sogar 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 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 Einstellungsbereich 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-ID- Wert (Beispiel-ID: com.yourcompany.yourproject ).

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

6. Klicken Sie auf App registrieren .

Schritt 3: Fügen Sie Firebase-Konfigurationsdateien hinzu

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

   • Für iOS — Klicken Sie auf Download GoogleService-Info.plist .

   • Für Android — Klicken Sie auf Download google-services.json .

   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 Firebase-Projekte verstehen .

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

   • Stellen Sie sicher, dass dem 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 > Import Package > Custom Package .

3. Wählen Sie aus dem 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 nach Google Play-Diensten suchen und diese optional auf die für das Firebase Unity SDK erforderliche Version aktualisieren, bevor Sie andere Methoden im SDK aufrufen.

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 die Registerkarte „Allgemein“ im Bereich „Editor“ aus.

2. Scrollen Sie nach unten zu Linked Frameworks and Libraries 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: Aktivieren Sie Push-Benachrichtigungen

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

2. Schalten Sie Push-Benachrichtigungen auf Ein .

3. Scrollen Sie nach unten zu Hintergrundmodi und schalten Sie ihn dann auf Ein .

4. Aktivieren Sie das Kontrollkästchen Remote-Benachrichtigungen unter Hintergrundmodi .

Initialisieren Sie Firebase Cloud Messaging

Die Firebase Cloud Message-Bibliothek wird initialisiert, wenn Handler für die TokenReceived oder MessageReceived -Ereignisse 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 für die spätere Verwendung zwischengespeichert werden sollte. Sie benötigen dieses Token, wenn Sie Nachrichten auf dieses spezielle Gerät ausrichten möchten.

Außerdem müssen Sie sich für das Ereignis OnMessageReceived 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 Aktivität für einen Android-Einstiegspunkt

Auf Android wird Firebase Cloud Messaging mit einer benutzerdefinierten Einstiegspunktaktivität geliefert, die die standardmäßige UnityPlayerActivity ersetzt. Wenn Sie keinen benutzerdefinierten Einstiegspunkt verwenden, erfolgt diese Ersetzung automatisch, und Sie müssen keine weiteren Maßnahmen ergreifen. Apps, die nicht die standardmäßige Einstiegspunktaktivität verwenden oder ihre eigenen Assets/Plugins/AndroidManifest.xml bereitstellen, benötigen 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 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, weil die standardmäßige UnityPlayerActivity keine onStop , onRestart -Aktivitätslebenszyklusübergänge verarbeitet oder onNewIntent implementiert, das 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äß handhabt (ein Beispiel dafür wird unten gezeigt). 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 aufnehmen.

/**
 * 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 von 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 Nachrichtenübermittlung auf Android

Wenn die App überhaupt nicht ausgeführt wird und ein Benutzer auf eine Benachrichtigung tippt, wird die Nachricht standardmäßig nicht durch die integrierten Rückrufe von FCM geleitet. In diesem Fall werden Nachrichtennutzdaten über eine Intent empfangen, die zum Starten der Anwendung verwendet wird.

Bei Nachrichten, die empfangen werden, während sich die App im Hintergrund befindet, wird der Inhalt ihres Benachrichtigungsfelds verwendet, um die Benachrichtigung in der Taskleiste zu füllen, aber dieser Benachrichtigungsinhalt wird nicht an FCM übermittelt. Das heißt, FirebaseMessage.Notification ist null.

In Summe:

Automatische Initialisierung verhindern

FCM generiert ein Registrierungstoken für das Geräte-Targeting. 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 Einwilligung erhalten möchten, können Sie die Generierung zum Zeitpunkt der Konfiguration verhindern, indem Sie FCM (und auf Android Analytics) deaktivieren. Fügen Sie dazu Ihrer Info.plist (nicht Ihrer GoogleService-Info.plist ) auf Apple oder Ihrer AndroidManifest.xml auf Android einen Metadatenwert 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 tätigen:

Firebase.Messaging.FirebaseMessaging.TokenRegistrationOnInitEnabled = true;

Dieser Wert bleibt nach dem Festlegen über App-Neustarts hinweg bestehen.

Umgang mit Nachrichten mit Deep Links auf Android

FCM ermöglicht das Versenden von Nachrichten mit einem Deep-Link in Ihre App. Um Nachrichten zu erhalten, die einen Deep-Link enthalten, müssen Sie der Aktivität, die Deep-Links für Ihre App verarbeitet, einen neuen Intent-Filter hinzufügen. Der Intent-Filter sollte Deep-Links 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>

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 Topic-Nachrichten mit Firebase senden. Um mehr zu erfahren, sehen Sie sich das Quickstart-Beispiel an, das diese Funktionalität demonstriert.

Um Ihrer App andere, fortgeschrittenere Verhaltensweisen hinzuzufügen, lesen Sie die Anleitungen zum Senden von Nachrichten von einem App-Server:

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

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