Erste Schritte mit Firebase Cloud Messaging in Flutter-Apps

Plattform auswählen: iOS+ Android Web Flutter Unity C++


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

Je nach Zielplattform sind einige zusätzliche Einrichtungsschritte erforderlich.

iOS+

Method Swizzling

Wenn Sie das Flutter-Plug-in FCM auf Apple-Geräten verwenden möchten, ist Method Swizzling erforderlich. Ohne diese Berechtigung funktionieren wichtige Firebase-Funktionen wie die Verarbeitung von FCM-Registrierungen nicht richtig.

Android

Google Play-Dienste

FCM-Clients erfordern Geräte mit Android 7.0 oder höher, auf denen auch die Google Play-Dienste installiert sind, oder einen Emulator mit Android 7.0 und Google APIs. Sie sind nicht darauf beschränkt, Ihre Android-Apps über den Google Play Store bereitzustellen.

Apps, die das Play Services SDK verwenden, sollten immer prüfen, ob auf dem Gerät ein kompatibles Google Play-Dienste-APK vorhanden ist, bevor sie auf Funktionen der Google Play-Dienste zugreifen. Es wird empfohlen, dies an zwei Stellen zu tun: in der onCreate()-Methode der Hauptaktivität und in ihrer onResume()-Methode. Die Prüfung in onCreate() sorgt dafür, dass die App nicht ohne erfolgreiche Prüfung verwendet werden kann. Die Prüfung in onResume() sorgt dafür, dass die Prüfung auch dann durchgeführt wird, wenn der Nutzer auf andere Weise zur laufenden App zurückkehrt, z. B. über den Button „Zurück“.

Wenn auf dem Gerät keine kompatible Version der Google Play-Dienste installiert ist, kann deine App GoogleApiAvailability.makeGooglePlayServicesAvailable() aufrufen, damit Nutzer die Google Play-Dienste aus dem Play Store herunterladen können.

Web

Web-Anmeldedaten mit FCM konfigurieren

Die FCM-Weboberfläche verwendet Web-Anmeldedaten, die als „Voluntary Application Server Identification“ oder „VAPID“-Schlüssel bezeichnet werden, um Sendeanfragen an unterstützte Web-Push-Dienste zu autorisieren. Wenn Sie Ihre App für Push-Benachrichtigungen abonnieren möchten, müssen Sie ein Schlüsselpaar mit Ihrem Firebase-Projekt verknüpfen. Sie können entweder ein neues Schlüsselpaar generieren oder Ihr vorhandenes Schlüsselpaar über die Firebase-Konsole importieren.

FCM-Plug-in installieren

  1. Installieren und initialisieren Sie die Firebase-Plug-ins für Flutter, falls noch nicht geschehen.

  2. Führen Sie im Stammverzeichnis Ihres Flutter-Projekts den folgenden Befehl aus, um das Plug-in zu installieren:

    flutter pub add firebase_messaging

  3. Erstellen Sie anschließend Ihre Flutter-Anwendung neu:

    flutter run

Berechtigung zum Senden von Benachrichtigungen anfordern

Wenn Sie eine Benachrichtigung an ein Gerät senden möchten, müssen Sie das Gerät mit register() bei FCM registrieren. Wenn die Berechtigung zum Senden von Benachrichtigungen nicht erteilt wurde, wird der Nutzer mit dieser Methode um die Berechtigung zum Senden von Benachrichtigungen gebeten. Andernfalls wird die FID bei Erfolg über onRegistered bereitgestellt oder die Future wird aufgrund eines Fehlers abgelehnt.

// You may set the permission requests to "provisional" which allows the user to choose what type
// of notifications they would like to receive once the user receives a notification.
final notificationSettings = await FirebaseMessaging.instance.requestPermission(provisional: true);

// For apple platforms, make sure the APNS token is available before making any FCM plugin API calls
final apnsToken = await FirebaseMessaging.instance.getAPNSToken();
if (apnsToken != null) {
 // APNS token is available, make FCM plugin API requests...
}

Auf die Firebase-Installations-ID zugreifen

Registrierung mit Firebase-Installations-ID aktivieren

Damit Sie Ihre App-Instanz mit der Firebase-Installations-ID (FID) bei FCM registrieren können, müssen Sie zuerst FIDs in der Konfiguration Ihrer App für Android- und Apple-Plattformen aktivieren. Im Web ist keine statische Opt-in-Konfiguration erforderlich:

Android

Fügen Sie das folgende <meta-data>-Element im <application>-Element Ihrer AndroidManifest.xml hinzu:

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

iOS+

Fügen Sie den Schlüssel FirebaseMessagingInstallationIdEnabled zu Ihrer Info.plist hinzu und legen Sie ihn auf true (YES) fest:

<key>FirebaseMessagingInstallationIdEnabled</key>
<true/>

Stream onRegistered abonnieren

