Erste Schritte mit Firebase Cloud Messaging in Android-Apps

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


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

FCM-Clients erfordern Geräte mit Android 7.0 oder höher, auf denen auch die Google Play Store App installiert ist, 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.

SDK einrichten

Falls noch nicht geschehen, fügen Sie Ihrem Android-Projekt Firebase hinzu.

Für eine optimale Nutzung von FCM empfehlen wir dringend, Google Analytics in Ihrem Projekt zu aktivieren. Google Analytics ist eine Voraussetzung für die Berichterstellung zur Nachrichtenzustellung für FCM.

App-Manifest bearbeiten

Fügen Sie dem Manifest Ihrer App Folgendes hinzu:

  • Ein Dienst, der FirebaseMessagingService erweitert. Dies ist erforderlich, wenn Sie Nachrichten über den Empfang von Benachrichtigungen in Apps im Hintergrund hinaus verarbeiten möchten. Wenn Sie Benachrichtigungen in Apps im Vordergrund, Datennutzlasten und mehr erhalten möchten, müssen Sie diesen Dienst erweitern.
    • <service
    android:name=".java.MyFirebaseMessagingService"
    android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>
  • (Optional) Metadatenelemente innerhalb der Anwendungskomponente, um ein Standard-Benachrichtigungssymbol und eine Standardfarbe festzulegen. Android verwendet diese Werte, wenn für eingehende Nachrichten nicht explizit ein Symbol oder eine Farbe festgelegt ist.
    • <!-- Set custom default icon. This is used when no icon is set for incoming notification messages.
     See README(https://goo.gl/l4GJaQ) for more. -->
<meta-data
    android:name="com.google.firebase.messaging.default_notification_icon"
    android:resource="@drawable/ic_stat_ic_notification" />
<!-- Set color used with incoming notification messages. This is used when no color is set for the incoming
     notification message. See README(https://goo.gl/6BKBk7) for more. -->
<meta-data
    android:name="com.google.firebase.messaging.default_notification_color"
    android:resource="@color/colorAccent" />
  • (Optional) Ab Android 8.0 (API-Level 26) werden Benachrichtigungskanäle unterstützt und empfohlen. FCM bietet einen Standardbenachrichtigungskanal mit grundlegenden Einstellungen. Wenn Sie lieber einen eigenen Standardkanal erstellen und verwenden möchten, legen Sie für default_notification_channel_id die ID Ihres Benachrichtigungskanalobjekts fest, wie gezeigt. FCM verwendet diesen Wert immer dann, wenn für eingehende Nachrichten nicht explizit ein Benachrichtigungskanal festgelegt ist. Weitere Informationen finden Sie unter Benachrichtigungskanäle verwalten. 
    • <meta-data
    android:name="com.google.firebase.messaging.default_notification_channel_id"
    android:value="@string/default_notification_channel_id" />

Laufzeitberechtigung zum Senden von Benachrichtigungen unter Android 13 und höher anfordern

In Android 13 wird eine neue Laufzeitberechtigung für das Anzeigen von Benachrichtigungen eingeführt. Dies betrifft alle Apps, die unter Android 13 oder höher ausgeführt werden und FCM-Benachrichtigungen verwenden.

Standardmäßig enthält das FCM SDK (Version 23.0.6 oder höher) die im Manifest definierte Berechtigung POST_NOTIFICATIONS. Ihre App muss jedoch auch die Laufzeitversion dieser Berechtigung mit der Konstante android.permission.POST_NOTIFICATIONS anfordern. Ihre App darf erst dann Benachrichtigungen anzeigen, wenn der Nutzer diese Berechtigung erteilt hat.

So fordern Sie die neue Laufzeitberechtigung an:

Kotlin

// Declare the launcher at the top of your Activity/Fragment:
private val requestPermissionLauncher = registerForActivityResult(
    ActivityResultContracts.RequestPermission(),
) { isGranted: Boolean ->
    if (isGranted) {
        // FCM SDK (and your app) can post notifications.
    } else {
        // TODO: Inform user that that your app will not show notifications.
    }
}

private fun askNotificationPermission() {
    // This is only necessary for API level >= 33 (TIRAMISU)
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
        if (ContextCompat.checkSelfPermission(this, Manifest.permission.POST_NOTIFICATIONS) ==
            PackageManager.PERMISSION_GRANTED
        ) {
            // FCM SDK (and your app) can post notifications.
        } else if (shouldShowRequestPermissionRationale(Manifest.permission.POST_NOTIFICATIONS)) {
            // TODO: display an educational UI explaining to the user the features that will be enabled
            //       by them granting the POST_NOTIFICATION permission. This UI should provide the user
            //       "OK" and "No thanks" buttons. If the user selects "OK," directly request the permission.
            //       If the user selects "No thanks," allow the user to continue without notifications.
        } else {
            // Directly ask for the permission
            requestPermissionLauncher.launch(Manifest.permission.POST_NOTIFICATIONS)
        }
    }
}

Java

// Declare the launcher at the top of your Activity/Fragment:
private final ActivityResultLauncher<String> requestPermissionLauncher =
        registerForActivityResult(new ActivityResultContracts.RequestPermission(), isGranted -> {
            if (isGranted) {
                // FCM SDK (and your app) can post notifications.
            } else {
                // TODO: Inform user that that your app will not show notifications.
            }
        });

private void askNotificationPermission() {
    // This is only necessary for API level >= 33 (TIRAMISU)
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
        if (ContextCompat.checkSelfPermission(this, Manifest.permission.POST_NOTIFICATIONS) ==
                PackageManager.PERMISSION_GRANTED) {
            // FCM SDK (and your app) can post notifications.
        } else if (shouldShowRequestPermissionRationale(Manifest.permission.POST_NOTIFICATIONS)) {
            // TODO: display an educational UI explaining to the user the features that will be enabled
            //       by them granting the POST_NOTIFICATION permission. This UI should provide the user
            //       "OK" and "No thanks" buttons. If the user selects "OK," directly request the permission.
            //       If the user selects "No thanks," allow the user to continue without notifications.
        } else {
            // Directly ask for the permission
            requestPermissionLauncher.launch(Manifest.permission.POST_NOTIFICATIONS);
        }
    }
}

