Richten Sie eine Firebase Cloud Messaging-Client-App auf Android ein

Für FCM-Clients sind Geräte mit Android 4.4 oder höher erforderlich, auf denen auch die Google Play Store-App installiert ist, oder ein Emulator mit Android 4.4 und Google APIs. Beachten Sie, dass Sie Ihre Android-Apps nicht nur über den Google Play Store bereitstellen können.

Richten Sie das SDK ein

In diesem Abschnitt werden Aufgaben behandelt, die Sie möglicherweise erledigt haben, wenn Sie bereits andere Firebase-Funktionen für Ihre App aktiviert haben. Wenn Sie dies noch nicht getan haben, fügen Sie Firebase zu Ihrem Android-Projekt hinzu

Bearbeiten Sie Ihr App-Manifest

Fügen Sie dem Manifest Ihrer App Folgendes hinzu:

  • Ein Dienst, der FirebaseMessagingService erweitert. Dies ist erforderlich, wenn Sie Nachrichten verarbeiten möchten, die über den Empfang von Benachrichtigungen für Apps im Hintergrund hinausgehen. Um Benachrichtigungen in Apps im Vordergrund zu erhalten, Datennutzlast zu empfangen, Upstream-Nachrichten zu senden usw. 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) Innerhalb der Anwendungskomponente Metadatenelemente zum Festlegen eines Standardbenachrichtigungssymbols und einer Standardfarbe. Android verwendet diese Werte immer dann, wenn für eingehende Nachrichten das Symbol oder die Farbe nicht explizit festgelegt werden.
  • <!-- 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) und höher werden Benachrichtigungskanäle unterstützt und empfohlen. FCM bietet einen Standardbenachrichtigungskanal mit Grundeinstellungen. Wenn Sie lieber Ihren 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 immer dann, wenn eingehende Nachrichten keinen expliziten Benachrichtigungskanal festlegen. 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" />

Fordern Sie die Berechtigung für Laufzeitbenachrichtigungen auf Android 13+ an

Android 13 führt eine neue Laufzeitberechtigung zum Anzeigen von Benachrichtigungen ein. Dies betrifft alle Apps, die auf Android 13 oder höher laufen und FCM-Benachrichtigungen verwenden.

Standardmäßig enthält das FCM SDK (Version 23.0.6 oder höher) die im Manifest definierte POST_NOTIFICATIONS Berechtigung. Allerdings muss Ihre App auch die Laufzeitversion dieser Berechtigung über die Konstante android.permission.POST_NOTIFICATIONS anfordern. Ihre App darf keine Benachrichtigungen anzeigen, bis der Benutzer 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, die dem Benutzer die Funktionen erklärt, die aktiviert werden, wenn er der App Berechtigungen zum Posten von Benachrichtigungen erteilt. Diese Benutzeroberfläche sollte dem Benutzer Optionen zum Zustimmen oder Ablehnen bieten, z. B. die Schaltflächen „OK“ und „Nein, danke“ . Wenn der Benutzer OK auswählt, fordern Sie direkt die Berechtigung an. Wenn der Benutzer Nein danke auswählt, erlauben Sie dem Benutzer, ohne Benachrichtigungen fortzufahren.

Weitere Best Practices dazu, wann Ihre App die POST_NOTIFICATIONS -Berechtigung vom Benutzer anfordern sollte, finden Sie unter Benachrichtigungslaufzeitberechtigung .

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

Android fragt den Benutzer automatisch um Erlaubnis, wenn Ihre App zum ersten Mal einen Benachrichtigungskanal erstellt, sofern sich die App im Vordergrund befindet. Allerdings gibt es wichtige Vorbehalte bezüglich des Zeitpunkts der Kanalerstellung und der Erlaubnisanfragen:

  • Wenn Ihre App ihren ersten Benachrichtigungskanal erstellt, während sie im Hintergrund ausgeführt wird (was das FCM SDK tut, wenn eine FCM-Benachrichtigung empfangen wird), lässt Android die Anzeige der Benachrichtigung nicht zu und fordert den Benutzer erst beim nächsten Mal zur Benachrichtigungsberechtigung auf Zeit, zu der Ihre App geöffnet wird. Dies bedeutet, dass alle Benachrichtigungen, die Sie erhalten, bevor Ihre App geöffnet wird und der Benutzer die Berechtigung akzeptiert, verloren gehen .
  • Wir empfehlen Ihnen dringend, Ihre App auf Android 13+ zu aktualisieren, um die APIs der Plattform zum Anfordern von Berechtigungen nutzen zu können. Wenn dies nicht möglich ist, sollte Ihre App Benachrichtigungskanäle erstellen, bevor Sie Benachrichtigungen an die App senden, um den Benachrichtigungsberechtigungsdialog auszulösen und sicherzustellen, dass keine Benachrichtigungen verloren gehen. Weitere Informationen finden Sie unter Best Practices für Benachrichtigungsberechtigungen .

