Personalizzare un messaggio su più piattaforme

L'Firebase Admin SDK e l'API HTTP FCM v1 consentono alle richieste di messaggi di impostare tutti i campi disponibili nell'oggetto message. Ciò include:

  • un insieme comune di campi da interpretare da tutte le istanze dell'app che ricevono il messaggio.
  • set di campi specifici della piattaforma, ad esempio AndroidConfig e WebpushConfig, interpretati solo dalle istanze dell'app in esecuzione sulla piattaforma specificata.

I blocchi specifici della piattaforma ti offrono la flessibilità di personalizzare i messaggi per diverse piattaforme per assicurarti che vengano gestiti correttamente quando vengono ricevuti. Il backend FCM prenderà in considerazione tutti i parametri specificati e personalizzerà il messaggio per ogni piattaforma.

Quando utilizzare i campi comuni

Utilizza i campi comuni quando:

  • Inviare campi a qualsiasi piattaforma
  • Inviare messaggi agli argomenti

Tutte le istanze dell'app, indipendentemente dalla piattaforma, possono interpretare i seguenti campi comuni:

Quando utilizzare i campi specifici della piattaforma

Utilizza i campi specifici della piattaforma quando vuoi:

  • Inviare i campi solo a piattaforme specifiche
  • Invia campi specifici della piattaforma oltre a quelli comuni

Quando vuoi inviare valori solo a piattaforme specifiche, utilizza campi specifici della piattaforma. Ad esempio, per inviare una notifica solo alle piattaforme Apple e web, ma non ad Android, devi utilizzare due insiemi di campi separati, uno per Apple e uno per il web.

Quando invii messaggi con opzioni di consegna specifiche, utilizza i campi specifici della piattaforma per impostarli. Se vuoi, puoi specificare valori diversi per piattaforma. Tuttavia, anche quando vuoi impostare essenzialmente lo stesso valore su tutte le piattaforme, devi utilizzare campi specifici per la piattaforma. Questo perché ogni piattaforma potrebbe interpretare il valore in modo leggermente diverso. Ad esempio, il time to live è impostato su Android come tempo di scadenza in secondi, mentre su Apple è impostato come data di scadenza.

Messaggio di notifica con opzioni di recapito specifiche della piattaforma

La seguente richiesta di invio dell'API HTTP v1 invia un titolo e un contenuto di notifica comuni a tutte le piattaforme, ma anche alcuni override specifici della piattaforma. Nello specifico, la richiesta:

  • imposta una durata elevata per le piattaforme Android e web, mentre imposta la priorità dei messaggi APN (piattaforme Apple) su un valore basso
  • imposta le chiavi appropriate per definire il risultato del tocco di un utente sulla notifica su Android e Apple, ovvero click_action e category, rispettivamente.
{
  "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"
       }
     }
   }
 }

Per saperne di più, consulta la pagina Riferimento HTTP v1 per maggiori dettagli sulle chiavi disponibili nei blocchi specifici della piattaforma nel corpo del messaggio. Per saperne di più sulla creazione di richieste di invio che contengono il corpo del messaggio, consulta Inviare un messaggio utilizzando l'API FCM HTTP v1.

Messaggio di notifica con opzioni di colore e icona

Nell'esempio seguente, la richiesta di invio invia un titolo e contenuti di notifica comuni a tutte le piattaforme, ma invia anche alcuni override specifici della piattaforma ai dispositivi Android.

Per Android, la richiesta imposta un'icona e un colore speciali da visualizzare sui dispositivi Android. Come indicato nel riferimento per AndroidNotification, il colore è specificato nel formato #rrggbb e l'immagine deve essere una risorsa icona disegnabile locale per l'app per Android.

Ecco un esempio dell'effetto visivo sul dispositivo di un utente:

Disegno semplice di due dispositivi, uno dei quali mostra un'icona e un colore personalizzati

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

Vai

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

Per saperne di più, consulta la pagina di riferimento HTTP v1 per ulteriori dettagli sulle chiavi disponibili nei blocchi specifici della piattaforma nel corpo del messaggio.

Messaggio di notifica con un'immagine personalizzata

La seguente richiesta di invio invia un titolo di notifica comune a tutte le piattaforme, ma invia anche un'immagine. Ecco un esempio dell'effetto visivo sul dispositivo di un utente:

Semplice disegno di un'immagine in una notifica display

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

Per saperne di più, consulta la pagina di riferimento HTTP v1 per ulteriori dettagli sulle chiavi disponibili nei blocchi specifici della piattaforma nel corpo del messaggio.

Messaggio di notifica con un'azione di clic associata

La seguente richiesta di invio invia un titolo di notifica comune a tutte le piattaforme, ma anche un'azione che l'app deve eseguire in risposta all'interazione dell'utente con la notifica. Ecco un esempio dell'effetto visivo sul dispositivo di un utente:

Semplice disegno di un utente che tocca per aprire una pagina 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