Wenn Sie eine Nachricht an Ihre App-Instanz auf einem bestimmten Gerät senden möchten, benötigen Sie die Firebase-Installations-ID (FID) dieser App-Instanz, nachdem sie bei FCM registriert wurde. Die FID wird asynchron über den onRegistered-Stream bereitgestellt.

Auf Android- und Apple-Plattformen registriert FCM die App-Instanz beim Start automatisch, wenn die automatische Initialisierung aktiviert ist (Standardeinstellung). Es ist jedoch ein expliziter Aufruf von register() erforderlich:

  • Im Web: Optional können Sie vapidKey und serviceWorkerScriptPath übergeben.
  • Auf Android- und Apple-Plattformen, wenn die automatische Initialisierung deaktiviert ist oder nachdem unregister() aufgerufen wurde. Sie können auch jederzeit register() aufrufen, um onRegistered mit der bereits registrierten FID auszulösen.

Abonnieren Sie immer onRegistered, bevor Sie register() aufrufen, damit Ihr Listener aktiv ist, wenn das Registrierungsereignis ausgegeben wird:

final messaging = FirebaseMessaging.instance;

messaging.onRegistered
    .listen((String installationId) {
      // TODO: Send the Firebase Installation ID (FID) to your application server.
    })
    .onError((err) {
      // Error getting Firebase Installation ID.
    });

// Required on Web, and on Android/Apple if auto-initialization is disabled.
await messaging.register(
  // Optional on Web (ignored on Android and Apple platforms)
  vapidKey: "BKagOny0KF_2pCJQ3m....moL0ewzQ8rZu",
);

Der onRegistered-Stream gibt die FID in den folgenden Szenarien aus:

  1. Automatisch beim ersten Start der App und bei der routinemäßigen Synchronisierung auf Android- und Apple-Plattformen, wenn die automatische Initialisierung aktiviert ist.
  2. Jedes Mal, wenn ein manueller register()-Aufruf abgeschlossen wird (auch wenn die App-Instanz bereits registriert ist, gibt onRegistered weiterhin die bereits registrierte FID aus).
  3. Wenn eine Änderung der Firebase-Installations-ID erkannt und die App noch einmal bei FCM registriert wird, oder im Web, wenn ein pushsubscriptionchange-Ereignis ausgelöst wird.

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

Auf das Registrierungstoken zugreifen (verworfen)

Wenn Sie eine Nachricht an ein bestimmtes Gerät senden möchten, benötigen Sie das Registrierungstoken des Geräts. Rufen Sie getToken() auf, um das Registrierungstoken für eine App-Instanz abzurufen. Wenn die Berechtigung zum Senden von Benachrichtigungen nicht erteilt wurde, wird der Nutzer mit dieser Methode um die Berechtigung zum Senden von Benachrichtigungen gebeten. Andernfalls wird ein Token zurückgegeben oder die Future-Anfrage wird aufgrund eines Fehlers abgelehnt.

Übergeben Sie auf Webplattformen Ihren öffentlichen VAPID-Schlüssel an getToken():

final fcmToken = await FirebaseMessaging.instance.getToken(vapidKey: "BKagOny0KF_2pCJQ3m....moL0ewzQ8rZu");

Wenn Sie benachrichtigt werden möchten, wenn das Token aktualisiert wird, abonnieren Sie den onTokenRefresh-Stream:

FirebaseMessaging.instance.onTokenRefresh
    .listen((fcmToken) {
      // TODO: If necessary send token to application server.

      // Note: This callback is fired at each app startup and whenever a new
      // token is generated.
    })
    .onError((err) {
      // Error getting token.
    });

Automatische Initialisierung verhindern

Wenn eine FCM-Registrierung generiert wird, lädt die Bibliothek die Kennung und die Konfigurationsdaten in Firebase hoch. Wenn Sie die automatische Registrierung verhindern möchten, deaktivieren Sie die automatische Initialisierung bei der Erstellung.

Wenn die automatische Initialisierung deaktiviert ist, können Sie die App-Instanz zur Laufzeit explizit registrieren, indem Sie register() aufrufen. Achten Sie darauf, zuerst onRegistered zu abonnieren, um die Firebase-Installations-ID zu erhalten:

await FirebaseMessaging.instance.register();

iOS

Fügen Sie unter iOS Ihrer Info.plist einen Metadatenwert hinzu:

FirebaseMessagingAutoInitEnabled = NO

Android

Unter Android können Sie die Analytics-Erfassung und die automatische FCM-Initialisierung deaktivieren (Sie müssen beides deaktivieren), indem Sie die folgenden Metadatenwerte in die Datei AndroidManifest.xml einfügen:

<meta-data
    android:name="firebase_messaging_auto_init_enabled"
    android:value="false" />
<meta-data
    android:name="firebase_analytics_collection_enabled"
    android:value="false" />

Automatische Initialisierung von FCM zur Laufzeit wieder aktivieren

Wenn Sie die automatische Initialisierung für eine bestimmte App-Instanz aktivieren möchten, rufen Sie setAutoInitEnabled() auf:

