Esta página se ha traducido con Cloud Translation API.

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
Códigos de respuesta de error de mensajes posteriores
Sintaxis de mensajes ascendentes
Mensajes de control FCM

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

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` .

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

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.

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.