Personalizzare un messaggio su più piattaforme

L'Firebase Admin SDK e l'API HTTP FCM v1 consentono alle tue richieste di messaggi di impostare tutti i campi disponibili nell'oggetto message. È incluso quanto segue:

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

I blocchi specifici per piattaforma ti offrono la flessibilità di personalizzare i messaggi per diverse piattaforme per garantire 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:

  • Invia i campi a qualsiasi piattaforma
  • Invia 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:

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

Ogni volta che vuoi inviare valori solo a piattaforme specifiche, utilizza i 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 pubblicazione specifiche, utilizza i campi specifici della piattaforma per impostarle. Se vuoi, puoi specificare valori diversi per ogni piattaforma. Tuttavia, anche se vuoi impostare essenzialmente lo stesso valore su più piattaforme, devi utilizzare i campi specifici della piattaforma. Questo perché ogni piattaforma potrebbe interpretare il valore in modo leggermente diverso. Ad esempio, la durata viene impostata su Android come data di scadenza in secondi, mentre su Apple viene impostata come data di scadenza.

Messaggio di notifica con opzioni di invio specifiche per la piattaforma

La seguente richiesta di invio dell'API HTTP v1 invia un titolo e un contenuto di notifica comuni a tutte le piattaforme, ma invia anche alcuni override specifici per la piattaforma. In particolare, 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 di un tocco dell'utente sulla notifica su Android e Apple, rispettivamente click_action e category.
{
  "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 di 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 Invia un messaggio utilizzando l'API HTTP v1 di FCM.

Messaggio di notifica con opzioni di colore e icona

Nell'esempio seguente, la richiesta di invio invia un titolo e un contenuto 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 drawable 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")
            .setTitle("$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();

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',
)

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

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

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 maggiori dettagli sulle chiavi disponibili nei blocchi specifici della piattaforma nel corpo del messaggio.

Messaggio di notifica con un'immagine personalizzata

Keep in mind:

  • Le immagini per le notifiche sono limitate a 1 MB e sono soggette al supporto delle immagini integrato di Android.
  • Per poter ricevere e gestire le immagini delle notifiche in un'app Apple, devi aggiungere un'estensione del servizio di notifica. L'estensione del servizio di notifica consente alla tua app di gestire l'immagine pubblicata nel payload FCM prima di mostrare la notifica all'utente finale. Per un esempio di codice, consulta Configura l'estensione del servizio di notifica.
  • Le immagini caricate utilizzando Compositore di notifiche sono limitate a 300 kB.
  • Le immagini archiviate o pubblicate da Cloud Storage sono soggette ai limiti di quota standard.

Nella richiesta di invio della notifica, imposta le seguenti opzioni per consentire al client di ricezione di gestire l'immagine inviata nel payload:

  • Per Android, imposta la seguente opzione AndroidConfig:
    • notification.image contenente l'URL dell'immagine
  • Per iOS, imposta le seguenti opzioni ApnsConfig:
    • fcm_options.image contenente l'URL dell'immagine. Apple richiede che l'URL dell'immagine includa un'estensione del file valida per identificare correttamente il tipo di risorsa.
    • headers({ "mutable-content": 1})

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 sul 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 maggiori 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 invia 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