Envía mensajes a grupos de dispositivos en la Web o en JavaScript

Los mensajes por grupos de dispositivos te permiten agregar varios dispositivos a un solo grupo. Esta función es parecida a la mensajería por temas, pero incluye autenticación para garantizar que solo tus servidores puedan administrar la pertenencia a un grupo. Por ejemplo, si quieres enviar mensajes distintos según el modelo de teléfono, tus servidores pueden agregar registros a los grupos correspondientes o quitarlos de ellos, y enviar el mensaje adecuado a cada grupo. La diferencia entre los mensajes por grupos de dispositivos y la mensajería por temas es que los primeros requieren administrar los grupos de dispositivos en tus servidores en lugar de en tu aplicación de manera directa.

La cantidad máxima de miembros permitida para una clave de notificación es de 20.

Administra grupos de dispositivos

Antes de enviar mensajes a un grupo de dispositivos, debes hacer lo siguiente:

1. Obtener los tokens de registro de cada dispositivo que desees agregar al grupo

2. Crear la notification_key, que identifica el grupo de dispositivos mediante la asignación de un grupo específico (por lo general, un usuario) a todos los tokens de registro relacionados del grupo. Puedes crear claves de notificación en el servidor de apps

La administración básica de grupos de dispositivos (crear y quitar grupos, y agregar o quitar dispositivos) se ejecuta a través de la API de HTTP v1 mediante tokens de corta duración para autorizar solicitudes de envío. Consulta las Claves de administración de grupos de dispositivos para obtener una lista de las claves compatibles.

Administra grupos de dispositivos en el servidor de apps

Crea un grupo de dispositivos

Si quieres crear un grupo de dispositivos, envía una solicitud POST que proporcione un nombre para el grupo y una lista de tokens de registro para los dispositivos. FCM muestra una notification_key nueva que representa al grupo de dispositivos.

Solicitud HTTP POST

Envía una solicitud como la siguiente a https://fcm.googleapis.com/fcm/notification:

https://fcm.googleapis.com/fcm/notification
Content-Type:application/json
access_token_auth: true
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
project_id:SENDER_ID

{
   "operation": "create",
   "notification_key_name": "appUser-Chris",
   "registration_ids": ["bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
                        "cR1rjyj4_Kc:APA91bGusqbypSuMdsh7jSNrW4nzsM...",
                        ... ]

El notification_key_name es un nombre o identificador (p. ej., puede ser un nombre de usuario) que es único para un grupo determinado. El notification_key_name y la notification_key son únicos en un grupo de tokens de registro. Si tienes varias apps cliente para el mismo ID de remitente, es importante que notification_key_name sea único en cada una. Esto garantiza que los mensajes solo vayan a la app de destino deseada.

Formato de la respuesta

Una solicitud correcta muestra una notification_key como la siguiente:

{
   "notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ"
}

Guarda la notification_key y el notification_key_name correspondiente para usarlos en otras operaciones.

Cuando se crea correctamente un grupo de dispositivos, se descartan los tokens de registro no válidos.

Recupera una clave de notificación

Si necesitas recuperar una clave de notificación existente, usa notification_key_name en una solicitud GET de la siguiente manera:

https://fcm.googleapis.com/fcm/notification?notification_key_name=appUser-Chris
Content-Type:application/json
access_token_auth: true
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
project_id:SENDER_ID
{}

Para cada solicitud GET de un nombre de clave de notificación determinado, el servidor muestra una string codificada única. Si bien cada string puede parecer una clave diferente, en realidad es un valor válido para "notification_key".

Agrega y quita dispositivos de un grupo de dispositivos

Para agregar o quitar dispositivos de un grupo existente, envía una solicitud POST con los valores add o remove en el parámetro operation y proporciona los tokens de registro para agregarlos o quitarlos.

Si quitas todos los tokens de registro existentes de un grupo de dispositivos, FCM borra el grupo de dispositivos.

Solicitud HTTP POST

Por ejemplo, para agregar un dispositivo con el token de registro bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1... a appUser-Chris, deberías enviar esta solicitud:

{
   "operation": "add",
   "notification_key_name": "appUser-Chris",
   "notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ",
   "registration_ids": ["bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."]
}

Formato de la respuesta

Una solicitud correcta para agregar o quitar un dispositivo muestra una notification_key como la siguiente:

{
   "notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ"
}

Nota: notification_key_name no es necesario para agregar o quitar tokens de registro, pero hacerlo puede evitar que uses una notification_key incorrecta por accidente.

Claves de administración de grupos de dispositivos

En la siguiente tabla, se indican las claves para crear grupos de dispositivos y agregar y quitar miembros.

Tabla 10. Claves de administración de grupos de dispositivos

Parámetro	Uso	Descripción
operation	Obligatorio, string	La operación que se ejecutará. Los valores válidos son create, add y remove.
notification_key_name	Obligatorio, string	El nombre que definió el usuario para el grupo de dispositivos que se creará o se modificará.
notification_key	Obligatorio (excepto para la operación create, string)	El identificador único del grupo de dispositivos. Este valor se muestra en respuesta a una operación de tipo create realizada correctamente y es obligatorio para todas las operaciones posteriores que afecten al grupo de dispositivos.
registration_ids	Obligatorio, arreglo de strings	Los tokens de dispositivo que se agregarán o quitarán. Si quitas todos los tokens de registro existentes de un grupo de dispositivos, FCM lo borrará.

Envía mensajes descendentes a grupos de dispositivos

Para enviar mensajes a grupos de dispositivos, usa la API de HTTP v1. Si actualmente envías mensajes a grupos de dispositivos que usan las APIs de envío heredadas obsoletas para HTTP o XMPP, o cualquiera de las versiones anteriores del Firebase Admin SDK para Node.js según los protocolos heredados, te recomendamos que migres a la API de HTTP v1 lo antes posible. Las APIs de envío heredadas se inhabilitarán y quitarán en junio de 2024.

El proceso para enviar mensajes a un grupo de dispositivos es muy similar al que se usa para enviar mensajes a un dispositivo individual, mediante el mismo método que permite autorizar solicitudes de envío. Establece el campo token en la clave de notificación del grupo:

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":{
      "token":"APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ",
      "data":{
        "hello": "This is a Firebase Cloud Messaging device group message!"
      }
   }
}

Comando cURL

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
"message":{
   "data":{
     "hello": "This is a Firebase Cloud Messaging device group message!"
   },
   "token":"APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ"
}}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send

Nota: A diferencia de los métodos de envío del grupo de dispositivos en las APIs heredadas obsoletas, la respuesta HTTP v1 no contiene recuentos de errores ni resultados correctos. Un envío exitoso muestra una respuesta vacía.