Protocolo XMPP de mensajería en la nube de Firebase

Este documento proporciona una referencia para la sintaxis XMPP utilizada para pasar mensajes entre su servidor de aplicaciones, aplicaciones cliente y Firebase Cloud Messaging (FCM). Su servidor de aplicaciones debe conectarse a estos puntos finales:

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

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

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

Sintaxis de mensajes posteriores

Esta sección proporciona la sintaxis para enviar mensajes posteriores.

Mensajes XMPP descendentes (JSON)

La siguiente tabla enumera los destinos, las opciones y la carga útil de los mensajes XMPP JSON.

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

Parámetro Uso Descripción
Objetivo
to Opcional, cadena

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 a varios temas, utilice el parámetro condition .

condition Opcional, cadena

Este parámetro especifica una expresión lógica de condiciones que determina el destino del mensaje.

Condición admitida: Tema, formateado como "'tuTema' en temas". Este valor no distingue entre mayúsculas y minúsculas.

Operadores admitidos: && , || . Se admiten un máximo de dos operadores por mensaje de tema.

Opciones
message_id Requerido, cadena

Este parámetro identifica de forma única un mensaje en una conexión XMPP.

collapse_key Opcional, cadena

Este parámetro identifica un grupo de mensajes (por ejemplo, con collapse_key: "Updates Available" ) que se pueden contraer para que solo se envíe el último mensaje cuando se reanude la entrega. Esto tiene como objetivo evitar enviar demasiados mensajes iguales cuando el dispositivo vuelve a estar en línea o sale del estado de reposo.

No hay garantía del orden en que se envían los mensajes.

Nota: Se permite un máximo de 4 claves de colapso diferentes en un momento dado. Esto significa que FCM puede almacenar simultáneamente 4 mensajes diferentes por aplicación cliente. Si excede este número, no hay garantía de qué 4 claves de colapso conservará FCM.

priority Opcional, cadena

Establece la prioridad del mensaje. Los valores válidos son "normal" y "alto". En las plataformas Apple, corresponden a las prioridades 5 y 10 de APN.

De forma predeterminada, los mensajes de notificación se envían con prioridad alta y los mensajes de datos con prioridad normal. La prioridad normal optimiza el consumo de batería de la aplicación cliente y debe usarse a menos que se requiera una entrega inmediata. Para mensajes con prioridad normal, la aplicación puede recibir el mensaje con un retraso no especificado.

Cuando se envía un mensaje con alta prioridad, se envía inmediatamente y la aplicación puede mostrar una notificación.

content_available Opcional, booleano

En las plataformas Apple, utilice este campo para representar content-available en la carga útil de APN. Cuando se envía una notificación o un mensaje y esto se establece en true , se activa una aplicación cliente inactiva y el mensaje se envía a través de APN como una notificación silenciosa y no a través de FCM. Tenga en cuenta que no se garantiza que las notificaciones silenciosas en APN se entreguen y pueden depender de factores como que el usuario active el modo de bajo consumo, fuerce el cierre de la aplicación, etc. En Android, los mensajes de datos activan la aplicación de forma predeterminada. En Chrome, actualmente no es compatible.

mutable_content Opcional, JSON booleano

En las plataformas Apple, utilice este campo para representar mutable-content en la carga útil de APN. Cuando se envía una notificación y esto se establece en true , el contenido de la notificación se puede modificar antes de que se muestre, usando una extensión de la aplicación del Servicio de notificaciones . Este parámetro se ignorará para Android y web.

time_to_live Opcional, número

Este parámetro especifica cuánto tiempo (en segundos) debe mantenerse el mensaje en el almacenamiento FCM si el dispositivo está fuera de línea. El tiempo de vida máximo admitido es de 4 semanas y el valor predeterminado es de 4 semanas. Para obtener más información, consulte Configuración de la vida útil de un mensaje .

dry_run Opcional, booleano

Este parámetro, cuando se establece en true , permite a los desarrolladores probar una solicitud sin enviar 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 Apple, si el mensaje lo entregan APN, representa los campos de datos personalizados. Si lo entrega FCM, se representa como un diccionario de valores clave en AppDelegate application:didReceiveRemoteNotification: .

En Android, esto da como resultado una score con nombre adicional de intención con el valor de cadena 3x1 .

La clave no debe ser una palabra reservada ("de", "tipo_mensaje" ni ninguna palabra que comience con "google" o "gcm"). No utilice ninguna de las palabras definidas en esta tabla (como collapse_key ).

Se recomiendan valores en tipos de cadena. Debe convertir valores en objetos u otros tipos de datos que no sean cadenas (por ejemplo, enteros o booleanos) a cadenas.

notification Opcional, objeto Este parámetro especifica los pares clave-valor predefinidos y visibles para el usuario de la carga útil de notificación. Consulte Compatibilidad con la carga útil de notificaciones para obtener más detalles. Para obtener más información sobre las opciones de mensajes de notificación y mensajes de datos, consulte Tipos de mensajes . Si se proporciona una carga útil de notificación, o la opción content_available está configurada en true para un mensaje a un dispositivo Apple, el mensaje se envía a través de APN ; de lo contrario, se envía a través de FCM.

Soporte de carga útil de notificación

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

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

Parámetro Uso Descripción
title Opcional, cadena

El título de la notificación.

Este campo no es visible en teléfonos y tabletas.

body Opcional, cadena

El texto del cuerpo de la notificación.

sound Opcional, cadena

El sonido que se reproducirá cuando el dispositivo reciba la notificación.

Cadena que especifica archivos de sonido en el paquete principal de la aplicación cliente o en la carpeta Library/Sounds del contenedor de datos de la aplicación. Consulte la biblioteca para desarrolladores de iOS para obtener más información.

badge Opcional, cadena

El valor de la insignia en el ícono de la aplicación de la pantalla de inicio.

Si no se especifica, la insignia no se cambia.

Si se establece en 0 , se elimina la insignia.

click_action Opcional, cadena

La acción asociada con un usuario hace clic en la notificación.

Corresponde a la category en la carga útil de APN.

subtitle Opcional, cadena

El subtítulo de la notificación.

body_loc_key Opcional, cadena

La clave de la cadena del cuerpo en los recursos de cadena de la aplicación que se usará para localizar el texto del cuerpo a la localización actual del usuario.

Corresponde a loc-key en la carga útil de APN.

Consulte Referencia clave de carga útil y Localización del contenido de sus notificaciones remotas para obtener más información.

body_loc_args Opcional, matriz JSON como cadena

Valores de cadena variables que se utilizarán en lugar de los especificadores de formato en body_loc_key para localizar el texto del cuerpo a la localización actual del usuario.

Corresponde a loc-args en la carga útil de APN.

Consulte Referencia clave de carga útil y Localización del contenido de sus notificaciones remotas para obtener más información.

title_loc_key Opcional, cadena

La clave de la cadena de título en los recursos de cadena de la aplicación que se usará para localizar el texto del título a la localización actual del usuario.

Corresponde a title-loc-key en la carga útil de APN.

Consulte Referencia clave de carga útil y Localización del contenido de sus notificaciones remotas para obtener más información.

title_loc_args Opcional, matriz JSON como cadena

Valores de cadena variables que se utilizarán en lugar de los especificadores de formato en title_loc_key para localizar el texto del título a la localización actual del usuario.

Corresponde a title-loc-args en la carga útil de APN.

Consulte Referencia clave de carga útil y Localización del contenido de sus notificaciones remotas para obtener más información.

Tabla 2b. Android: claves para mensajes de notificación

Parámetro Uso Descripción
title Opcional, cadena

El título de la notificación.

body Opcional, cadena

El texto del cuerpo de la notificación.

android_channel_id Opcional, cadena

La identificación del canal de notificación (nuevo en Android O).

La aplicación debe crear un canal con este ID de canal antes de recibir cualquier notificación con este ID de canal.

Si no envía este ID de canal en la solicitud, o si la aplicación aún no ha creado el ID de canal proporcionado, FCM usa el ID de canal especificado en el manifiesto de la aplicación.

icon Opcional, cadena

El icono de notificación.

Establece el ícono de notificación en myicon para el recurso dibujable myicon . Si no envía esta clave en la solicitud, FCM muestra el icono del iniciador especificado en el manifiesto de su aplicación.

sound Opcional, cadena

El sonido que se reproducirá cuando el dispositivo reciba la notificación.

Admite "default" o el nombre de archivo de un recurso de sonido incluido en la aplicación. Los archivos de sonido deben residir en /res/raw/ .

tag Opcional, cadena

Identificador utilizado para reemplazar notificaciones existentes en el cajón de notificaciones.

Si no se especifica, cada solicitud crea una nueva notificación.

Si se especifica y ya se muestra una notificación con la misma etiqueta, la nueva notificación reemplaza la existente en el cajón de notificaciones.

color Opcional, cadena

El color del icono de la notificación, expresado en formato #rrggbb .

click_action Opcional, cadena

La acción asociada con un usuario hace clic en la notificación.

Si se especifica, se inicia una actividad con un filtro de intención coincidente cuando un usuario hace clic en la notificación.

body_loc_key Opcional, cadena

La clave de la cadena del cuerpo en los recursos de cadena de la aplicación que se usará para localizar el texto del cuerpo a la localización actual del usuario.

Consulte Recursos de cadenas para obtener más información.

body_loc_args Opcional, matriz JSON como cadena

Valores de cadena variables que se utilizarán en lugar de los especificadores de formato en body_loc_key para localizar el texto del cuerpo a la localización actual del usuario.

Consulte Formato y estilo para obtener más información.

title_loc_key Opcional, cadena

La clave de la cadena de título en los recursos de cadena de la aplicación que se usará para localizar el texto del título a la localización actual del usuario.

Consulte Recursos de cadenas para obtener más información.

title_loc_args Opcional, matriz JSON como cadena

Valores de cadena variables que se utilizarán en lugar de los especificadores de formato en title_loc_key para localizar el texto del título a la localización actual del usuario.

Consulte Formato y estilo para obtener más información.

Tabla 2c. Web (JavaScript): claves para mensajes de notificación

Parámetro Uso Descripción
title Opcional, cadena

El título de la notificación.

body Opcional, cadena

El texto del cuerpo de la notificación.

icon Opcional, cadena

La URL que se utilizará para el icono de notificación.

click_action Opcional, cadena

La acción asociada con un usuario hace clic en la notificación.

Para todos los valores de URL, se requiere HTTPS.

Interpretar una respuesta de mensaje XMPP descendente

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

Tabla 3 Cuerpo de respuesta XMPP del mensaje descendente.

Parámetro Uso Descripción
from Requerido, cadena

Este parámetro especifica quién envió esta respuesta.

El valor es el token de registro de la aplicación cliente.

message_id Requerido, cadena Este parámetro identifica de forma única un mensaje en una conexión XMPP. El valor es una cadena que identifica de forma única el mensaje asociado.
message_type Requerido, cadena

Este parámetro especifica un mensaje ack o nack de FCM al servidor de aplicaciones.

Si el valor se establece en nack , el servidor de aplicaciones debe mirar error y error_description para obtener información sobre el error.

error Opcional, cadena Este parámetro especifica un error relacionado con el mensaje descendente. Se establece cuando el message_type es nack . Consulte la tabla 4 para obtener más detalles.
error_description Opcional, cadena Este parámetro proporciona información descriptiva del error. Se establece cuando el message_type es nack .

Códigos de respuesta de error de mensajes posteriores

La siguiente tabla enumera los códigos de respuesta de error para mensajes posteriores.

Tabla 4 Códigos de respuesta de error de mensajes posteriores.

Error código XMPP Acción sugerida
Token de registro faltante INVALID_JSON Compruebe que la solicitud contenga un token de registro (en el registration_id en un mensaje de texto sin formato, o en el campo to o registration_ids en JSON).
Registro de APN no válido INVALID_JSON Para registros de iOS, verifique que la solicitud de registro del cliente contenga un token de APN válido y un ID de aplicación.
Token de registro no válido BAD_REGISTRATION Verifique el formato del token de registro que pasa al servidor. Asegúrese de que coincida con el token de registro que recibe la aplicación cliente al registrarse en FCM. No trunque ni agregue caracteres adicionales.
Dispositivo no registrado DEVICE_UNREGISTERED Un token de registro existente puede dejar de ser válido en varios escenarios, entre ellos:
  • Si la aplicación cliente se da de baja de FCM.
  • Si la aplicación cliente se cancela automáticamente, lo que puede suceder si el usuario desinstala la aplicación. Por ejemplo, en iOS, si los APN informan que el token de APN no es válido.
  • Si el token de registro caduca (por ejemplo, Google podría decidir actualizar los tokens de registro o el token APN ha caducado para los dispositivos).
  • Si la aplicación cliente está actualizada, pero la nueva versión no está configurada para recibir mensajes.
Para todos estos casos, elimine este token de registro del servidor de aplicaciones y deje de usarlo para enviar mensajes.
Remitente no coincidente SENDER_ID_MISMATCH Un token de registro está vinculado a un determinado grupo de remitentes. Cuando una aplicación cliente se registra en FCM, debe especificar qué remitentes pueden enviar mensajes. Debe utilizar una de esas ID de remitente al enviar mensajes a la aplicación cliente. Si cambia a un remitente diferente, los tokens de registro existentes no funcionarán.
JSON no válido INVALID_JSON Verifique que el mensaje JSON tenga el formato correcto y contenga campos válidos (por ejemplo, asegurándose de que se pase el tipo de datos correcto).
Mensaje demasiado grande INVALID_JSON Verifique que el tamaño total de los datos de carga útil incluidos en un mensaje no exceda los límites de FCM: 4096 bytes para la mayoría de los mensajes o 2048 bytes en el caso de mensajes a temas. Esto incluye tanto las claves como los valores.
Clave de datos no válida INVALID_JSON Compruebe que los datos de la carga útil no contengan una clave (como from , gcm o cualquier valor con el prefijo google ) que FCM utilice internamente. Tenga en cuenta que FCM también utiliza algunas palabras (como collapse_key ) pero están permitidas en la carga útil, en cuyo caso el valor de la carga útil se anula por el valor de FCM.
Tiempo de vida no válido INVALID_JSON Compruebe que el valor utilizado 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 incorrecto BAD_ACK Verifique que el mensaje ack tenga el formato correcto antes de volver a intentarlo. Consulte la tabla 6 para obtener más detalles.
Se acabó el tiempo SERVICE_UNAVAILABLE

El servidor no pudo procesar la solicitud a tiempo. Vuelva a intentar la misma solicitud, pero debe:

  • Implemente un retroceso exponencial en su mecanismo de reintento. (por ejemplo, si esperó un segundo antes del primer reintento, espere al menos dos segundos antes del siguiente, luego cuatro segundos, y así sucesivamente). Si envía varios mensajes, retrase cada uno de ellos de forma independiente una cantidad aleatoria adicional para evitar emitir una nueva solicitud para todos los mensajes al mismo tiempo.
  • El retraso del reintento inicial debe establecerse en un segundo.

Nota: Los remitentes que causan problemas corren el riesgo de ser incluidos en la lista negra.

