Envoyer un message de test à une application en arrière-plan

Pour commencer à utiliser FCM, créez le cas d'utilisation le plus simple: envoyer un message de notification de test à partir du compilateur de notifications vers un appareil de développement lorsque l'application est en arrière-plan sur l'appareil. Cette page liste toutes les étapes à suivre, de la configuration à la validation. Elle peut couvrir des étapes que vous avez déjà effectuées si vous avez configuré une application cliente Android pour FCM.

Configurez le SDK

Cette section décrit les tâches que vous avez peut-être effectuées si vous avez déjà activé d'autres fonctionnalités Firebase pour votre application.

Avant de commencer

  • Installez ou mettez à jour Android Studio vers la dernière version.

  • Assurez-vous que votre projet répond à ces exigences (notez que certains produits peuvent avoir des exigences plus strictes):

    • Cible le niveau d'API 21 (Lollipop) ou version ultérieure
    • Utilise Android 5.0 ou version ultérieure
    • Utilise Jetpack (AndroidX), ce qui implique de respecter les exigences de version suivantes :
      • com.android.tools.build:gradle v7.3.0 ou version ultérieure
      • compileSdkVersion 28 ou version ultérieure
  • Configurez un appareil physique ou utilisez un émulateur pour exécuter votre application.
    Notez que les SDK Firebase dépendant des services Google Play nécessitent que les services Google Play soient installés sur l'appareil ou l'émulateur.

  • Connectez-vous à Firebase avec votre compte Google.

Si vous ne disposez pas encore d'un projet Android et que vous souhaitez simplement essayer un produit Firebase, vous pouvez télécharger l'un de nos exemples de démarrage rapide.

Créer un projet Firebase

Avant de pouvoir ajouter Firebase à votre application Android, vous devez créer un projet Firebase pour vous y connecter. Pour en savoir plus sur les projets Firebase, consultez la page Comprendre les projets Firebase.

  1. Dans la console Firebase, cliquez sur Ajouter un projet.

    • Pour ajouter des ressources Firebase à un projet Google Cloud existant, saisissez son nom ou sélectionnez-le dans le menu déroulant.

    • Pour créer un projet, saisissez le nom souhaité. Vous pouvez également modifier l'ID du projet affiché sous le nom du projet.

  2. Si vous y êtes invité, lisez et acceptez les Conditions d'utilisation de Firebase.

  3. Cliquez sur Continuer.

  4. (Facultatif) Configurez Google Analytics pour votre projet, ce qui vous permet de profiter d'une expérience optimale avec l'un des produits Firebase suivants:

    Sélectionnez un compte Google Analytics existant ou créez-en un.

    Si vous créez un compte, sélectionnez votre emplacement de création de rapports Analytics, puis acceptez les paramètres de partage des données et les conditions Google Analytics pour votre projet.

  5. Cliquez sur Créer un projet (ou sur Ajouter Firebase si vous utilisez un projet Google Cloud existant).

Firebase provisionne automatiquement des ressources pour votre projet Firebase. Une fois le processus terminé, vous êtes redirigé vers la page de présentation de votre projet Firebase dans la console Firebase.

Enregistrer votre application auprès de Firebase