Im Allgemeinen sollten Sie eine Benutzeroberfläche anzeigen, auf der dem Nutzer die Funktionen erklärt werden, die aktiviert werden, wenn er der App die Berechtigung zum Posten von Benachrichtigungen erteilt. Diese Benutzeroberfläche sollte dem Nutzer Optionen zum Zustimmen oder Ablehnen bieten, z. B. die Schaltflächen OK und Nein danke. Wenn der Nutzer OK auswählt, fordere die Berechtigung direkt an. Wenn der Nutzer Nein, danke auswählt, kann er ohne Benachrichtigungen fortfahren.

Weitere Best Practices dazu, wann Ihre App die Berechtigung POST_NOTIFICATIONS vom Nutzer anfordern sollte, finden Sie unter Laufzeitberechtigung für Benachrichtigungen.

Berechtigungen zum Senden von Benachrichtigungen für Apps, die auf Android 12L (API-Level 32) oder niedriger ausgerichtet sind

Android fragt den Nutzer automatisch um Erlaubnis, wenn deine App zum ersten Mal einen Benachrichtigungskanal erstellt, sofern sich die App im Vordergrund befindet. Es gibt jedoch wichtige Einschränkungen hinsichtlich des Zeitpunkts der Kanalerstellung und der Berechtigungsanfragen:

  • Wenn Ihre App den ersten Benachrichtigungskanal erstellt, während sie im Hintergrund ausgeführt wird, was das FCM SDK beim Empfang einer FCM-Benachrichtigung tut, lässt Android die Anzeige der Benachrichtigung nicht zu und fordert den Nutzer erst beim nächsten Öffnen der App auf, die Berechtigung zum Senden von Benachrichtigungen zu erteilen. Das bedeutet, dass alle Benachrichtigungen, die vor dem Öffnen der App und dem Akzeptieren der Berechtigung durch den Nutzer eingehen, verloren gehen.
  • Wir empfehlen dringend, deine App auf Android 13 oder höher auszurichten, um die APIs der Plattform zum Anfordern von Berechtigungen zu nutzen. Wenn das nicht möglich ist, sollte Ihre App Benachrichtigungskanäle erstellen, bevor Sie Benachrichtigungen an die App senden, um das Dialogfeld für die Berechtigung zum Senden von Benachrichtigungen auszulösen und sicherzustellen, dass keine Benachrichtigungen verloren gehen. Weitere Informationen finden Sie unter Best Practices für die Berechtigung zum Senden von Benachrichtigungen.