Optional: Entfernen Sie POST_NOTIFICATIONS Berechtigung

Standardmäßig enthält das FCM SDK die Berechtigung POST_NOTIFICATIONS . Wenn Ihre App keine Benachrichtigungen verwendet (sei es über FCM-Benachrichtigungen, über ein anderes SDK oder direkt von Ihrer App gepostet) und Sie nicht möchten, dass Ihre App die Berechtigung enthält, können Sie sie mithilfe der Markierung remove der Manifestzusammenführung entfernen. Beachten Sie, dass durch das Entfernen dieser Berechtigung die Anzeige aller Benachrichtigungen verhindert wird, nicht nur der FCM-Benachrichtigungen. Fügen Sie der Manifestdatei Ihrer App Folgendes hinzu:

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

Greifen Sie auf das Geräteregistrierungstoken zu

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

In diesem Abschnitt wird beschrieben, wie Sie das Token abrufen und Änderungen am Token überwachen. Da das Token nach dem ersten Start rotiert werden könnte, wird dringend empfohlen, das neueste aktualisierte Registrierungstoken abzurufen.

Das Registrierungstoken kann sich ändern, wenn:

  • Die App wird auf einem neuen Gerät wiederhergestellt
  • Der Benutzer deinstalliert/neuinstalliert die App
  • Der Benutzer löscht App-Daten.

Rufen Sie das aktuelle Registrierungstoken ab

Wenn Sie das aktuelle Token abrufen müssen, 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();
        }
    });

Überwachen Sie die Token-Generierung

Der onNewToken Rückruf wird immer dann 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 Sie das Token erhalten haben, können Sie es an Ihren App-Server senden und mit Ihrer bevorzugten Methode speichern.

Suchen Sie nach Google Play-Diensten

Apps, die auf dem Play Services SDK basieren, sollten das Gerät immer auf ein kompatibles Google Play Services APK überprüfen, bevor sie auf die Funktionen der Google Play Services 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() stellt sicher, dass die App ohne eine erfolgreiche Prüfung nicht verwendet werden kann. Die Prüfung in onResume() stellt sicher, dass die Prüfung weiterhin durchgeführt wird, wenn der Benutzer auf andere Weise zur laufenden App zurückkehrt, beispielsweise über die Schaltfläche „Zurück“.

Wenn das Gerät nicht über eine kompatible Version der Google Play-Dienste verfügt, kann Ihre App GoogleApiAvailability.makeGooglePlayServicesAvailable() aufrufen, um Benutzern das Herunterladen von Google Play-Diensten aus dem Play Store zu ermöglichen.

Verhindern Sie die automatische Initialisierung

Wenn ein FCM-Registrierungstoken generiert wird, lädt die Bibliothek die Kennung und Konfigurationsdaten in Firebase hoch. Wenn Sie die automatische Tokengenerierung lieber verhindern möchten, deaktivieren Sie die Analytics-Erfassung und die automatische FCM-Initialisierung (Sie müssen beide deaktivieren), indem Sie diese Metadatenwerte zu Ihrer 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" />

Um die automatische FCM-Initialisierung wieder zu aktivieren, führen Sie einen Laufzeitaufruf durch:

Kotlin+KTX

Firebase.messaging.isAutoInitEnabled = true

Java

FirebaseMessaging.getInstance().setAutoInitEnabled(true);

Um die Analytics-Sammlung wieder zu aktivieren, rufen Sie die Methode setAnalyticsCollectionEnabled() der FirebaseAnalytics -Klasse auf. Zum Beispiel:

setAnalyticsCollectionEnabled(true);

Diese Werte bleiben über App-Neustarts hinweg bestehen, sobald sie festgelegt wurden.

Nächste Schritte

Nachdem die Client-App eingerichtet ist, können Sie mit dem Notifications Composer mit dem Versenden von Downstream-Nachrichten beginnen. Diese Funktionalität wird im Schnellstartbeispiel demonstriert, das Sie herunterladen, ausführen und überprüfen können.

Um Ihrer App weiteres, erweitertes Verhalten hinzuzufügen, können Sie einen Absichtsfilter deklarieren und eine Aktivität implementieren, um auf eingehende Nachrichten zu reagieren. Einzelheiten finden Sie in den Anleitungen zum Senden von Nachrichten von einem App-Server:

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