Envía mensajes a grupos de dispositivos en Android

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.

Puedes usar los mensajes por grupos de dispositivos con los protocolos heredados XMPP o HTTP en tu servidor de apps. Las versiones anteriores del SDK de Firebase Admin para Node.js se basan en los protocolos heredados y también proporcionan capacidades de mensajes por grupos de dispositivos. 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 del servidor de apps. Consulta la referencia del protocolo HTTP heredado para ver una lista de 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
Authorization:key=API_KEY
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.

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
Authorization:key=API_KEY
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.

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

Envía mensajes descendentes a grupos de dispositivos

Enviar mensajes a un grupo de dispositivos es muy similar a enviar mensajes a un dispositivo individual. Establece el parámetro to como la clave de notificación única para el grupo de dispositivos. Consulta los tipos de mensaje para conocer los detalles de la compatibilidad de cargas útiles. Los ejemplos en esta página muestran cómo enviar mensajes de datos a grupos de dispositivos en protocolos heredados HTTP y XMPP.

Solicitud HTTP POST del grupo de dispositivos

https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

{
  "to": "aUniqueKey",
  "data": {
    "hello": "This is a Firebase Cloud Messaging Device Group Message!",
   }
}

Respuesta HTTP del grupo de dispositivos

A continuación, se muestra un ejemplo de un resultado correcto: la notification_key tiene 2 tokens de registro asociados, y el mensaje se envió correctamente a ambos:

{
  "success": 2,
  "failure": 0
}

A continuación, se muestra un ejemplo de un resultado parcialmente correcto: la notification_key tiene 3 tokens de registro asociados. El mensaje se envió correctamente a solo 1 de los tokens de registro. El mensaje de respuesta muestra una lista de los tokens de registro (registration_ids) que no recibieron el mensaje:

{
  "success":1,
  "failure":2,
  "failed_registration_ids":[
     "regId1",
     "regId2"
  ]
}

Cuando un mensaje no se puede entregar a uno o más tokens de registro asociados con una notification_key, el servidor de apps debe volver a intentar la operación tras esperar un período de retirada.

Si el servidor intenta enviar un mensaje a un grupo de dispositivos que no tiene miembros, la respuesta luce como el siguiente ejemplo, con 0 resultados correctos y 0 errores:

{
  "success": 0,
  "failure": 0
}

Mensaje XMPP del grupo de dispositivos

<message id="">
  <gcm xmlns="google:mobile:data">
  {
      "to": "aUniqueKey",
      "message_id": "m-1366082849205" ,
      "data": {
          "hello":"This is a Firebase Cloud Messaging Device Group Message!"
      }
  }
  </gcm>
</message>

Respuesta XMPP del grupo de dispositivos

Cuando un mensaje se envía correctamente a cualquiera de los dispositivos del grupo, el servidor de conexiones XMPP responde con un ACK. Si todos los mensajes enviados a todos los dispositivos del grupo fallan, el servidor de conexiones XMPP responde con un NACK.

A continuación, se muestra un ejemplo de un resultado correcto: la notification_key tiene 3 tokens de registro asociados, y el mensaje se envió correctamente a todos ellos.

{
  "from": "aUniqueKey",
  "message_type": "ack",
  "success": 3,
  "failure": 0,
  "message_id": "m-1366082849205"
}

A continuación, se muestra un ejemplo de un resultado parcialmente correcto: la notification_key tiene 3 tokens de registro asociados. El mensaje se envió correctamente a solo 1 de los tokens de registro. El mensaje de respuesta muestra una lista de los tokens de registro que no recibieron el mensaje:

{
  "from": "aUniqueKey",
  "message_type": "ack",
  "success":1,
  "failure":2,
  "failed_registration_ids":[
     "regId1",
     "regId2"
  ]
}

Cuando el servidor de conexiones de FCM no puede entregar el mensaje a ninguno de los dispositivos del grupo, el servidor de apps recibe una respuesta NACK.

Para ver la lista completa de opciones de mensaje, consulta la información de referencia del protocolo de servidor de conexiones que seleccionaste, HTTP o XMPP.