Envoyer des messages à plusieurs appareils

Pour cibler un message sur plusieurs appareils, utilisez la messagerie thématique . Cette fonctionnalité vous permet d'envoyer un message à plusieurs appareils qui se sont inscrits à un sujet particulier.

Ce didacticiel se concentre sur l'envoi de messages thématiques à partir de votre serveur d'applications à l'aide du SDK Admin ou de l'API REST pour FCM, ainsi que sur leur réception et leur gestion dans une application Android. Nous aborderons la gestion des messages pour les applications en arrière-plan et au premier plan. Toutes les étapes pour y parvenir sont couvertes, de la configuration à la vérification.

Configurer le SDK

Cette section peut couvrir les étapes que vous avez déjà effectuées si vous avez configuré une application client Android pour FCM ou suivi les étapes pour envoyer votre premier message .

Avant que tu commences

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

  • Assurez-vous que votre projet répond à ces exigences :

    • Cible le niveau d'API 19 (KitKat) ou supérieur
    • Utilise Android 4.4 ou supérieur
    • Utilise Jetpack (AndroidX) , qui inclut le respect de ces exigences de version :
      • com.android.tools.build:gradle v7.3.0 ou version ultérieure
      • compileSdkVersion 28 ou 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 à l'aide de votre compte Google.

Si vous n'avez pas encore de 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 connecter à votre application Android. Consultez Comprendre les projets Firebase pour en savoir plus sur les projets Firebase.

Enregistrez votre application avec Firebase

Pour utiliser Firebase dans votre application Android, vous devez enregistrer votre application avec votre projet Firebase. L'enregistrement de votre application est souvent appelé « ajouter » 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 workflow de configuration.

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

  4. (Facultatif) Saisissez d'autres informations sur l'application : pseudonyme 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.

  2. Pour rendre les valeurs de votre fichier de configuration google-services.json accessibles aux SDK Firebase, vous avez besoin du plugin 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 :

      Kotlin

      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.1" apply false
}

      Groovy

      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.1' 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 plugin des services Google :

      Kotlin

      plugins {
  id("com.android.application")

  // Add the Google services Gradle plugin
  id("com.google.gms.google-services")
  // ...
}

      Groovy

      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 le Cloud Firebase Bibliothèque de messagerie pour Android. Nous vous recommandons d'utiliser la BoM Android Firebase pour contrôler la gestion 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:32.8.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.

    (Alternative) Ajouter des dépendances de la bibliothèque Firebase sans utiliser la BoM

    Si vous choisissez de ne pas utiliser la BoM Firebase, 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 fortement d'utiliser la BoM pour gérer les versions de 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:23.4.1")
    implementation("com.google.firebase:firebase-analytics:21.6.1")
}
    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 s'appuyer sur le module de bibliothèque principal (pour plus de détails, consultez la FAQ sur cette initiative ).

  2. Synchronisez votre projet Android avec les fichiers Gradle.

Abonnez l'application client à un sujet

