获取我们在 Firebase 峰会上发布的所有信息,了解 Firebase 可如何帮助您加快应用开发速度并满怀信心地运行应用。了解详情

Configurer une application cliente Firebase Cloud Messaging sur Android

Les clients FCM nécessitent des appareils exécutant Android 4.4 ou version ultérieure sur lesquels l'application Google Play Store est également installée, ou un émulateur exécutant Android 4.4 avec les API Google. Notez que vous n'êtes pas limité au déploiement de vos applications Android via Google Play Store.

Configurer le SDK

Cette section couvre les tâches que vous avez peut-être effectuées si vous avez déjà activé d'autres fonctionnalités Firebase pour votre application. Si vous ne l'avez pas déjà fait, ajoutez Firebase à votre projet Android

Modifier le manifeste de votre application

Ajoutez les éléments suivants au fichier manifeste de votre application :

  • Un service qui étend FirebaseMessagingService . Ceci est nécessaire si vous souhaitez gérer des messages au-delà de la réception de notifications sur les applications en arrière-plan. Pour recevoir des notifications dans des applications au premier plan, pour recevoir des données utiles, pour envoyer des messages en amont, etc., vous devez étendre ce service.
  • <service
        android:name=".java.MyFirebaseMessagingService"
        android:exported="false">
        <intent-filter>
            <action android:name="com.google.firebase.MESSAGING_EVENT" />
        </intent-filter>
    </service>
  • (Facultatif) Dans le composant d'application, des éléments de métadonnées pour définir une icône et une couleur de notification par défaut. Android utilise ces valeurs chaque fois que les messages entrants ne définissent pas explicitement l'icône ou la couleur.
  • <!-- 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" />
  • (Facultatif) À partir d'Android 8.0 (API niveau 26) et supérieur, les canaux de notification sont pris en charge et recommandés. FCM fournit un canal de notification par défaut avec des paramètres de base. Si vous préférez créer et utiliser votre propre canal par défaut, définissez default_notification_channel_id sur l'ID de votre objet de canal de notification, comme indiqué ; FCM utilisera cette valeur chaque fois que les messages entrants ne définissent pas explicitement un canal de notification. Pour en savoir plus, consultez Gérer les canaux de notification .
  • <meta-data
        android:name="com.google.firebase.messaging.default_notification_channel_id"
        android:value="@string/default_notification_channel_id" />

Demander l'autorisation de notification d'exécution sur Android 13+

Android 13 introduit une nouvelle autorisation d'exécution pour afficher les notifications. Cela affecte toutes les applications exécutées sur Android 13 ou supérieur qui utilisent les notifications FCM.

Par défaut, le SDK FCM (version 23.0.6 ou ultérieure) inclut l'autorisation POST_NOTIFICATIONS définie dans le manifeste. Cependant, votre application devra également demander la version d'exécution de cette autorisation via la constante android.permission.POST_NOTIFICATIONS . Votre application ne sera pas autorisée à afficher des notifications tant que l'utilisateur n'aura pas accordé cette autorisation.

Pour demander la nouvelle autorisation d'exécution :

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

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

En règle générale, vous devez afficher une interface utilisateur expliquant à l'utilisateur les fonctionnalités qui seront activées s'il autorise l'application à publier des notifications. Cette interface utilisateur doit fournir à l'utilisateur des options pour accepter ou refuser, telles que les boutons OK et Non merci . Si l'utilisateur sélectionne OK , demandez directement l'autorisation. Si l'utilisateur sélectionne Non merci , autorisez l'utilisateur à continuer sans notifications.

Voir Autorisation d'exécution des notifications pour plus de bonnes pratiques sur le moment où votre application doit demander l'autorisation POST_NOTIFICATIONS à l'utilisateur.

Autorisations de notification pour les applications ciblant Android 12L (niveau API 32) ou inférieur

Android demande automatiquement l'autorisation de l'utilisateur la première fois que votre application crée un canal de notification, tant que l'application est au premier plan. Cependant, il existe des mises en garde importantes concernant le moment de la création de la chaîne et des demandes d'autorisation :

  • Si votre application crée son premier canal de notification lorsqu'elle s'exécute en arrière-plan (ce que fait le SDK FCM lors de la réception d'une notification FCM), Android n'autorisera pas l'affichage de la notification et ne demandera pas à l'utilisateur l'autorisation de notification avant le prochain l'heure à laquelle votre application est ouverte. Cela signifie que toutes les notifications reçues avant l'ouverture de votre application et que l'utilisateur accepte l'autorisation seront perdues .
  • Nous vous recommandons fortement de mettre à jour votre application pour cibler Android 13+ afin de profiter des API de la plateforme pour demander l'autorisation. Si cela n'est pas possible, votre application doit créer des canaux de notification avant d'envoyer des notifications à l'application afin de déclencher la boîte de dialogue d'autorisation de notification et de s'assurer qu'aucune notification n'est perdue. Voir les meilleures pratiques d'autorisation de notification pour plus d'informations.

Facultatif : supprimer l'autorisation POST_NOTIFICATIONS

Par défaut, le SDK FCM inclut l'autorisation POST_NOTIFICATIONS . Si votre application n'utilise pas de messages de notification (que ce soit via des notifications FCM, via un autre SDK ou directement publié par votre application) et que vous ne souhaitez pas que votre application inclue l'autorisation, vous pouvez la supprimer à l'aide du marqueur remove de la fusion du manifeste . Gardez à l'esprit que la suppression de cette autorisation empêche l'affichage de toutes les notifications, et pas seulement des notifications FCM. Ajoutez les éléments suivants au fichier manifeste de votre application :

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

Accéder au jeton d'enregistrement de l'appareil

Lors du démarrage initial de votre application, le SDK FCM génère un jeton d'enregistrement pour l'instance de l'application cliente. Si vous souhaitez cibler des appareils uniques ou créer des groupes d'appareils, vous devrez accéder à ce jeton en étendant FirebaseMessagingService et en remplaçant onNewToken .

Cette section décrit comment récupérer le jeton et comment surveiller les modifications apportées au jeton. Étant donné que le jeton peut subir une rotation après le démarrage initial, il est fortement recommandé de récupérer le dernier jeton d'enregistrement mis à jour.

Le jeton d'enregistrement peut changer lorsque :

  • L'application est restaurée sur un nouvel appareil
  • L'utilisateur désinstalle/réinstalle l'application
  • L'utilisateur efface les données de l'application.

Récupérer le jeton d'enregistrement actuel

Lorsque vous devez récupérer le jeton actuel, appelez FirebaseMessaging.getInstance().getToken() :

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

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

Surveiller la génération de jetons

Le rappel onNewToken se déclenche chaque fois qu'un nouveau jeton est généré.

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

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

Une fois que vous avez obtenu le jeton, vous pouvez l'envoyer à votre serveur d'applications et le stocker en utilisant votre méthode préférée.

Vérifiez les services Google Play

Les applications qui s'appuient sur le SDK des services Play doivent toujours rechercher sur l'appareil un APK de services Google Play compatible avant d'accéder aux fonctionnalités des services Google Play. Il est recommandé de le faire à deux endroits : dans la méthode onCreate() de l'activité principale et dans sa méthode onResume() . La vérification dans onCreate() garantit que l'application ne peut pas être utilisée sans une vérification réussie. La vérification dans onResume() garantit que si l'utilisateur revient à l'application en cours d'exécution par d'autres moyens, par exemple via le bouton de retour, la vérification est toujours effectuée.

Si l'appareil ne dispose pas d'une version compatible des services Google Play, votre application peut appeler GoogleApiAvailability.makeGooglePlayServicesAvailable() pour permettre aux utilisateurs de télécharger les services Google Play à partir du Play Store.

Empêcher l'initialisation automatique

Lorsqu'un jeton d'enregistrement FCM est généré, la bibliothèque télécharge l'identifiant et les données de configuration dans Firebase. Si vous préférez empêcher la génération automatique de jetons, désactivez la collecte Analytics et l'initialisation automatique FCM (vous devez désactiver les deux) en ajoutant ces valeurs de métadonnées à votre AndroidManifest.xml :

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

Pour réactiver l'initialisation automatique FCM, effectuez un appel d'exécution :

Java

FirebaseMessaging.getInstance().setAutoInitEnabled(true);

Kotlin+KTX

Firebase.messaging.isAutoInitEnabled = true

Pour réactiver la collecte Analytics, appelez la méthode setAnalyticsCollectionEnabled() de la classe FirebaseAnalytics . Par exemple:

setAnalyticsCollectionEnabled(true);

Ces valeurs persistent lors des redémarrages de l'application une fois définies.

Prochaines étapes

Une fois l'application cliente configurée, vous êtes prêt à commencer à envoyer des messages en aval avec l' éditeur de notifications . Cette fonctionnalité est illustrée dans l' exemple de démarrage rapide , que vous pouvez télécharger, exécuter et examiner.

Pour ajouter d'autres comportements plus avancés à votre application, vous pouvez déclarer un filtre d'intention et implémenter une activité pour répondre aux messages entrants. Pour plus de détails, consultez les guides d'envoi de messages depuis un serveur d'applications :

Gardez à l'esprit que, pour tirer parti de ces fonctionnalités, vous aurez besoin d'une implémentation de serveur et des protocoles de serveur (HTTP ou XMPP), ou d'une implémentation du SDK Admin .