Error Interno del Servidor INTERNAL_SERVER_
ERROR
El servidor encontró un error al intentar procesar la solicitud. Puede volver a intentar la misma solicitud siguiendo los requisitos enumerados en "Tiempo de espera" (consulte la fila anterior).
Se superó la tasa de mensajes del dispositivo DEVICE_MESSAGE_RATE
_EXCEEDED
La tasa de mensajes a un dispositivo en particular es demasiado alta. Reduzca la cantidad de mensajes enviados a este dispositivo y no vuelva a intentar enviarlos inmediatamente.
Tasa de mensajes de temas superada TOPICS_MESSAGE_RATE
_EXCEEDED
La tasa de mensajes a suscriptores de un tema en particular es demasiado alta. Reduzca la cantidad de mensajes enviados para este tema y no vuelva a intentar enviarlos inmediatamente.
Drenaje de conexión CONNECTION_DRAINING El mensaje no se pudo procesar porque la conexión se está agotando. Esto sucede porque, periódicamente, FCM necesita cerrar una conexión para realizar el equilibrio de carga. Vuelva a intentar enviar el mensaje a través de otra conexión XMPP.
Credenciales APN no válidas INVALID_APNS_CREDENTIAL No se pudo enviar un mensaje dirigido a un dispositivo iOS porque la clave de autenticación de APN requerida no se cargó o expiró. Verifique la validez de sus credenciales de desarrollo y producción.
Error de autenticación AUTHENTICATION_FAILED No se pudo autenticar con servicios push externos. Compruebe si está utilizando los certificados push web correctos.

Sintaxis de mensajes ascendentes

Un mensaje ascendente es un mensaje que la aplicación cliente envía al servidor de aplicaciones. Actualmente, sólo XMPP admite mensajería ascendente. Consulte la documentación de su plataforma para obtener más información sobre el envío de mensajes desde aplicaciones cliente.

Interpretación de un mensaje XMPP ascendente

La siguiente tabla describe los campos de la estrofa XMPP generada por FCM en respuesta a solicitudes de mensajes ascendentes de aplicaciones cliente.

Tabla 5 Mensajes XMPP ascendentes.

Parámetro Uso Descripción
from Requerido, cadena

Este parámetro especifica quién envió el mensaje.

El valor es el token de registro de la aplicación cliente.

category Requerido, cadena Este parámetro especifica el nombre del paquete de la aplicación cliente que envió el mensaje.
message_id Requerido, cadena Este parámetro especifica el ID único del mensaje.
data Opcional, cadena Este parámetro especifica los pares clave-valor de la carga útil del mensaje.

Enviar un mensaje ACK

La siguiente tabla describe la respuesta ACK que se espera que el servidor de aplicaciones envíe a FCM en respuesta a un mensaje ascendente que recibió el servidor de aplicaciones.

Tabla 6 Respuesta del mensaje XMPP ascendente.

Parámetro Uso Descripción
to Requerido, cadena

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

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

message_id Requerido, cadena Este parámetro especifica para qué mensaje está destinada la respuesta. El valor debe ser el valor message_id del mensaje ascendente correspondiente.
message_type Requerido, cadena Este parámetro especifica un mensaje ack de un servidor de aplicaciones a CCS. Para mensajes ascendentes, siempre debe configurarse en ack .

Mensajes del servidor FCM (XMPP)

Este es un mensaje enviado desde FCM a un servidor de aplicaciones. Estos son los principales tipos de mensajes que FCM envía al servidor de aplicaciones:

  • Control: estos mensajes generados por CCS indican que se requiere una acción por parte del servidor de aplicaciones.

La siguiente tabla describe los campos incluidos en los mensajes que CCS envía a un servidor de aplicaciones.

Tabla 7 Mensajes de control FCM (XMPP).

Parámetro Uso Descripción
campo común
message_type Requerido, cadena

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

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

control_type Opcional, cadena

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 realizar el equilibrio de carga. A medida que la conexión se agota, no se permite enviar más mensajes a la conexión, pero los mensajes existentes en la canalización continúan procesándose.