Personnaliser un message sur plusieurs plates-formes

L'Firebase Admin SDK et l'API HTTP FCM v1 vous permettent de définir tous les champs disponibles dans l'objet message pour vos requêtes de message. Par exemple :

  • un ensemble commun de champs à interpréter par toutes les instances d'application qui reçoivent le message.
  • des ensembles de champs spécifiques à la plate-forme, tels que AndroidConfig et WebpushConfig, interprétés uniquement par les instances d'application s'exécutant sur la plate-forme spécifiée.

Les blocs spécifiques à la plate-forme vous permettent de personnaliser les messages pour différentes plates-formes afin de vous assurer qu'ils sont traités correctement lorsqu'ils sont reçus. Le backend FCM prendra en compte tous les paramètres spécifiés et personnalisera le message pour chaque plate-forme.

Quand utiliser les champs communs

Utilisez les champs communs lorsque vous :

  • Envoyer des champs vers n'importe quelle plate-forme
  • Envoyer des messages à des sujets

Toutes les instances d'application, quelle que soit la plate-forme, peuvent interpréter les champs communs suivants :

Quand utiliser des champs spécifiques à une plate-forme

Utilisez les champs spécifiques à la plate-forme lorsque vous souhaitez :

  • Envoyer des champs uniquement à certaines plates-formes
  • Envoyer des champs spécifiques à la plate-forme en plus des champs communs

Chaque fois que vous souhaitez n'envoyer des valeurs qu'à certaines plates-formes, utilisez des champs spécifiques à ces plates-formes. Par exemple, pour envoyer une notification uniquement aux plates-formes Apple et Web, mais pas à Android, vous devez utiliser deux ensembles de champs distincts, un pour Apple et un pour le Web.

Lorsque vous envoyez des messages avec des options de distribution spécifiques, utilisez les champs propres à la plate-forme pour les définir. Si vous le souhaitez, vous pouvez spécifier différentes valeurs par plate-forme. Toutefois, même si vous souhaitez définir une valeur pratiquement identique sur toutes les plates-formes, vous devez utiliser des champs spécifiques à chaque plate-forme. En effet, chaque plate-forme peut interpréter la valeur légèrement différemment. Par exemple, le délai avant expiration est défini sur Android comme une heure d'expiration en secondes, tandis que sur Apple, il est défini comme une date d'expiration.

Message de notification avec des options de diffusion spécifiques à la plate-forme

La requête d'envoi de l'API HTTP v1 suivante envoie un titre et un contenu de notification communs à toutes les plates-formes, mais envoie également des remplacements spécifiques à certaines plates-formes. Plus précisément, la demande :

  • définit une longue durée de vie pour les plates-formes Android et Web, tout en définissant la priorité du message APNs (plates-formes Apple) sur un paramètre faible.
  • définit les clés appropriées pour définir le résultat d'un appui de l'utilisateur sur la notification sur Android et Apple : click_action et category, respectivement.
{
  "message":{
     "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
     "notification":{
       "title":"Match update",
       "body":"Arsenal goal in added time, score is now 3-0"
     },
     "android":{
       "ttl":"86400s",
       "notification"{
         "click_action":"OPEN_ACTIVITY_1"
       }
     },
     "apns": {
       "headers": {
         "apns-priority": "5",
       },
       "payload": {
         "aps": {
           "category": "NEW_MESSAGE_CATEGORY"
         }
       }
     },
     "webpush":{
       "headers":{
         "TTL":"86400"
       }
     }
   }
 }

Pour en savoir plus, consultez la page de référence HTTP v1. Vous y trouverez plus d'informations sur les clés disponibles dans les blocs spécifiques à la plate-forme du corps du message. Pour en savoir plus sur la création de requêtes d'envoi contenant le corps du message, consultez Envoyer un message à l'aide de l'API FCM HTTP/1.

Message de notification avec options de couleur et d'icône

Dans l'exemple suivant, la requête d'envoi envoie un titre et un contenu de notification communs à toutes les plates-formes, mais elle envoie également des remplacements spécifiques à la plate-forme aux appareils Android.

Pour Android, la requête définit une icône et une couleur spéciales à afficher sur les appareils Android. Comme indiqué dans la référence pour AndroidNotification, la couleur est spécifiée au format #rrggbb et l'image doit être une ressource d'icône drawable locale à l'application Android.

Voici un exemple de l'effet visuel sur l'appareil d'un utilisateur :

Dessin simple de deux appareils, dont l'un affiche une icône et une couleur personnalisées

Node.js

