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 descendentes (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 (JSON).
Parámetro | Uso | Descripción | |
---|---|---|---|
Destino | |||
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 | |
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' in topics". Este valor no distingue entre mayúsculas y minúsculas. Operadores admitidos: | |
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 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 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 "alta". En iOS, estos corresponden a prioridad de APNS de 5 y 10. 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 puede mostrar una notificación. | |
content_available |
Opcional, booleano | En iOS, usa este campo para representar | |
mutable_content |
Opcional, booleano JSON | Actualmente, está disponible solo para dispositivos con iOS 10 y versiones más recientes. En iOS, usa este campo para representar | |
time_to_live |
Opcional, número | Este parámetro especifica el tiempo (en segundos) que el mensaje se debe conservar en el almacenamiento de FCM, si el dispositivo se encuentra sin conexión. El tiempo de vida máximo que se admite es de 4 semanas, y el valor predeterminado es de 4 semanas. Para obtener más información, consulta Configuración de la duración de un mensaje. |
|
delivery_receipt_
|
Opcional, booleano | Este parámetro le permite al servidor de apps solicitar la confirmación de la entrega del mensaje. Cuando este parámetro se configura como Nota: Este parámetro no se admite en mensajes enviados a dispositivos iOS. El valor predeterminado es |
|
dry_run |
Opcional, booleano | Cuando el valor de este parámetro es El valor predeterminado es | |
Carga útil | |||
data |
Opcional, objeto | Este parámetro especifica los pares clave-valor de la carga útil del mensaje. Por ejemplo, con En iOS, si el mensaje se envía a través de APNS, representa los campos de datos personalizados. Si se envía a través de FCM, se representa como un diccionario clave-valor en En Android, el resultado sería un intent adicional denominado 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, Se recomiendan los valores en tipos de string. Los valores de objetos y otros tipos de datos (p. ej., números enteros o booleanos) deben convertirse a string. |
|
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 de 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 si la opción content_available tiene el valor true para un mensaje a un dispositivo iOS, este se envía a través de APNS; de lo contrario, se hace mediante el servidor de conexión de FCM.
|
Soporte de carga de notificación
En las siguientes tablas se enumeran las claves predefinidas disponibles para crear mensajes de notificación para iOS y Android.
Tabla 2a. Claves para mensajes de notificación en iOS
Parámetro | Uso | Descripción |
---|---|---|
title |
Opcional, string |
El título de la notificación. Este campo no es visible en tablets y teléfonos con iOS. |
body |
Opcional, string |
El texto del cuerpo de la notificación. |
sound |
Opcional, string o diccionario |
El sonido que se reproduce cuando el dispositivo recibe la notificación.
Las strings que especifican los archivos de sonido pueden estar dentro del paquete principal de la app cliente o en la carpeta |
badge |
Opcional, string |
El valor de la insignia en el ícono de la app de la pantalla principal. Si no se especifica, no se cambia la insignia.
Si se le asigna el valor |
click_action |
Opcional, string |
La acción asociada con el clic de un usuario en la notificación. Corresponde a |
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 Para obtener más información, consulta Referencia de la clave de carga útil y Localiza 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 Corresponde a Para obtener más información, consulta Referencia de la clave de carga útil y Localiza 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 Para obtener más información, consulta Referencia de la clave de carga útil y Localiza 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 Corresponde a Para obtener más información, consulta Referencia de la clave de carga útil y Localiza 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 de canal en la solicitud o si la app aún no crea el ID proporcionado, FCM usa el ID de 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 |
sound |
Opcional, string |
El sonido que se reproduce cuando el dispositivo recibe la notificación. Admite |
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 |
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 Consulta la sección sobre 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 Consulta la sección sobre 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 Si el valor es |
error |
Opcional, string | Este parámetro especifica un error relacionado con el mensaje descendente. 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 descendentes
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). |
Token de registro no válido | BAD_REGISTRATION |
Revisa el formato del token de registro que le pasas 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:
|
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 usar 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 |
Comprueba 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 para 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 que se usan en FCM (como collapse_key ), pero se permiten en la carga útil. En este caso, el valor de FCM anula el valor de la carga útil. |
Tiempo de actividad 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:
Nota: Los remitentes que causen problemas corren el riesgo de ser incluidos en una lista negra. |
Error de servidor interno | INTERNAL_SERVER_
|
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 |
La tasa de mensajes a un dispositivo específico es demasiado alta. Reduce la cantidad de mensajes enviados a ese dispositivo y no intentes volver a enviar mensajes de inmediato. |
Tasa de mensajes a temas excedida | TOPICS_MESSAGE_RATE |
La tasa de mensajes a suscriptores de un tema particular es demasiado alta. Reduce la cantidad de mensajes enviados para este tema y no intentes volver a enviar mensajes de inmediato. |
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. |
Sintaxis de mensajes ascendentes
Un mensaje ascendente es un mensaje que la app cliente envía al servidor de apps. Actualmente, solo XMPP admite los mensajes ascendentes. 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 tabla siguiente, se describen los campos de la estrofa XMPP que FCM genera en respuesta a las solicitudes de mensajes ascendentes 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 ascendente que el servidor de apps recibió.
Tabla 6 Respuesta a mensaje XMPP ascendente
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 ascendente correspondiente. |
message_type |
Obligatorio, string | Este parámetro especifica un mensaje ack desde un servidor de apps a CCS. Para los mensajes ascendentes, se debe definir siempre en |
Mensajes de FCM a un servidor (XMPP)
Este es un mensaje enviado de FCM a un servidor de apps. A continuación, se mencionan los tipos de mensajes principales que FCM envía al servidor de apps:
- Confirmación de entrega: Si el servidor de apps incluyó
delivery_receipt_requested
en el mensaje descendente, FCM enviará una confirmación de entrega cuando se confirme que el dispositivo recibió el mensaje. - 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 |
---|---|---|
Campo común | ||
message_type |
Obligatorio, string | Este parámetro especifica el tipo de mensaje: confirmación de entrega o control. Cuando se configura en Cuando se configura en |
Relacionados específicamente con la confirmación de entrega | ||
from |
Obligatorio, string | Este parámetro se configura con el valor gcm.googleapis.com para indicar que el mensaje se envía desde FCM. |
message_id |
Obligatorio, string | Este parámetro especifica el ID del mensaje original para el que está destinada la confirmación, con el prefijo dr2: : para indicar que el mensaje es una confirmación de entrega. Un servidor de apps debe enviar un mensaje ack con este ID de mensaje para confirmar que recibió esta confirmación de entrega. Consulta la tabla 6 para ver el formato de mensaje ack . |
category |
Opcional, string | Este parámetro especifica el nombre del paquete de aplicación de la app cliente que recibe el mensaje que se informa mediante esta confirmación de entrega. Disponible cuando message_type es receipt . |
data |
Opcional, string | Este parámetro especifica los pares de clave/valor del mensaje de confirmación de entrega. Disponible cuando el tipo de mensaje es receipt .
|
Relacionado específicamente con el control | ||
control_type |
Opcional, string | Este parámetro especifica el tipo de mensaje de control enviado desde FCM. Actualmente, solo se admite |