Firebase Cloud Messaging-Client-App für Android einrichten

Für FCM-Kunden sind Geräte mit Android 5.0 oder höher erforderlich, auf denen auch die Google Play Store App installiert ist, oder ein Emulator mit Android 5.0 und Google APIs. Sie sind nicht darauf beschränkt, Ihre Android-Apps über den Google Play Store bereitzustellen.

SDK einrichten

In diesem Abschnitt werden Aufgaben beschrieben, die Sie möglicherweise bereits ausgeführt haben, wenn Sie bereits andere Firebase-Funktionen für Ihre App aktiviert haben. Fügen Sie Ihrem Android-Projekt Firebase hinzu

App-Manifest bearbeiten

Fügen Sie dem Manifest Ihrer App Folgendes hinzu:

  • Ein Dienst, der FirebaseMessagingService erweitert. Dies ist erforderlich, wenn Sie Nachrichten nicht nur in Apps im Hintergrund empfangen, sondern auch Nachrichten verarbeiten möchten. Wenn Sie Benachrichtigungen in Apps im Vordergrund erhalten, Datennutzlasten empfangen oder Upstream-Nachrichten senden 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 zum Festlegen eines Standardsymbols und einer Standardfarbe für Benachrichtigungen. Android verwendet diese Werte, wenn für eingehende 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" />
  • Optional: Ab Android 8.0 (API-Ebene 26) werden Benachrichtigungskanäle unterstützt und empfohlen. FCM stellt einen Standardbenachrichtigungskanal mit grundlegenden Einstellungen bereit. Wenn Sie lieber einen eigenen Standardkanal erstellen und verwenden möchten, legen Sie default_notification_channel_id wie gezeigt 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" />

Berechtigung für Laufzeitbenachrichtigungen unter Android 13 und höher anfordern

Mit Android 13 wird eine neue Laufzeitberechtigung für das Zeigen von Benachrichtigungen eingeführt. Das gilt für alle Apps, die unter Android 13 oder höher ausgeführt werden und FCM-Benachrichtigungen verwenden.

Das FCM SDK (Version 23.0.6 oder höher) enthält standardmäßig die im Manifest definierte Berechtigung POST_NOTIFICATIONS. Ihre App muss jedoch auch die Laufzeitversion dieser Berechtigung über die 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+KTX

// 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 den Nutzern erklärt wird, welche Funktionen aktiviert werden, wenn sie der App die Berechtigung zum Senden von Benachrichtigungen erteilen. Diese Benutzeroberfläche sollte den Nutzern die Möglichkeit bieten, zuzustimmen oder abzulehnen, z. B. über 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, muss er ohne Benachrichtigungen fortfahren können.

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

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

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

  • Wenn Ihre App ihren ersten Benachrichtigungskanal erstellt, wenn 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 dann zur Genehmigung der Benachrichtigungsberechtigung auf, wenn Ihre App das nächste Mal geöffnet wird. Das bedeutet, dass alle Benachrichtigungen verloren gehen, die vor dem Öffnen der App und der Zustimmung des Nutzers zur Berechtigung eingehen.
  • Wir empfehlen Ihnen dringend, Ihre App so zu aktualisieren, dass sie auf Android 13 oder höher ausgerichtet ist, damit Sie die APIs der Plattform nutzen können, um eine Berechtigung anzufordern. Wenn das nicht möglich ist, sollte Ihre App Benachrichtigungskanäle erstellen, bevor Sie Benachrichtigungen an die App senden, um den Dialog zur Benachrichtigungsberechtigung auszulösen und dafür zu sorgen, dass keine Benachrichtigungen verloren gehen. Weitere Informationen finden Sie unter Best Practices für Berechtigungen für Benachrichtigungen.

Optional: Berechtigung „POST_NOTIFICATIONS“ entfernen

Das FCM SDK enthält standardmäßig die Berechtigung POST_NOTIFICATIONS. Wenn deine App keine Benachrichtigungen verwendet (über FCM-Benachrichtigungen, über ein anderes SDK oder direkt von deiner App veröffentlicht) und du nicht möchtest, dass deine App die Berechtigung enthält, kannst du sie mit der Markierung remove der Manifestzusammenführung entfernen. Wenn Sie diese Berechtigung entfernen, werden nicht nur FCM-Benachrichtigungen, sondern alle Benachrichtigungen deaktiviert. Fügen Sie der Manifestdatei Ihrer App Folgendes hinzu:

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

Auf das Token für die Geräteregistrierung zugreifen

Beim ersten Starten Ihrer App generiert das FCM SDK ein Registrierungstoken für die Client-App-Instanz. Wenn Sie ein Targeting auf einzelne Geräte vornehmen oder Gerätegruppen erstellen möchten, müssen Sie auf dieses Token zugreifen. Dazu müssen Sie FirebaseMessagingService erweitern und onNewToken überschreiben.

In diesem Abschnitt wird beschrieben, wie Sie das Token abrufen und Änderungen am Token im Blick behalten. Da das Token nach dem ersten Start rotiert werden kann, empfehlen wir Ihnen dringend, das aktuellste 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 dann wieder
  • Der Nutzer löscht die App-Daten.

Aktuelles Registrierungstoken abrufen

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

Kotlin+KTX

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 beobachten

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

Kotlin+KTX

/**
 * 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 du das Token erhalten hast, kannst du es an deinen App-Server senden und mit deiner bevorzugten Methode speichern.

Auf Google Play-Dienste prüfen

Apps, die das Play Services SDK verwenden, sollten vor dem Zugriff auf die Funktionen der Google Play-Dienste immer prüfen, ob auf dem Gerät eine kompatible APK für die Google Play-Dienste installiert ist. Es wird empfohlen, dies an zwei Stellen zu tun: in der onCreate()-Methode der Hauptaktivität und in der onResume()-Methode. Durch das Einchecken in onCreate() wird sichergestellt, dass die Anwendung 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, z. B. über die Schaltfläche „Zurück“, zur laufenden App zurückkehrt.

Wenn auf dem Gerät keine kompatible Version der Google Play-Dienste installiert ist, kann Ihre App GoogleApiAvailability.makeGooglePlayServicesAvailable() aufrufen, damit Nutzer 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 die Konfigurationsdaten in Firebase hoch. Wenn Sie die automatische Tokengenerierung verhindern möchten, deaktivieren Sie die Analytics-Erfassung und die automatische FCM-Initialisierung (Sie müssen beide deaktivieren). Fügen Sie dazu die folgenden Metadatenwerte zu 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" />

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

Kotlin+KTX

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 dem Neustart der App erhalten.

Nächste Schritte

Nachdem die Client-App eingerichtet wurde, können Sie mit Notifications Composer nachgelagerte Nachrichten senden. Diese Funktion wird im Beispiel für den Schnellstart veranschaulicht, das Sie herunterladen, ausführen und prüfen können.

Wenn Sie Ihrer App ein anderes, erweitertes Verhalten hinzufügen möchten, können Sie einen Intent-Filter deklarieren und eine Aktivität implementieren, um auf eingehende Nachrichten zu reagieren. Weitere Informationen finden Sie in den Leitfäden zum Senden von Nachrichten von einem Anwendungsserver:

Beachten Sie, dass Sie für die Nutzung dieser Funktionen eine Serverimplementierung und die Serverprotokolle (HTTP oder XMPP) oder eine Implementierung des Admin SDK benötigen.