Les applications clientes peuvent s'abonner à n'importe quel sujet existant ou créer un nouveau sujet. Lorsqu'une application client s'abonne à un nouveau nom de sujet (qui n'existe pas déjà pour votre projet Firebase), un nouveau sujet de ce nom est créé dans FCM et n'importe quel client peut ensuite s'y abonner.

Pour s'abonner à un sujet, l'application client appelle Firebase Cloud Messaging subscribeToTopic() avec le nom du sujet FCM. Cette méthode renvoie une Task , qui peut être utilisée par un écouteur d'achèvement pour déterminer si l'abonnement a réussi :

Kotlin+KTX

Firebase.messaging.subscribeToTopic("weather")
    .addOnCompleteListener { task ->
        var msg = "Subscribed"
        if (!task.isSuccessful) {
            msg = "Subscribe failed"
        }
        Log.d(TAG, msg)
        Toast.makeText(baseContext, msg, Toast.LENGTH_SHORT).show()
    }
MainActivity.kt

Java

FirebaseMessaging.getInstance().subscribeToTopic("weather")
        .addOnCompleteListener(new OnCompleteListener<Void>() {
            @Override
            public void onComplete(@NonNull Task<Void> task) {
                String msg = "Subscribed";
                if (!task.isSuccessful()) {
                    msg = "Subscribe failed";
                }
                Log.d(TAG, msg);
                Toast.makeText(MainActivity.this, msg, Toast.LENGTH_SHORT).show();
            }
        });
MainActivity.java

Pour se désabonner, l'application client appelle Firebase Cloud Messaging unsubscribeFromTopic() avec le nom du sujet.

Recevoir et gérer les messages thématiques

FCM transmet les messages thématiques de la même manière que les autres messages en aval.

Pour recevoir des messages, utilisez un service qui étend FirebaseMessagingService . Votre service doit remplacer les rappels onMessageReceived et onDeletedMessages .

La fenêtre de temps de traitement d'un message peut être inférieure à 20 secondes en fonction des retards encourus avant l'appel de onMessageReceived , y compris les retards du système d'exploitation, le temps de démarrage de l'application, le thread principal bloqué par d'autres opérations ou les appels onMessageReceived précédents prenant trop de temps. Passé ce délai, divers comportements du système d'exploitation, tels que la suppression des processus d'Android ou les limites d'exécution en arrière-plan d'Android O, peuvent interférer avec votre capacité à terminer votre travail.

onMessageReceived est fourni pour la plupart des types de messages, avec les exceptions suivantes :

  • Messages de notification envoyés lorsque votre application est en arrière-plan . Dans ce cas, la notification est envoyée dans la barre d'état système de l'appareil. Un utilisateur appuyant sur une notification ouvre le lanceur d'applications par défaut.

  • Messages avec notification et charge utile de données, lorsqu'ils sont reçus en arrière-plan . Dans ce cas, la notification est envoyée dans la barre d'état système de l'appareil et la charge utile des données est livrée dans les extras de l'intention de votre activité de lancement.

En résumé:

État de l'application Notification Données Les deux
Premier plan onMessageReceived onMessageReceived onMessageReceived
Arrière-plan Barre d'état système onMessageReceived Notification : barre d'état système
Données : en extras de l'intention.
Pour plus d'informations sur les types de messages, voir Notifications et messages de données .

Modifier le manifeste de l'application

Pour utiliser FirebaseMessagingService , vous devez ajouter les éléments suivants dans le manifeste de votre application :

<service
    android:name=".java.MyFirebaseMessagingService"
    android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>
AndroidManifest.xml

Il est également recommandé de définir des valeurs par défaut pour personnaliser l'apparence des notifications. Vous pouvez spécifier une icône par défaut personnalisée et une couleur par défaut personnalisée qui sont appliquées chaque fois que des valeurs équivalentes ne sont pas définies dans la charge utile de notification.

Ajoutez ces lignes à l'intérieur de la balise application pour définir l'icône par défaut personnalisée et la couleur personnalisée :

<!-- 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" />
AndroidManifest.xml

Android affiche l'icône personnalisée par défaut pour

  • Tous les messages de notification envoyés par le compositeur de notifications .
  • Tout message de notification qui ne définit pas explicitement l'icône dans la charge utile de notification.

Android utilise la couleur par défaut personnalisée pour

  • Tous les messages de notification envoyés par le compositeur de notifications .
  • Tout message de notification qui ne définit pas explicitement la couleur dans la charge utile de notification.

Si aucune icône personnalisée par défaut n'est définie et qu'aucune icône n'est définie dans la charge utile de notification, Android affiche l'icône de l'application rendue en blanc.

Remplacer onMessageReceived

En remplaçant la méthode FirebaseMessagingService.onMessageReceived , vous pouvez effectuer des actions basées sur l'objet RemoteMessage reçu et obtenir les données du message :

Kotlin+KTX

override fun onMessageReceived(remoteMessage: RemoteMessage) {
    // TODO(developer): Handle FCM messages here.
    // Not getting messages here? See why this may be: https://goo.gl/39bRNJ
    Log.d(TAG, "From: ${remoteMessage.from}")

    // Check if message contains a data payload.
    if (remoteMessage.data.isNotEmpty()) {
        Log.d(TAG, "Message data payload: ${remoteMessage.data}")

        // Check if data needs to be processed by long running job
        if (needsToBeScheduled()) {
            // For long-running tasks (10 seconds or more) use WorkManager.
            scheduleJob()
        } else {
            // Handle message within 10 seconds
            handleNow()
        }
    }

    // Check if message contains a notification payload.
    remoteMessage.notification?.let {
        Log.d(TAG, "Message Notification Body: ${it.body}")
    }

    // Also if you intend on generating your own notifications as a result of a received FCM
    // message, here is where that should be initiated. See sendNotification method below.
}
MyFirebaseMessagingService.kt

Java

@Override
public void onMessageReceived(RemoteMessage remoteMessage) {
    // TODO(developer): Handle FCM messages here.
    // Not getting messages here? See why this may be: https://goo.gl/39bRNJ
    Log.d(TAG, "From: " + remoteMessage.getFrom());

    // Check if message contains a data payload.
    if (remoteMessage.getData().size() > 0) {
        Log.d(TAG, "Message data payload: " + remoteMessage.getData());

        if (/* Check if data needs to be processed by long running job */ true) {
            // For long-running tasks (10 seconds or more) use WorkManager.
            scheduleJob();
        } else {
            // Handle message within 10 seconds
            handleNow();
        }

    }

    // Check if message contains a notification payload.
    if (remoteMessage.getNotification() != null) {
        Log.d(TAG, "Message Notification Body: " + remoteMessage.getNotification().getBody());
    }

    // Also if you intend on generating your own notifications as a result of a received FCM
    // message, here is where that should be initiated. See sendNotification method below.
}
MyFirebaseMessagingService.java

Remplacer onDeletedMessages

Dans certaines situations, FCM peut ne pas transmettre de message. Cela se produit lorsqu'il y a trop de messages (> 100) en attente pour votre application sur un appareil particulier au moment de sa connexion ou si l'appareil ne s'est pas connecté à FCM depuis plus d'un mois. Dans ces cas, vous pouvez recevoir un rappel vers FirebaseMessagingService.onDeletedMessages() . Lorsque l'instance d'application reçoit ce rappel, elle doit effectuer une synchronisation complète avec votre serveur d'application. Si vous n'avez pas envoyé de message à l'application sur cet appareil au cours des 4 dernières semaines, FCM n'appellera pas onDeletedMessages() .

Gérer les messages de notification dans une application en arrière-plan

Lorsque votre application est en arrière-plan, Android dirige les messages de notification vers la barre d'état système. Un utilisateur appuyant sur la notification ouvre le lanceur d'applications par défaut.

Cela inclut les messages contenant à la fois des notifications et des données utiles (ainsi que tous les messages envoyés depuis la console de notifications). Dans ces cas, la notification est envoyée dans la barre d'état système de l'appareil et la charge utile des données est livrée dans les extras de l'intention de votre activité de lancement.

Pour obtenir un aperçu de la transmission des messages à votre application, consultez le tableau de bord de reporting FCM , qui 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.

Créer des demandes d'envoi

Après avoir créé un sujet, soit en abonnant les instances d'application client au sujet côté client, soit via l' API du serveur , vous pouvez envoyer des messages au sujet. Si c'est la première fois que vous créez des requêtes d'envoi pour FCM, consultez le guide de votre environnement de serveur et de FCM pour obtenir des informations de base et de configuration importantes.

Dans votre logique d'envoi sur le backend, spécifiez le nom du sujet souhaité comme indiqué :

Noeud.js

// The topic name can be optionally prefixed with "/topics/".
const topic = 'highScores';

const message = {
  data: {
    score: '850',
    time: '2:45'
  },
  topic: topic
};

// Send a message to devices subscribed to the provided topic.
getMessaging().send(message)
  .then((response) => {
    // Response is a message ID string.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

Java

// The topic name can be optionally prefixed with "/topics/".
String topic = "highScores";

// See documentation on defining a message payload.
Message message = Message.builder()
    .putData("score", "850")
    .putData("time", "2:45")
    .setTopic(topic)
    .build();

// Send a message to the devices subscribed to the provided topic.
String response = FirebaseMessaging.getInstance().send(message);
// Response is a message ID string.
System.out.println("Successfully sent message: " + response);
FirebaseMessagingSnippets.java

Python

# The topic name can be optionally prefixed with "/topics/".
topic = 'highScores'

# See documentation on defining a message payload.
message = messaging.Message(
    data={
        'score': '850',
        'time': '2:45',
    },
    topic=topic,
)

# Send a message to the devices subscribed to the provided topic.
response = messaging.send(message)
# Response is a message ID string.
print('Successfully sent message:', response)
cloud_messaging.py

Aller

// The topic name can be optionally prefixed with "/topics/".
topic := "highScores"

// See documentation on defining a message payload.
message := &messaging.Message{
	Data: map[string]string{
		"score": "850",
		"time":  "2:45",
	},
	Topic: topic,
}

// Send a message to the devices subscribed to the provided topic.
response, err := client.Send(ctx, message)
if err != nil {
	log.Fatalln(err)
}
// Response is a message ID string.
fmt.Println("Successfully sent message:", response)
messaging.go

C#

// The topic name can be optionally prefixed with "/topics/".
var topic = "highScores";

// See documentation on defining a message payload.
var message = new Message()
{
    Data = new Dictionary<string, string>()
    {
        { "score", "850" },
        { "time", "2:45" },
    },
    Topic = topic,
};

// Send a message to the devices subscribed to the provided topic.
string response = await FirebaseMessaging.DefaultInstance.SendAsync(message);
// Response is a message ID string.
Console.WriteLine("Successfully sent message: " + response);

REPOS

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
  "message":{
    "topic" : "foo-bar",
    "notification" : {
      "body" : "This is a Firebase Cloud Messaging Topic Message!",
      "title" : "FCM Message"
      }
   }
}

Commande cURL :

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
  "message": {
    "topic" : "foo-bar",
    "notification": {
      "body": "This is a Firebase Cloud Messaging Topic Message!",
      "title": "FCM Message"
    }
  }
}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Pour envoyer un message à une combinaison de rubriques, spécifiez une condition , qui est une expression booléenne qui spécifie les rubriques cibles. Par exemple, la condition suivante enverra des messages aux appareils abonnés à TopicA et à TopicB ou TopicC :

"'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)"

FCM évalue d'abord les conditions entre parenthèses, puis évalue l'expression de gauche à droite. Dans l'expression ci-dessus, un utilisateur abonné à un seul sujet ne reçoit pas le message. De même, un utilisateur non abonné à TopicA ne reçoit pas le message. Ces combinaisons le reçoivent :

  • TopicA et TopicB
  • TopicA et TopicC

Vous pouvez inclure jusqu'à cinq sujets dans votre expression conditionnelle.

Pour envoyer à une condition :

Noeud.js

// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
const condition = '\'stock-GOOG\' in topics || \'industry-tech\' in topics';

// See documentation on defining a message payload.
const message = {
  notification: {
    title: '$FooCorp up 1.43% on the day',
    body: '$FooCorp gained 11.80 points to close at 835.67, up 1.43% on the day.'
  },
  condition: condition
};

// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
getMessaging().send(message)
  .then((response) => {
    // Response is a message ID string.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

Java

// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
String condition = "'stock-GOOG' in topics || 'industry-tech' in topics";

// See documentation on defining a message payload.
Message message = Message.builder()
    .setNotification(Notification.builder()
        .setTitle("$GOOG up 1.43% on the day")
        .setBody("$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.")
        .build())
    .setCondition(condition)
    .build();

// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
String response = FirebaseMessaging.getInstance().send(message);
// Response is a message ID string.
System.out.println("Successfully sent message: " + response);
FirebaseMessagingSnippets.java

Python

# Define a condition which will send to devices which are subscribed
# to either the Google stock or the tech industry topics.
condition = "'stock-GOOG' in topics || 'industry-tech' in topics"

# See documentation on defining a message payload.
message = messaging.Message(
    notification=messaging.Notification(
        title='$GOOG up 1.43% on the day',
        body='$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.',
    ),
    condition=condition,
)

# Send a message to devices subscribed to the combination of topics
# specified by the provided condition.
response = messaging.send(message)
# Response is a message ID string.
print('Successfully sent message:', response)
cloud_messaging.py

Aller

// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
condition := "'stock-GOOG' in topics || 'industry-tech' in topics"

// See documentation on defining a message payload.
message := &messaging.Message{
	Data: map[string]string{
		"score": "850",
		"time":  "2:45",
	},
	Condition: condition,
}

// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
response, err := client.Send(ctx, message)
if err != nil {
	log.Fatalln(err)
}
// Response is a message ID string.
fmt.Println("Successfully sent message:", response)
messaging.go

C#

// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
var condition = "'stock-GOOG' in topics || 'industry-tech' in topics";

// See documentation on defining a message payload.
var message = new Message()
{
    Notification = new Notification()
    {
        Title = "$GOOG up 1.43% on the day",
        Body = "$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.",
    },
    Condition = condition,
};

// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
string response = await FirebaseMessaging.DefaultInstance.SendAsync(message);
// Response is a message ID string.
Console.WriteLine("Successfully sent message: " + response);

REPOS

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
   "message":{
    "condition": "'dogs' in topics || 'cats' in topics",
    "notification" : {
      "body" : "This is a Firebase Cloud Messaging Topic Message!",
      "title" : "FCM Message",
    }
  }
}

Commande cURL :

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
  "notification": {
    "title": "FCM Message",
    "body": "This is a Firebase Cloud Messaging Topic Message!",
  },
  "condition": "'dogs' in topics || 'cats' in topics"
}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Prochaines étapes