Protocolo XMPP de Firebase Cloud Messaging

En este documento, se brinda una referencia para la sintaxis XMPP que se utiliza para pasar mensajes entre tu servidor de apps, las apps cliente y Firebase Cloud Messaging (FCM). Tu servidor de apps debe conectarse a estos extremos:

// Production
fcm-xmpp.googleapis.com:5235

// Testing
fcm-xmpp.googleapis.com:5236

Los parámetros y las opciones disponibles se dividen en las siguientes categorías:

Sintaxis de mensajes descendentes
Códigos de respuesta de errores de mensajes descendentes
Sintaxis de mensajes ascendentes
Mensajes de control de FCM

Sintaxis de mensajes descendentes

Esta sección ofrece la sintaxis para enviar mensajes descendentes.

Mensajes XMPP downstream (JSON)

En la siguiente tabla, se enumeran los destinos, las opciones y la carga útil para mensajes JSON de XMPP.

Tabla 1 Destinos, opciones y carga útil para mensajes XMPP downstream (JSON).

Parámetro	Uso	Descripción
Target
`to`	Opcional, string	Este parámetro especifica el destinatario de un mensaje. El valor puede ser el token de registro de un dispositivo, la clave de notificación de un grupo de dispositivos o un solo tema (con el prefijo `/topics/`). Para enviar varios temas, usa el parámetro `condition`.
`condition`	Opcional, string	Este parámetro especifica una expresión lógica de las condiciones que determina el destino del mensaje. Condición compatible: Topic, con el formato "tuTema" en topics. Este valor no distingue mayúsculas de minúsculas. Operadores admitidos: `&&` y `\|\|`. Se admite un máximo de dos operadores por mensaje a tema.
Opciones
`message_id`	Obligatorio, string	Este parámetro identifica un mensaje en una conexión XMPP de manera inequívoca.
`collapse_key`	Opcional, string	Este parámetro identifica un grupo de mensajes (p. ej., con `collapse_key: "Updates Available"`) que puede contraerse, de modo que solo se envíe el último mensaje cuando se reanude la entrega. Esto es para evitar que se envíen demasiadas instancias del mismo tipo de mensaje cuando el dispositivo vuelve a conectarse o sale del estado de descanso. No se puede garantizar el orden en que se envían los mensajes. Nota: Se permite un máximo de 4 claves de contracción diferentes en cualquier momento. Esto significa que FCM puede almacenar 4 mensajes diferentes por app cliente de manera simultánea. Si se excede esta cantidad, no habrá ninguna garantía de cuáles serán las 4 claves de contracción que conservará FCM.
`priority`	Opcional, string	Establece la prioridad del mensaje. Los valores válidos son “normal” y “high”. En las plataformas de Apple, estos corresponden a las prioridades 5 y 10 del APNS. De forma predeterminada, los mensajes de notificación se envían con prioridad alta y los mensajes de datos se envían con prioridad normal. La prioridad normal optimiza el consumo de la batería de la app cliente y debe usarse salvo que el mensaje deba entregarse inmediatamente. En el caso de los mensajes con prioridad normal, la app puede recibir los mensajes con una demora no específica. Los mensajes con prioridad alta se envían inmediatamente y la app muestra una notificación.
`content_available`	Opcional, booleano	En las plataformas de Apple, usa este campo para representar `content-available` en la carga útil de APNS. Cuando se envía una notificación o un mensaje y el valor del campo es `true`, se despierta una app cliente inactiva y el mensaje se envía a través de APNs como una notificación silenciosa y no a través de FCM. Ten en cuenta que el envío de notificaciones silenciosas en APNS no está garantizado y puede depender de factores como la activación del Modo de bajo consumo por parte del usuario, el cierre forzoso de la app y otros. En Android, los mensajes de datos despiertan la app de forma predeterminada. En Chrome, no se admite actualmente.
`mutable_content`	Opcional, booleano JSON	En las plataformas de Apple, usa este campo para representar `mutable-content` en la carga útil de APNS. Cuando se envía una notificación y el valor de este parámetro es `true`, el contenido de la notificación se puede modificar antes de mostrarse mediante una extensión de app del servicio de notificaciones. Este parámetro se ignorará en Android y en la Web.
`time_to_live`	Opcional, número	Este parámetro especifica el tiempo (en segundos) que se debe conservar el mensaje en el almacenamiento de FCM si el dispositivo se encuentra sin conexión. El tiempo máximo admitido es de 4 semanas, al igual que el valor predeterminado. Para obtener más información, consulta Configura la duración de un mensaje.
`dry_run`	Opcional, booleano	Cuando el valor de este parámetro es `true`, los desarrolladores pueden probar una solicitud sin enviar realmente un mensaje. El valor predeterminado es `false`.
Carga útil
`data`	Opcional, objeto	Este parámetro especifica los pares clave-valor de la carga útil del mensaje. Por ejemplo, con `data:{"score":"3x1"}:`. En las plataformas de Apple, si el mensaje se entrega a través del APNS, representa los campos de datos personalizados. Si lo entrega FCM, se representa como un diccionario de pares clave-valor en `AppDelegate application:didReceiveRemoteNotification:`. En Android, el resultado sería un intent adicional denominado `score` con el valor de string `3x1`. La clave no debe ser una palabra reservada (“from”, “message_type”, ni ninguna palabra que empiece con “google“ o “gcm”). No uses ninguna de las palabras que se definen en esta tabla (por ejemplo, `collapse_key`). Se recomiendan los valores en tipos de string. Los valores de objetos u otros tipos de datos que no sean string (p. ej., enteros o booleanos) deben convertirse.
`notification`	Opcional, objeto	Este parámetro especifica los pares clave-valor predefinidos visibles para el usuario de la carga útil de notificación. Consulta Soporte de carga útil de la notificación para obtener más información. Para obtener más información sobre las opciones de mensajes de notificación y mensajes de datos, consulta los tipos de mensajes. Si se proporciona la carga útil de una notificación o la opción `content_available` tiene el valor `true` para un mensaje a un dispositivo Apple, el mensaje se envía a través de APNs; de lo contrario, se envía a través de FCM.

Soporte de carga de notificación

En las siguientes tablas, se enumeran las claves predefinidas disponibles para crear mensajes de notificación de Android y plataformas de Apple.

Tabla 2a. Apple: claves para mensajes de notificación

Parámetro	Uso	Descripción
`title`	Opcional, string	El título de la notificación. Este campo no es visible en tablets ni teléfonos.
`body`	Opcional, string	El texto del cuerpo de la notificación.
`sound`	Opcional, string	El sonido que se reproduce cuando el dispositivo recibe la notificación. Las strings que especifican los archivos de sonido pueden estar dentro del conjunto principal de la app cliente o en la carpeta `Library/Sounds` del contenedor de datos de la app. Consulta la biblioteca para desarrolladores de iOS para obtener más información.
`badge`	Opcional, string	El valor de la insignia en el ícono de la app de la pantalla principal. Si no se especifica, la insignia no se cambia. Si se le asigna el valor `0`, la insignia se quita.
`click_action`	Opcional, string	La acción asociada con el clic de un usuario en la notificación. Corresponde a `category` en la carga útil de APNS.
`subtitle`	Opcional, string	El subtítulo de la notificación.
`body_loc_key`	Opcional, string	La clave de la string del cuerpo en los recursos de string de la app que se usa para localizar el texto del cuerpo en la localización actual del usuario. Corresponde a `loc-key` en la carga útil de APNS. Para obtener más información, consulta la referencia de la clave de carga útil y cómo localizar el contenido de las notificaciones remotas.
`body_loc_args`	Opcional, matriz de JSON como string	Valores de string variables que se usarán en lugar de los especificadores de formato en `body_loc_key` para localizar el cuerpo del texto en la localización actual del usuario. Corresponde a `loc-args` en la carga útil de APNS. Para obtener más información, consulta la referencia de la clave de carga útil y cómo localizar el contenido de las notificaciones remotas.
`title_loc_key`	Opcional, string	La clave de la string del título en los recursos de string de la app que se usa para localizar el texto del título en la localización actual del usuario. Corresponde a `title-loc-key` en la carga útil de APNS. Para obtener más información, consulta la referencia de la clave de carga útil y cómo localizar el contenido de las notificaciones remotas.
`title_loc_args`	Opcional, matriz de JSON como string	Valores de string variables que se usarán en lugar de los especificadores de formato en `title_loc_key` para localizar el título del texto en la localización actual del usuario. Corresponde a `title-loc-args` en la carga útil de APNS. Para obtener más información, consulta la referencia de la clave de carga útil y cómo localizar el contenido de las notificaciones remotas.

Tabla 2b. Claves para mensajes de notificación en Android

Parámetro	Uso	Descripción
`title`	Opcional, string	El título de la notificación.
`body`	Opcional, string	El texto del cuerpo de la notificación.
`android_channel_id`	Opcional, string	El ID de canal de la notificación (nuevo en Android O). La app debe crear un canal con este ID antes de que se reciba cualquier notificación con él. Si no envías este ID del canal en la solicitud o si la app aún no crea el ID del canal proporcionado, FCM usa el ID del canal que especifica el manifiesto de la app.
`icon`	Opcional, string	El ícono de la notificación. Configura el ícono de la notificación como `myicon` para el elemento de diseño `myicon`. Si no envías esta clave en la solicitud, FCM muestra el ícono de selector que se especifica en el manifiesto de la app.
`sound`	Opcional, string	El sonido que se reproduce cuando el dispositivo recibe la notificación. Admite `"default"` o el nombre de archivo de un recurso de sonido incluido en la app. Los archivos de sonido deben alojarse en `/res/raw/`.
`tag`	Opcional, string	Identificador que se usa para reemplazar las notificaciones existentes en el panel lateral de notificaciones. Si no se configura, cada solicitud crea una nueva notificación. Si se especifica y ya se muestra una notificación con la misma etiqueta, la notificación nueva reemplaza la existente en el panel lateral de notificaciones.
`color`	Opcional, string	El color del ícono de la notificación, expresado en formato `#rrggbb`.
`click_action`	Opcional, string	La acción asociada con el clic de un usuario en la notificación. Si se especifica, se lanza una actividad con un filtro de intents que coinciden cuando un usuario hace clic en la notificación.
`body_loc_key`	Opcional, string	La clave de la string del cuerpo en los recursos de string de la app que se usa para localizar el texto del cuerpo en la localización actual del usuario. Consulta los recursos de string para obtener más información.
`body_loc_args`	Opcional, matriz de JSON como string	Valores de string variables que se usarán en lugar de los especificadores de formato en `body_loc_key` para localizar el cuerpo del texto en la localización actual del usuario. Consulta el formato y estilo para obtener más información.
`title_loc_key`	Opcional, string	La clave de la string del título en los recursos de string de la app que se usa para localizar el texto del título en la localización actual del usuario. Consulta los recursos de string para obtener más información.
`title_loc_args`	Opcional, matriz de JSON como string	Valores de string variables que se usarán en lugar de los especificadores de formato en `title_loc_key` para localizar el título del texto en la localización actual del usuario. Consulta el formato y estilo para obtener más información.

Tabla 2c. Claves para mensajes de notificación en la Web (JavaScript)

Parámetro	Uso	Descripción
`title`	Opcional, string	El título de la notificación.
`body`	Opcional, string	El texto del cuerpo de la notificación.
`icon`	Opcional, string	La URL que se usará para el ícono de la notificación.
`click_action`	Opcional, string	La acción asociada con el clic de un usuario en la notificación. Para todos los valores de URL, debe usarse el protocolo HTTPS.

Interpreta una respuesta de mensajes XMPP descendentes

La siguiente tabla incluye los campos que aparecen en una respuesta de mensaje XMPP descendente.

Tabla 3 Cuerpo de respuesta de mensajes XMPP descendentes

Parámetro	Uso	Descripción
`from`	Obligatorio, string	Este parámetro especifica el emisor de la respuesta. El valor es el token de registro de la app cliente.
`message_id`	Obligatorio, string	Este parámetro identifica un mensaje en una conexión XMPP de manera inequívoca. El valor es una string que identifica el mensaje asociado de manera inequívoca.
`message_type`	Obligatorio, string	Este parámetro especifica un mensaje `ack` o `nack` desde FCM al servidor de apps. Si el valor es `nack`, el servidor de apps debe buscar en `error` y `error_description` para obtener información de fallas.
`error`	Opcional, string	Este parámetro especifica un error relacionado con el mensaje downstream. Se establece cuando el `message_type` es `nack`. Consulta la tabla 4 para ver más detalles.
`error_description`	Opcional, string	Este parámetro proporciona información descriptiva del error. Se establece cuando el `message_type` es `nack`.

Códigos de respuesta de errores de mensajes downstream

En la siguiente tabla, se indican los códigos de respuesta de errores para mensajes descendentes.

Tabla 4 Códigos de respuesta de errores de mensajes descendentes.

Error	Código XMPP	Acción recomendada
Falta el token de registro	`INVALID_JSON`	Verifica que la solicitud contenga un token de registro (en el `registration_id`, si es un mensaje de texto sin formato, o en los campos `to` o `registration_ids` en JSON).
Registro de APNS no válido	`INVALID_JSON`	En el caso de iOS, verifica que la solicitud de registro del cliente contenga un ID de aplicación y un token de APNS válidos.
Token de registro no válido	`BAD_REGISTRATION`	Revisa el formato del token de registro que pasaste al servidor. Asegúrate de que coincida con el token de registro que la app cliente recibe cuando se registra en FCM. No lo trunques ni agregues caracteres adicionales.
Dispositivo no registrado	`DEVICE_UNREGISTERED`	Un token de registro existente puede dejar de ser válido en diversas situaciones, como las siguientes: Si la app cliente deja de estar registrada en FCM. Si se cancela el registro de la app cliente de forma automática, lo cual puede ocurrir si el usuario desinstala la aplicación. Por ejemplo, en iOS, si el APNS informó el token del APNS como no válido. Si caduca el token de registro (por ejemplo, porque Google decidió actualizar los tokens de registro o porque caducó el token del APNS para los dispositivos). Si la app cliente se actualiza, pero la nueva versión no está configurada para recibir mensajes. En todos estos casos, debes quitar este token de registro del servidor de apps y dejar de utilizarlo para enviar mensajes.
El emisor no coincide	`SENDER_ID_MISMATCH`	Un token de registro está asociado con un determinado grupo de emisores. Cuando una app cliente se registra para FCM, debe especificar qué remitentes tienen autorización para enviar mensajes. Debes utilizar el ID de uno de esos remitentes cuando envíes mensajes a la app cliente. Si cambias a otro diferente, los tokens de registro existentes no funcionarán.
JSON no válido	`INVALID_JSON`	Verifica que el mensaje JSON tenga un formato adecuado y contenga campos válidos (por ejemplo, que se pase el tipo de datos correcto).
Mensaje demasiado grande	`INVALID_JSON`	Comprueba que el tamaño total de los datos de la carga útil incluidos en un mensaje no supere los límites de FCM: 4,096 bytes para la mayor parte de los mensajes y 2,048 bytes en el caso de los mensajes a temas. Esto incluye las claves y los valores.
Clave de datos no válida	`INVALID_JSON`	Comprueba que los datos de la carga útil no contengan una clave (como `from`, `gcm` o cualquier valor con el prefijo `google`) que FCM usa internamente. Ten en cuenta que hay algunas palabras (como `collapse_key`) que se usan en FCM, pero se permiten en la carga útil. En este caso, el valor de FCM anula el valor de la carga útil.
Tiempo de vida no válido	`INVALID_JSON`	Comprueba que el valor que se usa en `time_to_live` sea un número entero que represente una duración en segundos entre 0 y 2,419,200 (4 semanas).
Mensaje ACK erróneo	`BAD_ACK`	Comprueba que el mensaje `ack` tenga el formato correcto antes de volver a intentarlo. Consulta la tabla 6 para ver más detalles.
Tiempo de espera	`SERVICE_UNAVAILABLE`	El servidor no pudo procesar la solicitud a tiempo. Vuelve a intentarlo con la misma solicitud, pero haz lo siguiente: Implementa la retirada exponencial en el mecanismo de reintento (p. ej., si esperaste un segundo antes del primer intento, espera al menos dos segundos antes del próximo, luego, cuatro segundos y así sucesivamente). Si envías múltiples mensajes, agrega una demora independiente a cada uno con un valor aleatorio adicional, a fin de evitar emitir una nueva solicitud para todos los mensajes en forma simultánea. La demora después del primer intento debe configurarse en un segundo. Nota: Los remitentes que causen problemas corren el riesgo de ser incluidos en una lista negra.
Error de servidor interno	`INTERNAL_SERVER_ ERROR`	Se produjo un error en el servidor mientras se intentaba procesar la solicitud. Puedes volver a intentar con la misma solicitud siguiendo los requisitos que se enumeran en “Tiempo de espera” (ver fila anterior de esta tabla).
Tasa de mensajes de dispositivos excedida	`DEVICE_MESSAGE_RATE _EXCEEDED`	La tasa de mensajes a un dispositivo específico es demasiado alta. Reduce la cantidad de mensajes que se envían a este dispositivo y no intentes volver a enviarle mensajes a este dispositivo de inmediato.
Tasa de mensajes a temas excedida	`TOPICS_MESSAGE_RATE _EXCEEDED`	La tasa de mensajes a suscriptores de un tema particular es demasiado alta. Reduce la cantidad de mensajes enviados a este tema y no intentes volver a enviar mensajes inmediatamente.
Agotamiento de conexión	`CONNECTION_DRAINING`	El mensaje no se pudo procesar debido al agotamiento de la conexión. Esto se debe a que FCM necesita cerrar una conexión de forma periódica para ejecutar el balanceo de cargas. Vuelve a intentar enviar el mensaje a través de otra conexión XMPP.
Credenciales de APNS no válidas	`INVALID_APNS_CREDENTIAL`	No se pudo enviar un mensaje destinado a un dispositivo iOS, ya que la clave de autenticación de APNS obligatoria venció o no se subió. Verifica la validez de tus credenciales de desarrollo y producción.
Error de autenticación	`AUTHENTICATION_FAILED`	No se pudo autenticar con los servicios push externos. Asegúrate de usar los certificados push web correctos.

Sintaxis de mensajes upstream

Un mensaje ascendente es un mensaje que la app cliente envía al servidor de apps. Actualmente, solo XMPP admite los mensajes upstream. Consulta la documentación de tu plataforma para obtener más información sobre el envío de mensajes desde apps cliente.

Interpretación de un mensaje XMPP ascendente

En la siguiente tabla, se describen los campos de la estrofa XMPP que FCM genera en respuesta a las solicitudes de mensajes upstream desde apps cliente.

Tabla 5 Mensajes XMPP ascendentes

Parámetro	Uso	Descripción
`from`	Obligatorio, string	Este parámetro especifica el emisor del mensaje. El valor es el token de registro de la app cliente.
`category`	Obligatorio, string	Este parámetro especifica el nombre de paquete de aplicación de la app cliente que envió el mensaje.
`message_id`	Obligatorio, string	Este parámetro especifica el ID único del mensaje.
`data`	Opcional, string	Este parámetro especifica los pares clave/valor de la carga útil del mensaje.

Envía un mensaje ACK

En la siguiente tabla, se describe la respuesta ACK que el servidor de apps debe enviar a FCM en respuesta a un mensaje upstream que el servidor de apps recibió.

Tabla 6 Respuesta a mensaje XMPP upstream

Parámetro Uso Descripción

Parámetro	Uso	Descripción
`to`	Obligatorio, string	Este parámetro especifica el destinatario de un mensaje de respuesta. El valor debe ser el token de registro de la app cliente que envió el mensaje ascendente.
`message_id`	Obligatorio, string	Este parámetro especifica el mensaje al cual corresponde la respuesta. Debe ser el valor de `message_id` del mensaje upstream correspondiente.
`message_type`	Obligatorio, string	Este parámetro especifica un mensaje `ack` desde un servidor de apps a CCS. Para los mensajes upstream, se debe definir siempre en `ack`.

to

Obligatorio, string

Este parámetro especifica el destinatario de un mensaje de respuesta.

El valor debe ser el token de registro de la app cliente que envió el mensaje ascendente.

message_id Obligatorio, string Este parámetro especifica el mensaje al cual corresponde la respuesta. Debe ser el valor de message_id del mensaje upstream correspondiente.

message_type Obligatorio, string Este parámetro especifica un mensaje ack desde un servidor de apps a CCS. Para los mensajes upstream, se debe definir siempre en ack.

Mensajes del servidor de FCM (XMPP)

Este es el mensaje enviado desde FCM a un servidor de apps. A continuación, se mencionan los tipos de mensajes principales que FCM envía al servidor de apps:

Control: Estos mensajes generados por CCS indican la acción requerida del servidor de apps.

En la tabla siguiente, se describen los campos incluidos en los mensajes que CCS le envía a un servidor de apps.

Tabla 7 Mensajes de control de FCM (XMPP).

Parámetro Uso Descripción

Parámetro	Uso	Descripción
Campo común
`message_type`	Obligatorio, string	Este parámetro especifica el tipo del mensaje: control. Cuando se configura en `control`, el mensaje incluye el `control_type` para indicar el tipo de control.
`control_type`	Opcional, string	Este parámetro especifica el tipo de mensaje de control enviado desde FCM. Actualmente, solo se admite `CONNECTION_DRAINING`. FCM envía este mensaje de control antes de cerrar una conexión para ejecutar el balanceo de cargas. Cuando se vacía la conexión, no se pueden enviar más mensajes a ella, pero continuarán procesándose los existentes en la canalización.

Campo común

message_type

Obligatorio, string

Este parámetro especifica el tipo del mensaje: control.

Cuando se configura en control, el mensaje incluye el control_type para indicar el tipo de control.

control_type

Opcional, string

Este parámetro especifica el tipo de mensaje de control enviado desde FCM.

Actualmente, solo se admite CONNECTION_DRAINING. FCM envía este mensaje de control antes de cerrar una conexión para ejecutar el balanceo de cargas. Cuando se vacía la conexión, no se pueden enviar más mensajes a ella, pero continuarán procesándose los existentes en la canalización.