Pour utiliser Firebase dans votre application Android, vous devez enregistrer votre application auprès de votre projet Firebase. L'enregistrement de votre application est souvent appelé "ajout" de votre application à votre projet.

  1. Accédez à la console Firebase.

  2. Au centre de la page de présentation du projet, cliquez sur l'icône Android () ou sur Ajouter une application pour lancer le processus de configuration.

  3. Saisissez le nom du package de votre application dans le champ Nom du package Android.

    • Un nom de package identifie de manière unique votre application sur l'appareil et dans le Google Play Store.

    • Un nom de package est souvent appelé ID d'application.

    • Recherchez le nom du package de votre application dans le fichier Gradle de votre module (au niveau de l'application), généralement app/build.gradle (exemple de nom de package : com.yourcompany.yourproject).

    • Notez que la valeur du nom du package est sensible à la casse et qu'elle ne peut pas être modifiée pour cette application Android pour Firebase une fois qu'elle est enregistrée dans votre projet Firebase.

  4. (Facultatif) Saisissez d'autres informations sur l'application : Pseudo de l'application et Certificat de signature de débogage SHA-1.

  5. Cliquez sur Enregistrer l'application.

Ajouter un fichier de configuration Firebase

  1. Téléchargez, puis ajoutez le fichier de configuration Firebase Android (google-services.json) à votre application:

    1. Cliquez sur Télécharger google-services.json pour obtenir votre fichier de configuration Firebase Android.

    2. Déplacez votre fichier de configuration dans le répertoire racine du module (au niveau de l'application) de votre application.

    • Le fichier de configuration Firebase contient des identifiants uniques, mais pas secrets, pour votre projet. Pour en savoir plus sur ce fichier de configuration, consultez Comprendre les projets Firebase.

    • Vous pouvez télécharger à nouveau votre fichier de configuration Firebase à tout moment.

    • Veillez à ne pas inclure de caractères supplémentaires dans le nom du fichier de configuration, par exemple (2).

  2. Pour rendre les valeurs de votre fichier de configuration google-services.json accessibles aux SDK Firebase, vous devez disposer du plug-in Gradle des services Google (google-services).

    1. Dans votre fichier Gradle au niveau racine (au niveau du projet) (<project>/build.gradle.kts ou <project>/build.gradle), ajoutez le plug-in des services Google en tant que dépendance:

      plugins {
        id("com.android.application") version "7.3.0" apply false
        // ...
      
        // Add the dependency for the Google services Gradle plugin
        id("com.google.gms.google-services") version "4.4.2" apply false
      }
      plugins {
        id 'com.android.application' version '7.3.0' apply false
        // ...
      
        // Add the dependency for the Google services Gradle plugin
        id 'com.google.gms.google-services' version '4.4.2' apply false
      }
    2. Dans le fichier Gradle de votre module (au niveau de l'application) (généralement <project>/<app-module>/build.gradle.kts ou <project>/<app-module>/build.gradle), ajoutez le plug-in des services Google:

      plugins {
        id("com.android.application")
      
        // Add the Google services Gradle plugin
        id("com.google.gms.google-services")
        // ...
      }
      plugins {
        id 'com.android.application'
      
        // Add the Google services Gradle plugin
        id 'com.google.gms.google-services'
        // ...
      }

Ajouter des SDK Firebase à votre application

  1. Dans le fichier Gradle de votre module (au niveau de l'application) (généralement <project>/<app-module>/build.gradle.kts ou <project>/<app-module>/build.gradle), ajoutez la dépendance pour la bibliothèque Firebase Cloud Messaging pour Android. Nous vous recommandons d'utiliser Firebase Android BoM pour contrôler le contrôle des versions de la bibliothèque.

    Pour une expérience optimale avec Firebase Cloud Messaging, nous vous recommandons d'activer Google Analytics dans votre projet Firebase et d'ajouter le SDK Firebase pour Google Analytics à votre application.

    dependencies {
        // Import the BoM for the Firebase platform
        implementation(platform("com.google.firebase:firebase-bom:33.9.0"))
    
        // Add the dependencies for the Firebase Cloud Messaging and Analytics libraries
        // When using the BoM, you don't specify versions in Firebase library dependencies
        implementation("com.google.firebase:firebase-messaging")
        implementation("com.google.firebase:firebase-analytics")
    }

    En utilisant Firebase Android BoM, votre application utilisera toujours des versions compatibles des bibliothèques Firebase Android.

    Si vous choisissez de ne pas utiliser Firebase BoM, vous devez spécifier chaque version de la bibliothèque Firebase dans sa ligne de dépendance.

    Notez que si vous utilisez plusieurs bibliothèques Firebase dans votre application, nous vous recommandons vivement d'utiliser BoM pour gérer les versions de la bibliothèque, ce qui garantit que toutes les versions sont compatibles.

    dependencies {
        // Add the dependencies for the Firebase Cloud Messaging and Analytics libraries
        // When NOT using the BoM, you must specify versions in Firebase library dependencies
        implementation("com.google.firebase:firebase-messaging:24.1.0")
        implementation("com.google.firebase:firebase-analytics:22.2.0")
    }
    Vous recherchez un module de bibliothèque spécifique à Kotlin ? À partir d'octobre 2023 (Firebase BoM 32.5.0), les développeurs Kotlin et Java peuvent dépendre du module de bibliothèque principal (pour en savoir plus, consultez les questions fréquentes sur cette initiative).

  2. Synchronisez votre projet Android avec les fichiers Gradle.

    Les builds Gradle qui utilisent le plug-in Android Gradle (AGP) 4.2 ou version antérieure doivent activer la compatibilité avec Java 8. Sinon, ces projets Android rencontrent un échec de compilation lors de l'ajout d'un SDK Firebase.

    Pour résoudre ce problème de compilation, vous pouvez suivre l'une des deux options suivantes:

    • Ajoutez l'compileOptions listée dans le message d'erreur à votre fichier build.gradle.kts ou build.gradle au niveau de l'application.
    • Augmentez la version minSdk de votre projet Android à 26 ou version ultérieure.

    Pour en savoir plus sur cet échec de compilation, consultez ces questions fréquentes.

Accéder au jeton d'enregistrement

Pour envoyer un message à un appareil spécifique, vous devez connaître le jeton d'enregistrement de cet appareil. Comme vous devrez saisir le jeton dans un champ de la console Notifications pour terminer ce tutoriel, assurez-vous de le copier ou de le stocker de manière sécurisée après l'avoir récupéré.

Au 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 individuels ou créer des groupes d'appareils, vous devez accéder à ce jeton en étendant FirebaseMessagingService et en remplaçant onNewToken.

Cette section explique comment récupérer le jeton et comment surveiller les modifications apportées au jeton. Étant donné que le jeton peut être remplacé 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():

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()
})
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 nouveau jeton est généré.

/**
 * 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)
}
/**
 * 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'application et le stocker à l'aide de la méthode de votre choix.

Envoyer un message de notification test

  1. Installez et exécutez l'application sur l'appareil cible. Sur les appareils Apple, vous devez accepter la demande d'autorisation pour recevoir des notifications à distance.

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

  3. Dans la console Firebase, ouvrez la page Messaging (Messagerie).

  4. S'il s'agit de votre premier message, sélectionnez Créer votre première campagne.

    1. Sélectionnez Messages de notification Firebase, puis Créer.
  5. Sinon, dans l'onglet Campagnes, sélectionnez Nouvelle campagne, puis Notifications.

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

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

  8. 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.

  9. Sélectionnez Tester.

Une fois que vous avez sélectionné Test, 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, consultez le tableau de bord de reporting FCM, qui enregistre le nombre de messages envoyés et ouverts sur des appareils Apple et Android, ainsi que les données sur les "impressions" (notifications vues par les utilisateurs) pour les applications Android.

Étapes suivantes

Envoyer des messages aux applications au premier plan

Une fois que vous avez envoyé des messages de notification lorsque votre application est en arrière-plan, consultez la section Recevoir des messages dans une application Android pour commencer à envoyer des messages aux applications au premier plan.

Aller au-delà des messages de notification

Pour aller au-delà des messages de notification et ajouter d'autres comportements plus avancés à votre application, consultez les articles suivants: