Erste Schritte mit Firebase Cloud Messaging in Unity-Apps

In diesem Leitfaden wird beschrieben, wie Sie Firebase Cloud Messaging in Ihren Unity-Client-Apps verwenden, um Nachrichten zuverlässig zu senden.

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, wobei für jede Plattform eine zusätzliche Einrichtung erforderlich ist.

Hinweis

Vorbereitung

• Installieren Sie Unity 2021 LTS oder höher. Frühere Versionen sind möglicherweise ebenfalls kompatibel, werden aber nicht aktiv unterstützt.

• (Nur Apple-Plattformen) Installieren Sie Folgendes:

  • Xcode 26.2 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 15 oder höher.
  • Für tvOS – Ziel ist tvOS 15 oder höher
  • Für Android: Ziel-API-Level 24 (Nougat) 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 Beispiele für den Schnelleinstieg herunterladen.

Schritt 1: Firebase-Projekt erstellen

Bevor Sie Firebase zu Ihrem Unity-Projekt hinzufügen können, müssen Sie ein Firebase-Projekt erstellen, das mit Ihrem Unity-Projekt verbunden wird. Weitere Informationen zu Firebase-Projekten finden Sie unter Firebase-Projekte.

Schritt 2: App bei Firebase registrieren

Sie können eine oder mehrere Apps oder Spiele registrieren, um sie mit Ihrem Firebase-Projekt zu verbinden.

1. Rufen Sie die Firebase-Konsole auf.