const topicName = 'industry-tech';

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.'
  },
  android: {
    notification: {
      icon: 'stock_ticker_update',
      color: '#7e55c3'
    }
  },
  topic: topicName,
};

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

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())
    .setAndroidConfig(AndroidConfig.builder()
        .setTtl(3600 * 1000)
        .setNotification(AndroidNotification.builder()
            .setIcon("stock_ticker_update")
            .setColor("#f45342")
            .build())
        .build())
    .setApnsConfig(ApnsConfig.builder()
        .setAps(Aps.builder()
            .setBadge(42)
            .build())
        .build())
    .setTopic("industry-tech")
    .build();
FirebaseMessagingSnippets.java

Python

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.',
    ),
    android=messaging.AndroidConfig(
        ttl=datetime.timedelta(seconds=3600),
        priority='normal',
        notification=messaging.AndroidNotification(
            icon='stock_ticker_update',
            color='#f45342'
        ),
    ),
    apns=messaging.APNSConfig(
        payload=messaging.APNSPayload(
            aps=messaging.Aps(badge=42),
        ),
    ),
    topic='industry-tech',
)
cloud_messaging.py

Go

oneHour := time.Duration(1) * time.Hour
badge := 42
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.",
	},
	Android: &messaging.AndroidConfig{
		TTL: &oneHour,
		Notification: &messaging.AndroidNotification{
			Icon:  "stock_ticker_update",
			Color: "#f45342",
		},
	},
	APNS: &messaging.APNSConfig{
		Payload: &messaging.APNSPayload{
			Aps: &messaging.Aps{
				Badge: &badge,
			},
		},
	},
	Topic: "industry-tech",
}
messaging.go

C#

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.",
    },
    Android = new AndroidConfig()
    {
        TimeToLive = TimeSpan.FromHours(1),
        Notification = new AndroidNotification()
        {
            Icon = "stock_ticker_update",
            Color = "#f45342",
        },
    },
    Apns = new ApnsConfig()
    {
        Aps = new Aps()
        {
            Badge = 42,
        },
    },
    Topic = "industry-tech",
};
FirebaseMessagingSnippets.cs

REST

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":"industry-tech",
     "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."
     },
     "android":{
       "notification":{
         "icon":"stock_ticker_update",
         "color":"#7e55c3"
       }
     }
   }
 }

Pour en savoir plus, consultez la page de référence HTTP v1. Vous y trouverez plus d'informations sur les clés disponibles dans les blocs spécifiques à la plate-forme dans le corps du message.

Message de notification avec une image personnalisée

La requête d'envoi suivante envoie un titre de notification commun à toutes les plates-formes, mais elle envoie également une image. Voici un exemple de l'effet visuel sur l'appareil d'un utilisateur :

Dessin simple d'une image dans une notification d'affichage

Node.js

const topicName = 'industry-tech';

const message = {
  notification: {
    title: 'Sparky says hello!'
  },
  android: {
    notification: {
      imageUrl: 'https://foo.bar.pizza-monster.png'
    }
  },
  apns: {
    payload: {
      aps: {
        'mutable-content': 1
      }
    },
    fcm_options: {
      image: 'https://foo.bar.pizza-monster.png'
    }
  },
  webpush: {
    headers: {
      image: 'https://foo.bar.pizza-monster.png'
    }
  },
  topic: topicName,
};

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

REST

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":"industry-tech",
     "notification":{
       "title":"Sparky says hello!",
     },
     "android":{
       "notification":{
         "image":"https://foo.bar/pizza-monster.png"
       }
     },
     "apns":{
       "payload":{
         "aps":{
           "mutable-content":1
         }
       },
       "fcm_options": {
           "image":"https://foo.bar/pizza-monster.png"
       }
     },
     "webpush":{
       "headers":{
         "image":"https://foo.bar/pizza-monster.png"
       }
     }
   }
 }

Pour en savoir plus, consultez la page de référence HTTP v1. Vous y trouverez plus d'informations sur les clés disponibles dans les blocs spécifiques à la plate-forme dans le corps du message.

Message de notification avec une action de clic associée

La requête d'envoi suivante envoie un titre de notification commun à toutes les plates-formes, mais elle envoie également une action que l'application doit effectuer en réponse à l'interaction de l'utilisateur avec la notification. Voici un exemple de l'effet visuel sur l'appareil d'un utilisateur :

Dessin simple d'un utilisateur appuyant sur un écran pour ouvrir une page Web

Node.js

const topicName = 'industry-tech';

const message = {
  notification: {
    title: 'Breaking News....'
  },
  android: {
    notification: {
      clickAction: 'news_intent'
    }
  },
  apns: {
    payload: {
      aps: {
        'category': 'INVITE_CATEGORY'
      }
    }
  },
  webpush: {
    fcmOptions: {
      link: 'breakingnews.html'
    }
  },
  topic: topicName,
};

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

REST

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