Envía mensajes a temas en la Web o en JavaScript

Los mensajes por temas de FCM se basan en el modelo de publicación y suscripción. Este método permite enviar un mensaje a varios dispositivos que hayan aceptado un tema específico. Redacta tantos mensajes a temas como sea necesario y FCM manejará la ruta y la entrega del mensaje de manera confiable a los dispositivos correctos.

Por ejemplo, los usuarios de una app de pronóstico local de mareas podrían aceptar un tema de “alertas de corrientes de marea” y recibir notificaciones de condiciones óptimas de pesca en agua salada en áreas específicas. Los usuarios de una app de deportes se pueden suscribir a actualizaciones automáticas para recibir los resultados de los partidos de sus equipos favoritos en vivo.

Estos son algunos puntos que debes tener en cuenta sobre los temas:

  • Los mensajes por temas son ideales para contenido como el clima o para otra información disponible de manera pública.
  • Los mensajes por temas están optimizados en términos de rendimiento, no de latencia. Para enviar mensajes de manera rápida y segura a dispositivos individuales o a un grupo pequeño de estos, orienta los mensajes por tokens de registro en lugar de temas.
  • Si necesitas enviar mensajes a varios dispositivos por usuario, tal vez sea más conveniente que envíes mensajes a grupos de dispositivos en esos casos prácticos.
  • Los mensajes por temas admiten una cantidad ilimitada de suscripciones para cada tema. Sin embargo, FCM aplica los siguientes límites:
    • No se puede suscribir una instancia de app a más de 2,000 temas.
    • Si usas la importación por lotes para suscribir las instancias de app, cada solicitud tiene un límite de 1,000 instancias.
    • La frecuencia de las suscripciones nuevas tiene un límite por proyecto. Si envías demasiadas solicitudes de suscripción en un período breve, los servidores de FCM enviarán una respuesta 429 RESOURCE_EXHAUSTED (“se superó la cuota”). Vuelve a intentarlo con una retirada exponencial.

Suscribe la app cliente a un tema

Para cualquier par de token de registro y nombre de tema, puedes agregar el token al tema mediante la API de servidor Instance ID de Google. Llama a la API de Instance ID en este extremo y proporciona el token de registro de la instancia de la app y el nombre del tema:

 https://iid.googleapis.com/iid/v1/<REGISTRATION_TOKEN>/rel/topics/<TOPIC_NAME>

Para suscribir una instancia de la app a un tema denominado “películas”, por ejemplo, envía la siguiente solicitud POST desde tu servidor hacia el extremo y agrega la clave de API del servidor en el encabezado de la autorización como se muestra en este ejemplo:

https://iid.googleapis.com/iid/v1/nKctODamlM4:CKrh_PC8kIb7O...clJONHoA/rel/topics/movies
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

Para proteger la confidencialidad de la clave del servidor, nunca envíes este tipo de solicitud desde el cliente.

Si la solicitud se ejecuta correctamente, se mostrará la respuesta HTTP 200 OK. Para obtener más información sobre las respuestas de error y la forma de enviar solicitudes por lotes, consulta cómo crear asignaciones de relaciones para instancias de apps.

Recibe y administra mensajes por temas

FCM entrega mensajes por temas de la misma manera que otros mensajes descendentes. La manera de manejar los mensajes en el cliente depende del estado de primer o segundo plano de la página web y de otros factores descritos en esta sección.

El comportamiento de los mensajes varía si la página se encuentra en primer plano (tiene el “foco”) o en segundo plano, escondida detrás de otras pestañas o completamente cerrada. En todos los casos, la página debe controlar la devolución de llamada de onMessage, pero en los casos en segundo plano, es posible que también necesites controlar setBackgroundMessageHandler o configurar la notificación en pantalla para permitir que el usuario lleve tu app web al primer plano.

Estado de la app Notificación Datos Ambos
En primer plano onMessage onMessage onMessage
En segundo plano (service worker) Notificación que muestra el SDK setBackgroundMessageHandler Notificación que muestra el SDK

Maneja mensajes cuando la aplicación web está en primer plano

Para recibir el evento onMessage, tu app debe definir el service worker de mensajería de Firebase en firebase-messaging-sw.js. Otra opción es especificar un service worker existente con useServiceWorker.

// Give the service worker access to Firebase Messaging.
// Note that you can only use Firebase Messaging here, other Firebase libraries
// are not available in the service worker.
importScripts('https://www.gstatic.com/firebasejs/4.8.1/firebase-app.js');
importScripts('https://www.gstatic.com/firebasejs/4.8.1/firebase-messaging.js');

// Initialize the Firebase app in the service worker by passing in the
// messagingSenderId.
firebase.initializeApp({
  'messagingSenderId': 'YOUR-SENDER-ID'
});

// Retrieve an instance of Firebase Messaging so that it can handle background
// messages.
const messaging = firebase.messaging();

