Erste Schritte mit Firebase Cloud Messaging in Flutter-Apps

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

Je nach Zielplattform sind einige zusätzliche Einrichtungsschritte erforderlich.

iOS+

Method Swizzling

Wenn Sie das FCM Flutter-Plug-in auf Apple-Geräten verwenden möchten, ist Method Swizzling erforderlich. Andernfalls funktionieren wichtige Firebase-Funktionen wie die FCM Registrierungs verwaltung 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 können Ihre Android-Apps nicht nur über den Google Play Store bereitstellen.

Apps, die auf dem Play Services SDK basieren, sollten immer prüfen, ob auf dem Gerät eine kompatible Google Play-Dienste-APK vorhanden ist, bevor sie auf Google Play-Dienste-Funktionen zugreifen. Wir empfehlen, dies an zwei Stellen zu tun: in der Methode onCreate() der Hauptaktivität und in der Methode onResume(). Durch die Prüfung in onCreate() wird sichergestellt, dass die App nur verwendet werden kann, wenn die Prüfung erfolgreich war. Durch die Prüfung in onResume() wird sichergestellt, dass die Prüfung auch dann durchgeführt wird, wenn der Nutzer auf andere Weise zur laufenden App zurückkehrt, z. B. über die Schaltfläche „Zurück“.

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

Web

Webanmeldedaten mit FCM konfigurieren

Die FCM Weboberfläche verwendet Webanmeldedaten, sogenannte VAPID-Schlüssel (Voluntary Application Server Identification), 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.

Plug-in FCM 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 nach Abschluss den Build Ihrer 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 FCM mit register() registrieren. Wenn die Berechtigung zum Senden von Benachrichtigungen nicht erteilt wurde, werden 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 der Firebase-Installations-ID aktivieren

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

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

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

onRegistered-Stream 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 automatisch beim Start, wenn die automatische Initialisierung aktiviert ist (Standardeinstellung). Ein expliziter Aufruf von register() ist jedoch erforderlich:

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

Abonnieren Sie onRegistered immer, 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 ist. Auch wenn die App-Instanz bereits registriert ist, gibt onRegistered die bereits registrierte FID aus.
3. Immer wenn eine Änderung der Firebase-Installations-ID erkannt wird und die App bei FCMneu 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 App-Server und speichern Sie sie mit der gewünschten Methode.

Auf das Registrierungstoken zugreifen (veraltet)

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, werden Nutzer mit dieser Methode um die Berechtigung zum Senden von Benachrichtigungen gebeten. Andernfalls wird ein Token zurückgegeben oder die Future 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 ID und die Konfigurationsdaten in Firebase hoch. Wenn Sie die automatische Registrierung verhindern möchten, deaktivieren Sie die automatische Initialisierung zur Build-Zeit.

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

await FirebaseMessaging.instance.register();

iOS

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

FirebaseMessagingAutoInitEnabled = NO

Android

Deaktivieren Sie unter Android die Analytics-Erhebung und die automatische FCM-Initialisierung (beide müssen deaktiviert sein), indem Sie diese Metadatenwerte zu AndroidManifest.xml hinzufügen:

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

FCM automatische Initialisierung 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 nach Neustarts 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 Anfrage zur Berechtigung zum Empfangen von Remote-Benachrichtigungen akzeptieren.

2. Achten Sie darauf, dass die App auf dem Gerät im Hintergrund ausgeführt wird.

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

4. Erstellen Sie eine Kampagne.

   • Wenn dies Ihre erste Nachricht 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 Testen ausgewählt haben, sollte das Zielgerät mit der App im Hintergrund die Benachrichtigung erhalten.

Informationen zur Nachrichtenübermittlung an Ihre App finden Sie in der Firebase Konsole unter DevOps & Engagement > Messaging > Berichte Dashboard. In diesem Dashboard wird die Anzahl der gesendeten und geöffneten Nachrichten auf Apple- und Android-Geräten sowie Daten zu Impressionen (Benachrichtigungen, die von Nutzern gesehen wurden) für Android-Apps erfasst.

Interaktion verarbeiten

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

Je nach Inhalt einer Benachrichtigung möchten Sie möglicherweise die Interaktion des Nutzers verarbeiten, wenn die Anwendung geöffnet wird. Wenn beispielsweise eine neue Chatnachricht über eine Benachrichtigung gesendet wird und der Nutzer sie auswählt, möchten Sie möglicherweise die entsprechende Unterhaltung öffnen, wenn die Anwendung geöffnet wird.

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 eine Future zurück, die eine RemoteMessage enthält. Nach der Verwendung wird die RemoteMessage entfernt.
2. onMessageOpenedApp: EinStream der eine RemoteMessage postet, wenn die Anwendung aus einem Hintergrundzustand geöffnet wird.

Damit Ihre Nutzer ein reibungsloses Erlebnis haben, sollten Sie beide Szenarien verarbeiten. 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 die Interaktion verarbeiten, 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, haben Sie folgende Möglichkeiten, mit FCM für Flutter fortzufahren:

• Nachrichten an Geräte senden
• Nachrichten in einer Flutter-App empfangen
• Nachrichten an Themen senden