Optional: Berechtigung POST_NOTIFICATIONS entfernen

Standardmäßig enthält das FCM SDK die Berechtigung POST_NOTIFICATIONS. Wenn Ihre App keine Benachrichtigungen verwendet (weder über FCM-Benachrichtigungen, über ein anderes SDK noch direkt von Ihrer App gepostet) und Sie nicht möchten, dass Ihre App die Berechtigung enthält, können Sie sie mit der Markierung remove des Manifest-Mergers entfernen. Wenn Sie diese Berechtigung entfernen, werden alle Benachrichtigungen ausgeblendet, nicht nur die von FCM. Fügen Sie der Manifestdatei Ihrer App Folgendes hinzu:

<uses-permission android:name="android.permission.POST_NOTIFICATIONS" tools:node="remove"/>

Auf die Firebase-Installations-ID zugreifen

Beim ersten Start Ihrer App registriert das FCM SDK die App-Instanz bei FCM und gibt eine Kennung für die App-Instanz zurück. Wenn Sie einzelne App-Instanzen ansprechen möchten, müssen Sie auf diese Kennung zugreifen, indem Sie FirebaseMessagingService erweitern und onRegistered() überschreiben. Es empfiehlt sich, die zuletzt aktualisierte Kennung abzurufen, da sie sich nach dem ersten Start ändern kann.

Registrierung über Firebase-Installations-ID aktivieren

Wenn Sie die Registrierung Ihrer App-Instanz bei FCM mit der Firebase-Installations-ID (FID) aktivieren möchten, fügen Sie der Datei AndroidManifest.xml das folgende Metadaten-Flag hinzu: 
<meta-data
    android:name="firebase_messaging_installation_id_enabled"
    android:value="true" />

onRegistered()-Callback implementieren

App-Instanzen werden mit der Firebase-Installations-ID (FID) angesprochen, sobald sie bei FCM registriert sind. Wenn Sie die FID bei der Registrierung abrufen möchten, implementieren Sie den Callback onRegistered(). Sobald eine App-Instanz registriert ist, überwacht das FCM SDK automatisch FID-Änderungen und ruft den Callback auf, wenn eine Änderung erkannt wird. Wenn die automatische Initialisierung aktiviert ist, synchronisiert das FCM SDK automatisch mit dem FCM-Backend, um die Registrierung aktuell zu halten, und ruft den Callback auf, damit Ihr Anwendungsserver die aktuelle Kennung hat. Zum Schutz vor FID-Verlust oder veralteten FIDs sollten Sie die FID immer dann an Ihren Anwendungsserver senden, wenn dieser Callback ausgelöst wird.

Kotlin

  /**
   * There are three scenarios when `onRegistered` is called:
   * 1) Every time a manual `register()` call finishes successfully
   * 2) Whenever the FID is changed and the app is re-registered with FCM via the new FID.
   * 3) Automatically on app startup or routine sync when auto-initialization is enabled.
   * Under #2, there are three scenarios when the existing FID is changed:
   * A) App is restored to a new device
   * B) User uninstalls/reinstalls the app
   * C) User clears app data
   */
  override fun onRegistered(installationId: String) {
      Log.d(TAG, "Registered installation ID: $installationId")

      // Send the Firebase Installation ID to your app server.
      sendRegistrationToServer(installationId)
  }

