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, damit Sie zuverlässig Nachrichten senden können.

FCM Clients erfordern Geräte mit Android 6.0 oder höher, auf denen auch die Google Play Store App installiert ist, oder einen Emulator mit Android 6.0 und Google APIs. Sie können Ihre Android-Apps nicht nur über den Google Play Store bereitstellen.

SDK einrichten

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

Für eine optimale Nutzung von FCM empfehlen wir dringend die Aktivierung von Google Analytics in Ihrem Projekt. 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 Notifications in Apps im Vordergrund erhalten, Daten-Nutzlasten empfangen und mehr 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>
AndroidManifest.xml

• Optional: Metadatenelemente in der Anwendungskomponente, um ein Standardbenachrichtigung symbol und eine Standardfarbe festzulegen. Android verwendet diese Werte, wenn in eingehenden Nachrichten kein Symbol oder keine Farbe explizit 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" />
AndroidManifest.xml

• Optional: Unter Android 8.0 (API-Ebene 26) und höher, Benachrichtigungskanäle werden unterstützt und empfohlen. FCM bietet einen Standard Benachrichtigungskanal mit grundlegenden Einstellungen. Wenn Sie einen eigenen Standardkanal erstellen und verwenden möchten, legen Sie default_notification_channel_id auf die ID Ihres Benachrichtigungskanalobjekts fest. FCM verwendet diesen Wert, wenn in eingehenden Nachrichten kein Benachrichtigungskanal explizit 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" />
AndroidManifest.xml

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

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

Standardmäßig enthält das FCM SDK (Version 23.0.6 oder höher) die POST_NOTIFICATIONS im Manifest definierte Berechtigung. Ihre App muss jedoch auch die Laufzeitversion dieser Berechtigung mit der Konstanten 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)
        }
    }
}
MainActivity.kt

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);
        }
    }
}
MainActivity.java

Im Allgemeinen sollten Sie eine UI anzeigen, in der dem Nutzer die Funktionen erläutert werden, die aktiviert werden, wenn er der App die Berechtigung zum Senden von Benachrichtigungen erteilt. Diese UI sollte dem Nutzer Optionen zum Zustimmen oder Ablehnen bieten, z. B. die Schaltflächen OK und Nein, danke. Wenn der Nutzer OK auswählt, fordern Sie 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 vom Nutzer anfordern sollte, finden Sie unter Laufzeitberechtigung für Benachrichtigungen POST_NOTIFICATIONS.

Benachrichtigungsberechtigungen für Apps, die auf Android 12L (API-Ebene 32) oder niedriger ausgerichtet sind

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

• Wenn Ihre App ihren ersten Benachrichtigungskanal erstellt, während sie im Hintergrund ausgeführt wird (was das FCM SDK beim Empfang einer FCM Benachrichtigung tut), lässt Android nicht zu, dass die Benachrichtigung angezeigt wird, und fordert den Nutzer erst beim nächsten Öffnen der App zur Erteilung der Berechtigung zum Senden von Benachrichtigungen auf. Das bedeutet, dass alle Benachrichtigungen, die empfangen werden, bevor Ihre App geöffnet wird und der Nutzer die Berechtigung erteilt, verloren gehen.
• Wir empfehlen dringend, Ihre App so zu aktualisieren, dass sie auf Android 13 oder höher ausgerichtet ist, um die APIs der Plattform zum Anfordern der Berechtigung 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 POST_NOTIFICATIONS Berechtigung. Wenn Ihre App keine Benachrichtigungen verwendet (weder über FCM Benachrichtigungen noch über ein anderes SDK oder direkt von Ihrer App gesendet) und Sie nicht möchten, dass Ihre App die Berechtigung enthält, können Sie sie mit dem Marker des Manifest-Mergers remove entfernen. Beachten Sie, dass durch das Entfernen dieser Berechtigung die Anzeige aller Benachrichtigungen verhindert wird, nicht nur FCM Benachrichtigungen. Fügen Sie der Manifestdatei Ihrer App Folgendes hinzu:

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

Auf das FCM Registrierungstoken zugreifen

Tipp: Unter Best Practices für die Verwaltung von FCM-Registrierungstokens finden Sie Tipps zur Verwaltung von Tokens.

Beim ersten Start Ihrer App generiert das FCM SDK ein Registrierung Token für die Client-App-Instanz. Wenn Sie einzelne App-Instanzen ansprechen oder Gerätegruppen erstellen möchten, müssen Sie auf dieses Token zugreifen, indem Sie FirebaseMessagingService erweitern und onNewToken überschreiben. Da das Token nach dem ersten Start möglicherweise rotiert wird, empfehlen wir dringend, das neueste aktualisierte Registrierungs Token abzurufen.

Das Registrierungstoken kann sich ändern, wenn:

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

Apps, die noch die veralteten Instance ID APIs für die Tokenverwaltung verwenden, sollten die gesamte Tokenlogik aktualisieren, um die hier beschriebenen FCM APIs zu verwenden.

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();
        }
    });

Tokenerstellung ü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)
}
MyFirebaseMessagingService.kt

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);
}
MyFirebaseMessagingService.java

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

Auf Google Play-Dienste prüfen

Apps, die auf das Play Services SDK angewiesen sind, sollten immer prüfen, ob auf dem Gerät ein kompatibles APK für die Google Play-Dienste vorhanden ist, bevor sie auf Funktionen der Google Play-Dienste zugreifen. Weitere Informationen finden Sie unterGoogle Play Dienste einrichten. Wir empfehlen, dies an zwei Stellen zu tun: in der Methode onCreate() der Hauptaktivität und in der Methode onResume(). Die Prüfung in onCreate() stellt sicher, dass die App nicht ohne erfolgreiche Prüfung verwendet werden kann. Die Prüfung in onResume() stellt sicher, 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 vorhanden ist, kann Ihre App GoogleApiAvailability.makeGooglePlayServicesAvailable() aufrufen, damit Nutzer die Google Play-Dienste aus dem Play Store herunterladen können.

Automatische Initialisierung verhindern

Wenn ein FCM Registrierungstoken generiert wird, lädt die Bibliothek die Kennung und Konfigurationsdaten in Firebase hoch. Wenn Sie die automatische Tokenerstellung verhindern möchten, deaktivieren Sie die Analytics-Erfassung 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" />
AndroidManifest.xml

So aktivieren Sie die automatische FCM-Initialisierung wieder:

Kotlin

Firebase.messaging.isAutoInitEnabled = true
MainActivity.kt

Java

FirebaseMessaging.getInstance().setAutoInitEnabled(true);
MainActivity.java

Rufen Sie die setAnalyticsCollectionEnabled() Methode der FirebaseAnalytics Klasse auf, um die Analytics-Erfassung wieder zu aktivieren. Beispiel:

setAnalyticsCollectionEnabled(true);

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

Benachrichtigung senden

Um zu prüfen, ob Ihr Android-Client richtig eingerichtet ist, können Sie eine Testbenachrichtigung senden. Folgen Sie dazu dieser Anleitung:

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

2. Achten Sie darauf, dass sich die App auf dem Gerät im Hintergrund befindet.

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. Alle anderen Felder 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 dieses Leitfadens erhalten haben.

8. Wählen Sie Testen aus.

Das Zielgerät sollte 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 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.

Nächste Schritte

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

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