2. Klicken Sie in der Mitte der Projektübersicht auf das Unity-Symbol (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 aus, welches Build-Ziel Ihres Unity-Projekts 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-Paket-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 rufen Sie dann den Abschnitt mit den Einstellungen für die einzelnen Plattformen auf:

   • iOS: Gehen Sie zu Build Settings > iOS.

   • Android: Gehen Sie zu Android > Player Settings > Other Settings.

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

5. (Optional) Geben Sie die plattformspezifischen Aliasnamen Ihres Unity-Projekts ein.
   Diese Aliasse sind interne, praktische Kennungen und 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.

   Was müssen Sie über diese Konfigurationsdatei wissen?

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

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

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

2. Öffnen Sie das Fenster Project Ihres Unity-Projekts und verschieben Sie dann 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 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 (Assets > Paket importieren > Benutzerdefiniertes Paket) 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. Im Rahmen der Einrichtung von Analytics müssen Sie Ihrer App auch das Firebase-Paket für Analytics 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 Console im Einrichtungs-Workflow auf Weiter.

Schritt 5: Versionsanforderungen für Google Play-Dienste prüfen

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 Google Play services prüfen und optional auf die erforderliche Version aktualisieren, 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 registriert und für die Verwendung von Firebase konfiguriert.

Apple-Plattformen einrichten

Folgen Sie der Anleitung unten, um FCM mit Unity und Apple-Plattformen einzurichten.

APNs-Authentifizierungsschlüssel hochladen

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

1. Rufen Sie in der Firebase Console die settings Einstellungen > Allgemein auf. Klicken Sie dann auf den Tab Cloud Messaging.
2. Klicken Sie unter iOS-App-Konfiguration bei APNs-Authentifizierungsschlüssel auf Hochladen, um den Entwicklungs-Authentifizierungsschlüssel, den Produktions-Authentifizierungsschlüssel oder beide hochzuladen. Mindestens eine Angabe ist erforderlich.
3. Suchen Sie nach dem Speicherort des Schlüssels, 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

1. Klicken Sie in Xcode auf Ihr Projekt und wählen Sie dann im Editorbereich den Tab Allgemein aus.
2. Scrollen Sie zu Linked Frameworks and Libraries (Verknüpfte Frameworks und Bibliotheken) und klicken Sie auf den Button +, um ein Framework hinzuzufügen.
3. Scrollen Sie im angezeigten Fenster zu UserNotifications.framework, klicken Sie auf diesen Eintrag und dann auf Hinzufügen.
4. Klicken Sie in Xcode auf Ihr Projekt und wählen Sie im Editorbereich den Tab Capabilities (Funktionen) aus.
5. Stelle Push-Benachrichtigungen auf An.
6. Scrolle zu Hintergrundmodi und aktiviere die Option.
7. Setzen Sie unter Hintergrundmodi ein Häkchen bei Remote-Benachrichtigungen.

Firebase Cloud Messaging initialisieren

Registrierung mit Firebase-Installations-ID aktivieren

Wenn Sie die Registrierung Ihrer App-Instanz bei Firebase Cloud Messaging mit der Firebase-Installations-ID (FID) aktivieren möchten, müssen Sie zuerst FIDs in der Konfiguration Ihrer App für Android- und Apple-Plattformen aktivieren:

<meta-data android:name="firebase_messaging_installation_id_enabled"
           android:value="true" />

FirebaseMessagingInstallationIdEnabled = YES

Für FCM-Veranstaltungen registrieren

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

Bei der Initialisierung registriert Firebase Cloud Messaging die Client-App-Instanz für den Empfang von Nachrichten über die Firebase-Installations-ID (FID). Die App empfängt die FID mit dem Ereignis RegistrationReceived, das Sie auf Ihrem Server im Cache speichern sollten, um dieses Gerät für Nachrichten anzusprechen.

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

Die Einrichtung sieht so aus:

public void Start() {
  Firebase.Messaging.FirebaseMessaging.RegistrationReceived +=
      OnRegistrationReceived;
  Firebase.Messaging.FirebaseMessaging.MessageReceived +=
      OnMessageReceived;
}

public void OnRegistrationReceived(
    object sender,
    Firebase.Messaging.RegistrationReceivedEventArgs e) {
  UnityEngine.Debug.Log("Received Firebase Installation ID: " +
                        e.InstallationId);
  // TODO: Send the Firebase Installation ID (FID) to your app server to target
  // this device for messages.
}

public void OnMessageReceived(
    object sender,
    Firebase.Messaging.MessageReceivedEventArgs e) {
  UnityEngine.Debug.Log("Received a new message from: " + e.Message.From);
}

Nachdem Sie die Firebase-Installations-ID erhalten haben, senden Sie sie an Ihren Anwendungsserver und speichern Sie sie mit der von Ihnen bevorzugten Methode.

Manuelle Registrierung, wenn die automatische Initialisierung deaktiviert ist

Sie können die Registrierung mit FCM auch manuell zur Laufzeit mit RegisterAsync() auslösen:

// Manually register with FCM
Firebase.Messaging.FirebaseMessaging.RegisterAsync().ContinueWith(task => {
  if (task.IsCompleted) {
    // Note: The registered Installation ID is delivered to the
    // RegistrationReceived event handler.
    UnityEngine.Debug.Log("Registered with FCM");
  }
});

Auf das FCM-Registrierungstoken zugreifen (eingestellt)

Wenn Ihre App weiterhin die verworfenen Token-APIs verwendet, können Sie auf TokenReceived warten:

// Deprecated: Use RegistrationReceived instead
public void Start() {
  Firebase.Messaging.FirebaseMessaging.TokenReceived += OnTokenReceived;
}

public void OnTokenReceived(
    object sender,
    Firebase.Messaging.TokenReceivedEventArgs token) {
  UnityEngine.Debug.Log("Received Registration Token: " + token.Token);
}

Android-Plattformen einrichten

Folgen Sie der Anleitung unten, um FCM mit Unity- und Android-Plattformen einzurichten.

Android-Einstiegs-Activity konfigurieren

Firebase Cloud Messaging enthält eine benutzerdefinierte Einstiegspunktaktivität, die die Standardaktivität UnityPlayerActivity ersetzt. Wenn Sie keinen benutzerdefinierten Einstiegspunkt verwenden, erfolgt dieser Ersatz automatisch und Sie müssen nichts weiter unternehmen.

Das Firebase Cloud Messaging Unity-Plug-in für Android enthält zwei zusätzliche Dateien:

• Assets/Plugins/Android/libmessaging_unity_player_activity.jar enthält eine Aktivität namens MessagingUnityPlayerActivity, die die 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, weil die Standard-UnityPlayerActivity keine onStop- und onRestart-Aktivitätslebenszyklusübergänge verarbeitet und die onNewIntent nicht implementiert, die für die korrekte Verarbeitung eingehender Nachrichten durch Firebase Cloud Messaging erforderlich ist.

Aktivität mit benutzerdefiniertem Einstiegspunkt 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 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, das alle erforderlichen Methoden implementiert.

Wenn Sie eine benutzerdefinierte Aktivität verwenden und nicht com.google.firebase.MessagingUnityPlayerActivity 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 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);
}

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

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 Nutzlasten für Nachrichten ü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 bedeutet, dass FirebaseMessage.Notification null ist.

Zusammenfassung:

Nachrichten mit Deeplinks unter Android verarbeiten

Mit FCM können Nachrichten gesendet werden, die einen Deeplink zu Ihrer App enthalten. 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. 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. 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.

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 explizite Einwilligung einholen möchten, können Sie die Generierung bei der Konfiguration verhindern, indem Sie FCM (und unter Android Analytics) deaktivieren. Sie können Ihren Info.plist (nicht Ihren GoogleService-Info.plist) auf Apple-Geräten oder Ihren AndroidManifest.xml auf Android-Geräten einen Metadatenwert hinzufügen:

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

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

Firebase.Messaging.FirebaseMessaging.RegistrationOnInitEnabled = true;

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

Nächste Schritte

Nachdem Sie die Einrichtungsschritte abgeschlossen haben, haben Sie folgende Möglichkeiten, mit FCM für Unity fortzufahren:

• Nachrichten an Geräte senden
• Nachrichten in einem Unity-Client empfangen
• Themennachrichten senden