Enviar uma mensagem de teste a um app em segundo plano

Para dar os primeiros passos com o FCM, crie o caso de uso mais simples: o envio de uma mensagem de notificação ao dispositivo de um usuário específico quando o app está em segundo plano. Nesta página estão listadas todas as etapas, desde a configuração até a verificação. Se você configurou um aplicativo do cliente JavaScript para o FCM, pode ser que já tenha concluído algumas das etapas mostradas.

Configurar o SDK

Adicione o Firebase a seu projeto JavaScript, caso ainda não tenha feito isso.

Solicitar permissão para receber notificações

O método Notification.requestPermission() da API Web Notifications exibe uma caixa de diálogo de consentimento para que os usuários autorizem o app a receber notificações no navegador. Se a permissão for negada, as solicitações de token de registro do FCM resultarão em erro.

Notification.requestPermission().then((permission) => {
  if (permission === 'granted') {
    console.log('Notification permission granted.');
    // TODO(developer): Retrieve an Instance ID token for use with FCM.
    // ...
  } else {
    console.log('Unable to get permission to notify.');
  }
});

Acessar o token de registro

Esta seção descreve como recuperar o token de registro de uma instância do app e como monitorar os eventos de atualização dele. Como o token pode passar por um rodízio após a primeira inicialização, recomendamos que você recupere o token de registro mais atualizado.

O token de registro pode mudar quando:

  • o app da Web exclui o token de registro;
  • o usuário exclui dados do navegador. Nesse caso, chame getToken para recuperar o novo token.

Recuperar o token de registro atual

Quando você precisar recuperar o token atual, chame getToken. Esse método retorna nulo quando nenhuma permissão foi concedida. Caso contrário, ele retorna um token ou rejeita a promessa por causa de um erro.

O serviço de mensagens requer um arquivo firebase-messaging-sw.js. A menos que você já tenha um arquivo firebase-messaging-sw.js, crie um arquivo vazio com esse nome e coloque-o na raiz do seu domínio antes de recuperar um token. Você pode adicionar conteúdo significativo ao arquivo posteriormente no processo de configuração do cliente.

Para recuperar o token atual:

// Get Instance ID token. Initially this makes a network call, once retrieved
// subsequent calls to getToken will return from cache.
messaging.getToken().then((currentToken) => {
  if (currentToken) {
    sendTokenToServer(currentToken);
    updateUIForPushEnabled(currentToken);
  } else {
    // Show permission request.
    console.log('No Instance ID token available. Request permission to generate one.');
    // Show permission UI.
    updateUIForPushPermissionRequired();
    setTokenSentToServer(false);
  }
}).catch((err) => {
  console.log('An error occurred while retrieving token. ', err);
  showToken('Error retrieving Instance ID token. ', err);
  setTokenSentToServer(false);
});

Monitorar a atualização do token

O retorno de chamada de onTokenRefresh é acionado sempre que um novo token é gerado. Portanto, chamar getToken nesse contexto garantirá o acesso a um token de registro atual e disponível.

// Callback fired if Instance ID token is updated.
messaging.onTokenRefresh(() => {
  messaging.getToken().then((refreshedToken) => {
    console.log('Token refreshed.');
    // Indicate that the new Instance ID token has not yet been sent to the
    // app server.
    setTokenSentToServer(false);
    // Send Instance ID token to app server.
    sendTokenToServer(refreshedToken);
    // ...
  }).catch((err) => {
    console.log('Unable to retrieve refreshed token ', err);
    showToken('Unable to retrieve refreshed token ', err);
  });
});

Depois de receber o token, envie-o para o servidor do app e armazene-o usando seu método preferido. Use a API de servidor Instance ID para receber informações sobre inscrições.

Enviar uma mensagem de notificação de teste

  1. Instale e execute o app no dispositivo de destino.

  2. Verifique se o app está em segundo plano no dispositivo.

  3. Abra o Editor do Notificações e selecione Nova notificação.

  4. Digite o texto da mensagem.

  5. Selecione Enviar mensagem de teste.

  6. No campo Adicionar um token de registro do FCM, insira o token de registro obtido na seção anterior deste guia.

  7. Clique em Testar.

Depois de clicar em Testar, o dispositivo cliente de destino que tem o app em segundo plano receberá a notificação no navegador.

Adicionar propriedades push da Web a um payload de notificação

Com a API HTTP v1, é possível especificar opções de notificação adicionais como um objeto JSON contendo quaisquer propriedades válidas da API Web Notification. Os campos title e body deste objeto, se presentes, modificam os campos equivalentes google.firebase.fcm.v1.Notification.title e google.firebase.fcm.v1.Notification.body.

Solicitação HTTP POST

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

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...PbJ_uNasm

{
  "message": {
    "token" : <token of destination app>,
    "notification": {
      "title": "FCM Message",
      "body": "This is a message from FCM"
    },
    "webpush": {
      "headers": {
        "Urgency": "high"
      },
      "notification": {
        "body": "This is a message from FCM to web",
        "requireInteraction": "true",
        "badge": "/badge-icon.png"
      }
    }
  }
}

Com esta solicitação, os clientes da Web objetivados (incluindo navegadores compatíveis executados no Android) recebem uma mensagem de notificação de alta prioridade que permanece ativa até que o usuário interaja com ela. Ela contém os campos a seguir:

  • Title: FCM Message
  • Body: This is a message from FCM to web
  • RequireInteraction: true
  • Badge: /badge-icon.png

Os aplicativos nativos para Android e iOS (aos quais as modificações da Web não se aplicam) recebem uma mensagem de notificação de prioridade normal com os itens a seguir:

  • Title: FCM Message
  • Body: This is a message from FCM

No momento, RequireInteraction tem compatibilidade parcial entre os navegadores. Os desenvolvedores precisam conferir a especificação da API Web Notification para verificar a compatibilidade com o navegador e a plataforma.

cURL

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...PbJ_uNasm" -H "Content-Type: application/json" -d '{
  "message": {
    "notification": {
      "title": "FCM Message",
      "body": "This is a message from FCM"
    },
    "webpush": {
      "headers": {
        "Urgency": "high"
      },
      "notification": {
        "body": "This is a message from FCM to web",
        "requireInteraction": "true",
        "badge": "/badge-icon.png"
      }
    }
  },
  "token": "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
  }
}' "https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send"

Resposta HTTP

{
    "name": "projects/myproject-b5ae1/messages/0:1500415314455276%31bd1c9631bd1c98"
}

Consulte Criar solicitações de envio do servidor de apps para saber mais sobre mensagens do FCM.

Próximas etapas

Enviar mensagens aos apps em primeiro plano

Depois de enviar com êxito mensagens de notificação enquanto o app está em segundo plano, consulte Receber mensagens em um cliente JavaScript para dar os primeiros passos no envio para apps em primeiro plano.

Ir além das mensagens de notificação

Para ir além das notificações e adicionar outros comportamentos mais avançados ao seu app, consulte os seguintes artigos: