Personalizar uma mensagem entre plataformas

O Firebase Admin SDK e a API HTTP v1 do FCM permitem que as solicitações de mensagens definam todos os campos disponíveis no objeto message. Isso inclui:

  • Um conjunto comum de campos a serem interpretados por todas as instâncias do app que recebem a mensagem.
  • Conjuntos de campos específicos da plataforma, como AndroidConfig e WebpushConfig, interpretados apenas pelas instâncias do app em execução na plataforma especificada.

Os blocos específicos da plataforma oferecem flexibilidade para personalizar mensagens em plataformas diferentes, garantindo, assim, que elas sejam gerenciadas corretamente quando recebidas. O back-end do FCM considerará todos os parâmetros especificados e personalizará a mensagem para cada plataforma.

Quando usar campos comuns

Use campos comuns ao:

  • Enviar campos para qualquer plataforma
  • Enviar mensagens a tópicos

Todas as instâncias do app, independentemente da plataforma, podem interpretar os seguintes campos comuns:

Quando usar campos específicos da plataforma

Use campos específicos da plataforma quando quiser:

  • enviar campos apenas para plataformas específicas;
  • enviar campos específicos da plataforma, além dos campos comuns.

Sempre que você quiser enviar valores apenas para plataformas específicas, use campos específicos da plataforma. Por exemplo, para enviar uma notificação apenas para as plataformas Apple e Web, mas não para o Android, use dois conjuntos de campos separados, um para a Apple e outro para a Web.

Ao enviar mensagens com opções de entrega específicas, use os campos específicos da plataforma para configurá-las. É possível especificar valores diferentes por plataforma, se você quiser. No entanto, mesmo quando você quiser definir essencialmente o mesmo valor em todas as plataformas, é necessário usar campos específicos da plataforma. Isso ocorre porque o valor pode ser interpretado de maneira ligeiramente diferente dependendo da plataforma. Por exemplo, no Android, a vida útil é definida como um prazo de validade em segundos, enquanto que, na Apple, é definida como uma data de validade.

Mensagem de notificação com opções de entrega específicas da plataforma

A solicitação de envio API HTTP v1 a seguir envia o título e o conteúdo de uma notificação comum para todas as plataformas, mas também envia algumas modificações específicas da plataforma. Especificamente, a solicitação:

  • define uma vida útil longa para as plataformas Android e Web, ao mesmo tempo que define a prioridade das mensagens dos APNs (plataformas Apple) com uma configuração baixa;
  • indica as chaves adequadas para definir o resultado de um toque do usuário na notificação no Android e na Apple: click_action ecategory, respectivamente.
{
  "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"
       }
     }
   }
 }

Para saber mais, consulte a página de referência do HTTP v1 para mais detalhes sobre as chaves disponíveis em blocos específicos da plataforma no corpo da mensagem. Para mais informações sobre como criar solicitações de envio que contenham o corpo da mensagem, consulte Enviar uma mensagem usando a API HTTP v1 do FCM.

Mensagem de notificação com opções de cor e ícone

No exemplo a seguir, a solicitação de envio envia um título e conteúdo de notificação comuns para todas as plataformas, mas também envia algumas substituições específicas da plataforma para dispositivos Android.

Para Android, a solicitação define uma cor e um ícone especiais para exibir nos dispositivos. Conforme observado na AndroidNotification, a cor é especificada no formato #rrggbb, e a imagem precisa ser um recurso de ícone drawable local para o app Android.

Este é um exemplo do efeito visual no dispositivo de um usuário:

Desenho simples de dois dispositivos, e um deles exibindo um ícone e uma cor personalizados

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

Para saber mais, consulte a página de referência HTTP v1 para mais detalhes sobre as chaves disponíveis em blocos específicos da plataforma no corpo da mensagem.

Mensagem de notificação com uma imagem personalizada

Lembre-se:

  • Há um limite de 1 MB no tamanho das imagens de notificações, as maiores são restringidas de acordo com as imagens aceitas nativamente pelo Android.
  • Para receber e gerenciar imagens de notificações em um aplicativo da Apple, adicione uma extensão de serviço de notificação. Com essa extensão, é possível gerenciar pelo seu app a imagem enviada no payload do FCM antes de exibir a notificação para o usuário final. Consulte Configurar a extensão do serviço de notificação para ver um exemplo de código.
  • O limite de tamanho das imagens enviadas por meio do Editor do Notificações é de 300 KB.
  • As imagens armazenadas ou exibidas do Cloud Storage estão sujeitas aos limites de cota padrão.

Na sua solicitação de envio de notificação, defina as seguintes opções para permitir que o cliente que receber a mensagem gerencie a imagem enviada no payload:

  • Para Android, defina a seguinte opção AndroidConfig:
    • notification.image contendo o URL da imagem
  • Para iOS, defina as seguintes opções de ApnsConfig:
    • fcm_options.image contendo o URL da imagem. A Apple exige que o URL da imagem inclua uma extensão de arquivo válida para identificar corretamente o tipo de recurso.
    • headers({ "mutable-content": 1})

A solicitação de envio a seguir envia um título de notificação comum para todas as plataformas, mas também envia uma imagem. Este é um exemplo do efeito visual no dispositivo de um usuário:

Desenho simples de uma imagem em uma notificação de exibição

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

Para saber mais, consulte a página de referência HTTP v1 para mais detalhes sobre as chaves disponíveis em blocos específicos da plataforma no corpo da mensagem.

Mensagem de notificação com uma ação de clique associada

A solicitação de envio a seguir envia um título de notificação comum para todas as plataformas, mas também envia uma ação para o aplicativo realizar em resposta ao usuário que interage com a notificação. Este é um exemplo do efeito visual no dispositivo de um usuário:

Desenho simples de um usuário tocando em uma notificação e abrindo uma página da 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