Cuando la app se encuentra en primer plano (el usuario está viendo tu página web actualmente), puedes recibir datos y cargas de notificaciones directamente en la página.

// Handle incoming messages. Called when:
// - a message is received while the app has focus
// - the user clicks on an app notification created by a service worker
//   `messaging.setBackgroundMessageHandler` handler.
messaging.onMessage(function(payload) {
  console.log('Message received. ', payload);
  // ...
});

Maneja mensajes cuando la aplicación web está en segundo plano

Todos los mensajes que se reciben mientras la app está en segundo plano desencadenan una notificación en pantalla en el navegador. Puedes especificar opciones para esta notificación, como un título o una acción cuando se hace clic, ya sea en la solicitud de envío del servidor de apps o mediante el uso de la lógica del service worker en el cliente.

Configurar opciones de notificación en la solicitud de envío

En el caso de los mensajes de notificación que se envían desde el servidor de apps, la API de JavaScript de FCM es compatible con la clave click_action. Por lo general, esta se dirige a una página de la aplicación web, como en este ejemplo:

https://fcm.googleapis.com//v1/projects/<YOUR-PROJECT-ID>/messages:send
Content-Type: application/json
Authorization: bearer <YOUR-ACCESS-TOKEN>

{
  "message": {
    "topic": "matchday"
    "notification": {
      "title": "Background Message Title",
      "body": "Background message body"
    },
    "webpush": {
      "fcm_options": {
        "link": "https://dummypage.com"
      }
    }
  }
}

Si la acción de hacer clic apunta a una página que ya está abierta en una pestaña del navegador, la pestaña se pondrá en primer plano cuando se haga clic en la notificación. Si la página no está abierta, se abrirá en una pestaña nueva cuando se haga clic en la notificación.

Debido a que los mensajes de datos no son compatibles con click_action, se recomienda que agregues una carga útil de notificación a todos los mensajes de datos. También puedes administrar notificaciones con el service worker.

Para ver una explicación de la diferencia entre los mensajes de notificación y los de datos, consulta los tipos de mensaje.

Cómo configurar las opciones de notificación en el service worker

Tanto para los mensajes de notificación como para los de datos, puedes configurar las opciones de notificación en el service worker. Primero, inicia tu app en el service worker:

// Give the service worker access to Firebase Messaging.
// Note that you can only use Firebase Messaging here, other Firebase libraries
// are not available in the service worker.
importScripts('https://www.gstatic.com/firebasejs/4.8.1/firebase-app.js');
importScripts('https://www.gstatic.com/firebasejs/4.8.1/firebase-messaging.js');

// Initialize the Firebase app in the service worker by passing in the
// messagingSenderId.
firebase.initializeApp({
  'messagingSenderId': 'YOUR-SENDER-ID'
});

// Retrieve an instance of Firebase Messaging so that it can handle background
// messages.
const messaging = firebase.messaging();

Para establecer opciones, llama a setBackgroundMessageHandler en firebase-messaging-sw.js. En este ejemplo, se configuran las opciones de título, cuerpo, ícono y acción de clic.

messaging.setBackgroundMessageHandler(function(payload) {
  console.log('[firebase-messaging-sw.js] Received background message ', payload);
  // Customize notification here
  var notificationTitle = 'Background Message Title';
  var notificationOptions = {
    body: 'Background Message body.',
    icon: '/firebase-logo.png'
  };

  return self.registration.showNotification(notificationTitle,
    notificationOptions);
});

Crea solicitudes de envío

Desde el servidor, enviar mensajes a un tema de Firebase Cloud Messaging es muy similar a enviar mensajes a un dispositivo individual o a un grupo de usuarios. El servidor de apps establece la clave to con el valor /topics/yourTopic. Los desarrolladores pueden elegir cualquier nombre de tema que coincida con la expresión regular "/topics/[a-zA-Z0-9-_.~%]+".

Solicitud HTTP POST del tema

Envía a un tema individual:

https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
{
  "to" : "/topics/foo-bar",
  "priority" : "high",
  "notification" : {
    "body" : "This is a Firebase Cloud Messaging Topic Message!",
    "title" : "FCM Message",
  }
}

Respuesta HTTP del tema

//Success example:
{
  "message_id": "1023456"
}

//failure example:
{
  "error": "TopicsMessageRateExceeded"
}

Mensaje XMPP del tema

Envía a un tema individual:

<message id="">
  <gcm xmlns="google:mobile:data">
{
  "to" : "/topics/foo-bar",
  "priority" : "high",
  "notification" : {
    "body" : "This is a Firebase Cloud Messaging Topic Message!",
    "title" : "FCM Message",
  }
}
  </gcm>
</message>

Respuesta XMPP del tema

//Success example:
{
  "message_id": "1023456"
}

//failure example:
{
  "error": "TopicsMessageRateExceeded"
}

Pasos siguientes

Enviar comentarios sobre...

Si necesitas ayuda, visita nuestra página de asistencia.