Java

  /**
   * There are three scenarios when `onRegistered` is called:
   * 1) Every time a manual `register()` call finishes successfully
   * 2) Whenever the FID is changed and the app is re-registered with FCM via the new FID
   * 3) Automatically on app startup or routine sync when auto-initialization is enabled.
   * Under #2, there are three scenarios when the existing FID is changed:
   * A) App is restored to a new device
   * B) User uninstalls/reinstalls the app
   * C) User clears app data
   */
  @Override
  public void onRegistered(@NonNull String installationId) {
      Log.d(TAG, "Registered installation ID: " + installationId);

      // Send the Firebase Installation ID to your app server.
      sendRegistrationToServer(installationId);
  }

Manuelle Registrierung, wenn die automatische Initialisierung deaktiviert ist

Wenn Sie die automatische Initialisierung deaktivieren müssen, synchronisiert das FCM SDK beim Start nicht automatisch und löst auch nicht den Callback onRegistered() aus. Es wird dringend empfohlen, die automatische Initialisierung wieder zu aktivieren, nachdem die Berechtigungen zum Senden von Benachrichtigungen gewährt wurden. Weitere Informationen finden Sie unter Automatische Initialisierung wieder aktivieren.

Wenn die automatische Initialisierung deaktiviert bleiben muss, rufen Sie beim Start der App FirebaseMessaging.getInstance().register() auf, um die Registrierung und die FID-Bereitstellung über den Callback onRegistered() auszulösen. Sie können diesen Aufruf in der Methode onCreate() Ihrer Haupt-Activity ausführen.

Kotlin

  // Trigger manual registration if auto-initialization is turned off.
  // Consider calling this every time the app starts to guarantee sync status.
  FirebaseMessaging.getInstance().register()
      .addOnCompleteListener(this) { task ->
        if (!task.isSuccessful()) {
          // Registration failed. Consider retrying the registration with exponential backoff.
          Log.w(TAG, "Failed to register with Firebase Cloud Messaging", task.exception)
        }
        // Success! The Firebase Installation ID can be used to target messages to this app
        // instance and will be delivered asynchronously to your `onRegistered()` callback.
      }

Java

  // Trigger manual registration if auto-initialization is turned off.
  // Consider calling this every time the app starts to guarantee sync status.
  FirebaseMessaging.getInstance().register()
      .addOnCompleteListener(task -> {
        if (!task.isSuccessful()) {
          // Registration failed. Consider retrying the registration with exponential backoff.
          Log.w(TAG, "Failed to register with Firebase Cloud Messaging", task.exception)
        }
        // Success! The Firebase Installation ID can be used to target messages to this app
        // instance and will be delivered asynchronously to your `onRegistered()` callback.
      });

Auf das FCM-Registrierungstoken zugreifen (verworfen)

Beim ersten Start der App generiert das FCM SDK ein Registrierungstoken für die Client-App-Instanz. Wenn Sie einzelne App-Instanzen als Ziel festlegen oder Gerätegruppen erstellen möchten, müssen Sie auf dieses Token zugreifen. Erweitern Sie dazu FirebaseMessagingService und überschreiben Sie onNewToken. Da das Token nach dem ersten Start rotiert werden kann, wird dringend empfohlen, das neueste aktualisierte Registrierungstoken abzurufen.

Das Registrierungstoken kann sich in folgenden Fällen ändern:

  • Die App wird auf einem neuen Gerät wiederhergestellt.
  • Der Nutzer deinstalliert die App und installiert sie neu.
  • Der Nutzer löscht App-Daten.

Aktuelles Registrierungstoken abrufen

Wenn Sie das aktuelle Token abrufen müssen, rufen Sie FirebaseMessaging.getInstance().getToken() auf:

Kotlin

FirebaseMessaging.getInstance().token.addOnCompleteListener(OnCompleteListener { task ->
    if (!task.isSuccessful) {
        Log.w(TAG, "Fetching FCM registration token failed", task.exception)
        return@OnCompleteListener
    }

    // Get new FCM registration token
    val token = task.result

    // Log and toast
    val msg = getString(R.string.msg_token_fmt, token)
    Log.d(TAG, msg)
    Toast.makeText(baseContext, msg, Toast.LENGTH_SHORT).show()
})

