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

Keep in mind:

  • Le immagini per le notifiche sono limitate a 1 MB e sono altrimenti limitate dal supporto integrato per le immagini 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 fornita nel payload FCM prima di visualizzare la notifica all'utente finale. Per un esempio di codice, consulta Configurare l'estensione del servizio di notifica.
  • Le immagini caricate utilizzando il compositore di notifiche hanno una dimensione massima di 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 ricevente di gestire l'immagine fornita 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 di 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 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