await FirebaseMessaging.instance.setAutoInitEnabled(true);

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

Testbenachrichtigung senden

  1. Installieren Sie die App auf dem Zielgerät und führen Sie sie aus. Auf Apple-Geräten müssen Sie die Berechtigungsanfrage zum Empfangen von Remote-Benachrichtigungen akzeptieren.

  2. Die App muss auf dem Gerät im Hintergrund ausgeführt werden.

  3. Rufen Sie in der Firebase Console DevOps & Engagement > Messaging auf.

  4. Kampagne erstellen

    • Wenn dies Ihre erste Mitteilung ist:

      1. Wählen Sie Erste Kampagne erstellen aus.

      2. Wählen Sie Firebase-Benachrichtigungen und dann Erstellen aus.

    • Wenn Sie bereits Kampagnen erstellt haben:

      1. Wählen Sie auf dem Tab Kampagnen die Option Neue Kampagne aus.

      2. Klicken Sie auf Benachrichtigungen.

  5. Geben Sie den Nachrichtentext ein.

  6. Wählen Sie im rechten Bereich Testnachricht senden aus.

  7. Geben Sie im Feld Firebase-Installations-ID oder FCM-Registrierungstoken hinzufügen Ihre registrierte Firebase-Installations-ID oder Ihr Registrierungstoken ein.

  8. Wählen Sie Testen aus.

Nachdem Sie Test ausgewählt haben, sollte das Ziel-Clientgerät die Benachrichtigung erhalten, während die App im Hintergrund ausgeführt wird.

Informationen zur Nachrichtenzustellung an Ihre App finden Sie in der Firebase-Konsole unter DevOps & Engagement > Messaging > Berichte-Dashboard. In diesem Dashboard wird die Anzahl der Nachrichten erfasst, die auf Apple- und Android-Geräten gesendet und geöffnet wurden. Außerdem werden Daten zu „Impressionen“ (von Nutzern gesehene Benachrichtigungen) für Android-Apps angezeigt.

Interaktion mit dem Gerät

Wenn Nutzer auf eine Benachrichtigung tippen, wird standardmäßig sowohl unter Android als auch unter iOS die App geöffnet. Wenn die App beendet wurde, wird sie gestartet. Wenn sie im Hintergrund ausgeführt wird, wird sie in den Vordergrund gebracht.

Je nach Inhalt einer Benachrichtigung kann es sinnvoll sein, die Interaktion des Nutzers beim Öffnen der Anwendung zu verarbeiten. Wenn beispielsweise eine neue Chatnachricht über eine Benachrichtigung gesendet wird und der Nutzer sie auswählt, soll beim Öffnen der Anwendung die entsprechende Unterhaltung geöffnet werden.

Das Paket firebase-messaging bietet zwei Möglichkeiten, diese Interaktion zu verarbeiten:

  1. getInitialMessage(): Wenn die Anwendung aus einem beendeten Zustand geöffnet wird, gibt diese Methode ein Future mit einem RemoteMessage zurück. Nach dem Verbrauch wird die RemoteMessage entfernt.
  2. onMessageOpenedApp: Ein Stream, der eine RemoteMessage postet, wenn die Anwendung aus einem Hintergrundstatus geöffnet wird.

Damit deine Nutzer eine reibungslose Nutzung haben, solltest du beide Szenarien berücksichtigen. Das folgende Codebeispiel zeigt, wie das geht:

class Application extends StatefulWidget {
  @override
  State createState() => _Application();
}

class _Application extends State {
  // In this example, suppose that all messages contain a data field with the key 'type'.
  Future setupInteractedMessage() async {
    // Get any messages which caused the application to open from
    // a terminated state.
    RemoteMessage? initialMessage =
        await FirebaseMessaging.instance.getInitialMessage();

    // If the message also contains a data property with a "type" of "chat",
    // navigate to a chat screen
    if (initialMessage != null) {
      _handleMessage(initialMessage);
    }

    // Also handle any interaction when the app is in the background using a
    // Stream listener
    FirebaseMessaging.onMessageOpenedApp.listen(_handleMessage);
  }

  void _handleMessage(RemoteMessage message) {
    if (message.data['type'] == 'chat') {
      Navigator.pushNamed(context, '/chat',
        arguments: ChatArguments(message),
      );
    }
  }

  @override
  void initState() {
    super.initState();

    // Run code required to handle interacted messages in an async function
    // as initState() must not be async
    setupInteractedMessage();
  }

  @override
  Widget build(BuildContext context) {
    return Text("...");
  }
}

Wie Sie mit Interaktionen umgehen, hängt von Ihrer Einrichtung ab. Das zuvor gezeigte Beispiel ist ein einfaches Beispiel für die Verwendung eines StatefulWidget.

Nächste Schritte

Nachdem Sie die Einrichtungsschritte abgeschlossen haben, können Sie mit FCM for Flutter so fortfahren: