Premiers pas avec Firebase Cloud Messaging dans les applications Android

Sélectionnez une plate-forme : iOS+ Android Web Flutter Unity C++


Ce guide explique comment utiliser Firebase Cloud Messaging dans vos applications clientes Android pour envoyer des messages de manière fiable.

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

Configurez le SDK

Si ce n'est pas déjà fait, ajoutez Firebase à votre projet Android.

Pour une expérience optimale avec FCM, nous vous recommandons vivement d'activer Google Analytics dans votre projet. Google Analytics est requis pour les rapports de distribution des messages pour FCM.

Modifier le fichier manifeste de votre application

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

  • Un service qui étend FirebaseMessagingService. Cette étape est obligatoire si vous souhaitez gérer les messages au-delà de la réception de notifications sur les applications en arrière-plan. Pour recevoir des notifications dans les applications au premier plan, recevoir une charge utile de données et plus encore, 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, éléments de métadonnées permettant de 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 d'icône ni de 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 (niveau d'API 26), les canaux de notification sont compatibles 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 ou version ultérieure

Android 13 introduit une nouvelle autorisation d'exécution pour l'affichage des notifications. Cela concerne toutes les applications exécutées sur Android 13 ou version ultérieure qui utilisent des notifications FCM.

Par défaut, le SDK FCM (version 23.0.6 ou ultérieure) inclut l'autorisation POST_NOTIFICATIONS définie dans le fichier manifeste. Toutefois, votre application devra également demander la version d'exécution de cette autorisation à l'aide de 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 :

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

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

Consultez Autorisation d'exécution des notifications pour découvrir d'autres bonnes pratiques concernant le moment où votre application doit demander l'autorisation POST_NOTIFICATIONS à l'utilisateur.

Autorisations de notification pour les applications ciblant Android 12L (niveau d'API 32) ou une version antérieure

Android demande automatiquement l'autorisation à l'utilisateur la première fois que votre application crée un canal de notification, tant que l'application est au premier plan. Toutefois, il existe des mises en garde importantes concernant le moment de la création du canal et les 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 lorsqu'il reçoit une notification FCM, Android n'autorise pas l'affichage de la notification et n'invite pas l'utilisateur à accorder l'autorisation de notification avant la prochaine ouverture de l'application. Cela signifie que toutes les notifications reçues avant l'ouverture de votre application et l'acceptation de l'autorisation par l'utilisateur seront perdues.
  • Nous vous recommandons vivement de mettre à jour votre application pour cibler Android 13 ou version ultérieure afin de profiter des API de la plate-forme pour demander l'autorisation. Si ce 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. Pour en savoir plus, consultez les bonnes pratiques concernant les autorisations de notification.

Facultatif : supprimez 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és par votre application) et que vous ne souhaitez pas que votre application inclue l'autorisation, vous pouvez la supprimer à l'aide du repère remove de l'outil de fusion de fichiers manifestes. N'oubliez pas que la suppression de cette autorisation empêche l'affichage de toutes les notifications, et pas seulement de celles de 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 à l'ID d'installation Firebase

Lors du premier démarrage de votre application, le SDK FCM enregistre l'instance de l'application auprès de FCM et renvoie un identifiant pour l'instance de l'application. Si vous souhaitez cibler des instances d'application individuelles, vous devez accéder à cet identifiant en étendant FirebaseMessagingService et en remplaçant onRegistered(). Il est recommandé de récupérer le dernier identifiant mis à jour, car l'identifiant peut changer après le démarrage initial.

Activer l'enregistrement via l'ID d'installation Firebase

Pour activer l'enregistrement de votre instance d'application auprès de FCM à l'aide de l'ID d'installation Firebase (FID), ajoutez l'indicateur de métadonnées suivant à votre fichier AndroidManifest.xml : 
<meta-data
    android:name="firebase_messaging_installation_id_enabled"
    android:value="true" />

Implémenter le rappel onRegistered()

Les instances d'application sont ciblées à l'aide de l'ID d'installation Firebase (FID) une fois qu'elles sont enregistrées auprès de FCM. Pour récupérer le FID lors de l'enregistrement, implémentez le rappel onRegistered(). Une fois qu'une instance d'application est enregistrée, le SDK FCM surveille automatiquement les modifications de l'ID d'installation Firebase et appelle le rappel lorsqu'une modification est détectée. Lorsque l'initialisation automatique est activée, le SDK FCM se synchronise automatiquement avec le backend FCM pour maintenir l'enregistrement à jour et appelle le rappel pour s'assurer que votre serveur d'application dispose de l'identifiant actuel. Pour éviter de perdre le FID ou d'utiliser un FID obsolète, vous devez envoyer le FID à votre serveur d'application chaque fois que ce rappel se déclenche.

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

Enregistrer manuellement lorsque l'initialisation automatique est désactivée

Si vous devez désactiver l'initialisation automatique, le SDK FCM ne se synchronisera pas automatiquement et ne déclenchera pas le rappel onRegistered() au démarrage. Nous vous recommandons vivement de réactiver l'initialisation automatique une fois les autorisations de notification accordées. Pour en savoir plus, consultez Réactiver l'initialisation automatique.

Si l'initialisation automatique doit rester désactivée, appelez FirebaseMessaging.getInstance().register() au démarrage de l'application pour déclencher l'enregistrement et l'envoi du FID via le rappel onRegistered(). Vous pouvez exécuter cet appel dans la méthode onCreate() de votre Activity principal.

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

Accéder au jeton d'enregistrement FCM (obsolète)

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 instances d'application uniques ou créer des groupes d'appareils, vous devez accéder à ce jeton en étendant FirebaseMessagingService et en remplaçant onNewToken. Étant donné que le jeton peut faire l'objet d'une rotation après le démarrage initial, nous vous recommandons vivement de récupérer le dernier jeton d'enregistrement mis à jour.

Le jeton d'enregistrement peut changer dans les cas suivants :

  • 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() :

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

Surveiller la génération de jetons

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

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

Une fois que vous avez obtenu le jeton, vous pouvez l'envoyer à votre serveur d'applications et le stocker à l'aide de la méthode de votre choix.

Vérifier la présence des services Google Play

Les applications qui s'appuient sur le SDK des services Play doivent toujours vérifier que l'appareil dispose d'un APK des services Google Play compatible avant d'accéder aux fonctionnalités des services Google Play. Pour en savoir plus, consultez Configurer les services Google Play. Nous vous recommandons 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() permet de s'assurer que si l'utilisateur revient à l'application en cours d'exécution par un autre moyen, par exemple via le bouton 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 depuis le Play Store.

Empêcher l'initialisation automatique

Lorsqu'un enregistrement FCM est généré, la bibliothèque importe l'identifiant et les données de configuration dans Firebase. Si vous préférez empêcher l'enregistrement automatique, désactivez la collecte Analytics et l'initialisation automatique de 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" />

Réactiver l'initialisation automatique

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

Kotlin

Firebase.messaging.isAutoInitEnabled = true

Java

FirebaseMessaging.getInstance().setAutoInitEnabled(true);

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

setAnalyticsCollectionEnabled(true);

Une fois définies, ces valeurs sont conservées lors des redémarrages de l'application.

Envoyer un message de notification

Pour vous assurer que votre client Android est correctement configuré, vous pouvez envoyer un message de notification de test en suivant les instructions ci-dessous :

  1. Installez et exécutez l'application sur l'appareil cible.

  2. Assurez-vous que l'application s'exécute en arrière-plan sur l'appareil.

  3. Dans la console Firebase, accédez à DevOps et engagement > Messagerie.

  4. Créez une campagne.

    • S'il s'agit de votre premier message :

      1. Sélectionnez Créer votre première campagne.

      2. Sélectionnez Messages de notification Firebase, puis Créer.

    • Si vous avez déjà créé des campagnes :

      1. Dans l'onglet Campagnes, sélectionnez Nouvelle campagne.

      2. Cliquez sur Notifications.

  5. Saisissez le texte du message. Tous les autres sont facultatifs.

  6. Sélectionnez Envoyer un message test dans le volet de droite.

  7. Dans le champ Ajouter un jeton d'enregistrement FCM, saisissez le jeton d'enregistrement que vous avez obtenu dans une section précédente de ce guide.

  8. Sélectionnez Tester.

L'appareil client ciblé, avec l'application en arrière-plan, doit recevoir la notification.

Pour en savoir plus sur la distribution des messages dans votre application, accédez au tableau de bord DevOps et engagement > Messagerie > Rapports dans la console Firebase. Ce tableau de bord enregistre le nombre de messages envoyés et ouverts sur les appareils Apple et Android, ainsi que les données sur les "impressions" (notifications vues par les utilisateurs) pour les applications Android.

Étapes suivantes

Une fois la configuration terminée, voici quelques options pour continuer à utiliser FCM pour Android :