Java

FirebaseMessaging.getInstance().getToken()
    .addOnCompleteListener(new OnCompleteListener<String>() {
        @Override
        public void onComplete(@NonNull Task<String> task) {
          if (!task.isSuccessful()) {
            Log.w(TAG, "Fetching FCM registration token failed", task.getException());
            return;
          }

          // Get new FCM registration token
          String token = task.getResult();

          // Log and toast
          String msg = getString(R.string.msg_token_fmt, token);
          Log.d(TAG, msg);
          Toast.makeText(MainActivity.this, msg, Toast.LENGTH_SHORT).show();
        }
    });

Tokengenerierung überwachen

Der Callback onNewToken wird immer dann ausgelöst, wenn ein neues Token generiert wird.

Kotlin

/**
 * Called if the FCM registration token is updated. This may occur if the security of
 * the previous token had been compromised. Note that this is called when the
 * FCM registration token is initially generated so this is where you would retrieve the token.
 */
override fun onNewToken(token: String) {
    Log.d(TAG, "Refreshed token: $token")

    // If you want to send messages to this application instance or
    // manage this apps subscriptions on the server side, send the
    // FCM registration token to your app server.
    sendRegistrationToServer(token)
}

Java

/**
 * There are two scenarios when onNewToken is called:
 * 1) When a new token is generated on initial app startup
 * 2) Whenever an existing token is changed
 * Under #2, there are three scenarios when the existing token is changed:
 * A) App is restored to a new device
 * B) User uninstalls/reinstalls the app
 * C) User clears app data
 */
@Override
public void onNewToken(@NonNull String token) {
    Log.d(TAG, "Refreshed token: " + token);

    // If you want to send messages to this application instance or
    // manage this apps subscriptions on the server side, send the
    // FCM registration token to your app server.
    sendRegistrationToServer(token);
}

Nachdem Sie das Token erhalten haben, können Sie es an Ihren Anwendungsserver senden und mit der von Ihnen bevorzugten Methode speichern.

Google Play-Dienste prüfen

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. Weitere Informationen finden Sie unter Google Play-Dienste einrichten. 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 ohne erfolgreiche Prüfung nicht 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.

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 Analytics-Erfassung und die automatische FCM-Initialisierung (beide müssen deaktiviert werden). Fügen Sie dazu die folgenden Metadatenwerte zu Ihrer AndroidManifest.xml hinzu:

<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 wieder aktivieren

Wenn Sie die automatische FCM-Initialisierung wieder aktivieren möchten, führen Sie einen Laufzeitaufruf aus:

Kotlin

Firebase.messaging.isAutoInitEnabled = true

Java

FirebaseMessaging.getInstance().setAutoInitEnabled(true);

Wenn Sie die Analytics-Erfassung wieder aktivieren möchten, rufen Sie die Methode setAnalyticsCollectionEnabled() der Klasse FirebaseAnalytics auf. Beispiel:

setAnalyticsCollectionEnabled(true);

Diese Werte bleiben nach dem Festlegen auch nach einem Neustart der App erhalten.

Benachrichtigung senden

Damit Ihr Android-Client richtig eingerichtet ist, können Sie anhand der folgenden Anleitung eine Testbenachrichtigung senden:

  1. Installieren Sie die App auf dem Zielgerät und führen Sie sie aus.

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

  3. Rufen Sie in der Firebase-Konsole 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. Alle anderen sind optional.

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

  7. Geben Sie im Feld FCM-Registrierungstoken hinzufügen das Registrierungstoken ein, das Sie in einem vorherigen Abschnitt dieser Anleitung erhalten haben.

  8. Wählen Sie Testen aus.

Das Ziel-Clientgerät mit der App im Hintergrund sollte die Benachrichtigung erhalten.

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.

Nächste Schritte

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