Протокол XMPP для обмена сообщениями Firebase Cloud

В этом документе содержится ссылка на синтаксис XMPP, используемый для передачи сообщений между вашим сервером приложений, клиентскими приложениями и Firebase Cloud Messaging (FCM). Ваш сервер приложений должен подключаться к этим конечным точкам:

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

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

Доступные параметры и опции делятся на следующие категории:

Синтаксис нисходящего сообщения

В этом разделе представлен синтаксис для отправки нисходящих сообщений.

Нисходящие сообщения XMPP (JSON)

В следующей таблице перечислены цели, параметры и полезные данные для сообщений XMPP JSON.

Таблица 1. Цели, параметры и полезная нагрузка для нисходящих сообщений XMPP (JSON).

Параметр Использование Описание
Цель
to Необязательно, строка

Этот параметр указывает получателя сообщения.

Значением может быть токен регистрации устройства, ключ уведомления группы устройств или отдельная тема (с префиксом /topics/ ). Чтобы отправить сообщение в несколько тем, используйте параметр condition .

condition Необязательно, строка

Этот параметр определяет логическое выражение условий, определяющее цель сообщения.

Поддерживаемое условие: тема в темах имеет формат «ваша тема». Это значение нечувствительно к регистру.

Поддерживаемые операторы: && , || . Поддерживается максимум два оператора на сообщение темы.

Параметры
message_id Обязательно, строка

Этот параметр однозначно идентифицирует сообщение в соединении XMPP.

collapse_key Необязательно, строка

Этот параметр идентифицирует группу сообщений (например, с collapse_key: "Updates Available" ), которые можно свернуть, чтобы при возобновлении доставки отправлялось только последнее сообщение. Это сделано для того, чтобы избежать отправки слишком большого количества одних и тех же сообщений, когда устройство снова подключается к сети или выходит из спящего режима.

Нет никакой гарантии порядка отправки сообщений.

Примечание. В любой момент времени допускается использование максимум 4 различных ключей свертывания. Это означает, что FCM может одновременно хранить 4 разных сообщения для каждого клиентского приложения. Если вы превысите это число, нет гарантии, какие 4 ключа свертывания сохранятся FCM .

priority Необязательно, строка

Устанавливает приоритет сообщения. Допустимые значения: «нормальный» и «высокий». На платформах Apple они соответствуют приоритетам APN 5 и 10.

По умолчанию сообщения уведомлений отправляются с высоким приоритетом, а сообщения с данными отправляются с обычным приоритетом. Обычный приоритет оптимизирует расход заряда батареи клиентского приложения, и его следует использовать, если не требуется немедленная доставка. Для сообщений с обычным приоритетом приложение может получить сообщение с неопределенной задержкой.

Когда сообщение отправляется с высоким приоритетом, оно отправляется немедленно, и приложение может отображать уведомление.

content_available Необязательно, логическое значение

На платформах Apple используйте это поле для представления content-available в полезной нагрузке APN. Когда отправляется уведомление или сообщение, и для этого параметра установлено значение true , неактивное клиентское приложение просыпается, и сообщение отправляется через APN как автоматическое уведомление, а не через FCM . Обратите внимание, что доставка беззвучных уведомлений в APN не гарантируется и может зависеть от таких факторов, как включение пользователем режима энергосбережения, принудительный выход из приложения и т. д. На Android сообщения с данными пробуждают приложение по умолчанию. В Chrome в настоящее время не поддерживается.

mutable_content Необязательно, логическое значение JSON

На платформах Apple используйте это поле для представления mutable-content в полезной нагрузке APN. Если уведомление отправлено и для него установлено значение true , содержимое уведомления можно изменить перед его отображением с помощью расширения приложения службы уведомлений . Этот параметр будет игнорироваться для Android и Интернета.

time_to_live Дополнительно, номер

Этот параметр указывает, как долго (в секундах) сообщение должно храниться в хранилище FCM , если устройство находится в автономном режиме. Максимальный срок поддержки — 4 недели, значение по умолчанию — 4 недели. Дополнительную информацию см. в разделе «Настройка срока жизни сообщения» .

dry_run Необязательно, логическое значение

Если для этого параметра установлено значение true , разработчики могут протестировать запрос без фактической отправки сообщения.

Значение по умолчанию — false .

Полезная нагрузка
data Необязательно, объект

Этот параметр определяет пары ключ-значение полезных данных сообщения.

Например, с data:{"score":"3x1"}:

На платформах Apple, если сообщение доставляется через APN, оно представляет собой настраиваемые поля данных. Если он доставлен FCM , он представлен как словарь значений ключей в AppDelegate application:didReceiveRemoteNotification:

В Android это приводит к созданию дополнительной именованной score со строковым значением 3x1 .

Ключ не должен быть зарезервированным словом («from», «message_type» или любым словом, начинающимся с «google» или «gcm»). Не используйте слова, определенные в этой таблице (например, collapse_key ).

Рекомендуется использовать значения строкового типа. Вам необходимо преобразовать значения в объектах или других нестроковых типах данных (например, целые или логические значения) в строку.

notification Необязательно, объект Этот параметр указывает предопределенные, видимые пользователю пары «ключ-значение» полезных данных уведомления. Подробности см. в разделе Поддержка полезных данных уведомлений. Дополнительные сведения об уведомлениях и параметрах сообщений с данными см. в разделе Типы сообщений . Если предоставлены полезные данные уведомления или для параметра content_available установлено значение true для сообщения на устройство Apple, сообщение отправляется через APN , в противном случае оно отправляется через FCM .

Поддержка полезной нагрузки уведомлений

В следующих таблицах перечислены предопределенные ключи, доступные для создания уведомлений для платформ Apple и Android.

Таблица 2а. Apple — клавиши для уведомлений

Параметр Использование Описание
title Необязательно, строка

Название уведомления.

Это поле не отображается на телефонах и планшетах.

body Необязательно, строка

Текст уведомления.

sound Необязательно, строка

Звук, который воспроизводится, когда устройство получает уведомление.

Строка, определяющая звуковые файлы в основном пакете клиентского приложения или в папке Library/Sounds контейнера данных приложения. Дополнительную информацию см. в библиотеке разработчиков iOS .

badge Необязательно, строка

Значение значка на значке приложения на главном экране.

Если не указано, значок не изменяется.

Если установлено значение 0 , значок удаляется.

click_action Необязательно, строка

Действие, связанное с щелчком пользователя по уведомлению.

Соответствует category в полезных данных APN.

subtitle Необязательно, строка

Подзаголовок уведомления.

body_loc_key Необязательно, строка

Ключ основной строки в строковых ресурсах приложения, используемый для локализации основного текста в соответствии с текущей локализацией пользователя.

Соответствует loc-key в полезной нагрузке APN.

Дополнительные сведения см. в разделе «Справочник по ключам полезной нагрузки» и «Локализация содержимого удаленных уведомлений» .

body_loc_args Необязательно, массив JSON в виде строки

Значения переменных строк, которые будут использоваться вместо спецификаторов формата в body_loc_key и использоваться для локализации основного текста в соответствии с текущей локализацией пользователя.

Соответствует loc-args в полезных данных APN.

Дополнительные сведения см. в разделе «Справочник по ключам полезной нагрузки» и «Локализация содержимого удаленных уведомлений» .

title_loc_key Необязательно, строка

Ключ строки заголовка в строковых ресурсах приложения, используемый для локализации текста заголовка в соответствии с текущей локализацией пользователя.

Соответствует title-loc-key в полезной нагрузке APN.

Дополнительные сведения см. в разделе «Справочник по ключам полезной нагрузки» и «Локализация содержимого удаленных уведомлений» .

title_loc_args Необязательно, массив JSON в виде строки

Значения переменных строк, которые будут использоваться вместо спецификаторов формата в title_loc_key и использоваться для локализации текста заголовка в соответствии с текущей локализацией пользователя.

Соответствует title-loc-args в полезных данных APN.

Дополнительные сведения см. в разделе «Справочник по ключам полезной нагрузки» и «Локализация содержимого удаленных уведомлений» .

Таблица 2б. Android — клавиши для уведомлений

Параметр Использование Описание
title Необязательно, строка

Название уведомления.

body Необязательно, строка

Текст уведомления.

android_channel_id Необязательно, строка

Идентификатор канала уведомления (новое в Android O).

Приложение должно создать канал с этим идентификатором канала, прежде чем будет получено какое-либо уведомление с этим идентификатором канала.

Если вы не отправляете этот идентификатор канала в запросе или если предоставленный идентификатор канала еще не создан приложением, FCM использует идентификатор канала, указанный в манифесте приложения.

icon Необязательно, строка

Значок уведомления.

Устанавливает значок уведомления myicon для рисуемого ресурса myicon . Если вы не отправите этот ключ в запросе, FCM отобразит значок средства запуска, указанный в манифесте вашего приложения.

sound Необязательно, строка

Звук, который воспроизводится, когда устройство получает уведомление.

Поддерживает "default" или имя файла звукового ресурса, включенного в приложение. Звуковые файлы должны находиться в /res/raw/ .

tag Необязательно, строка

Идентификатор, используемый для замены существующих уведомлений в панели уведомлений.

Если не указано, каждый запрос создает новое уведомление.

Если указано и уведомление с таким же тегом уже отображается, новое уведомление заменяет существующее в панели уведомлений.

color Необязательно, строка

Цвет значка уведомления, выраженный в формате #rrggbb .

click_action Необязательно, строка

Действие, связанное с щелчком пользователя по уведомлению.

Если указано, действие с соответствующим фильтром намерений запускается, когда пользователь нажимает на уведомление.

body_loc_key Необязательно, строка

Ключ основной строки в строковых ресурсах приложения, используемый для локализации основного текста в соответствии с текущей локализацией пользователя.

Дополнительные сведения см. в разделе «Строковые ресурсы» .

body_loc_args Необязательно, массив JSON в виде строки

Значения переменных строк, которые будут использоваться вместо спецификаторов формата в body_loc_key и использоваться для локализации основного текста в соответствии с текущей локализацией пользователя.

Дополнительную информацию см. в разделе «Форматирование и оформление» .

title_loc_key Необязательно, строка

Ключ строки заголовка в строковых ресурсах приложения, используемый для локализации текста заголовка в соответствии с текущей локализацией пользователя.

Дополнительные сведения см. в разделе «Строковые ресурсы» .

title_loc_args Необязательно, массив JSON в виде строки

Значения переменных строк, которые будут использоваться вместо спецификаторов формата в title_loc_key и использоваться для локализации текста заголовка в соответствии с текущей локализацией пользователя.

Дополнительную информацию см. в разделе «Форматирование и оформление» .

Таблица 2в. Web (JavaScript) — клавиши для уведомлений.

Параметр Использование Описание
title Необязательно, строка

Название уведомления.

body Необязательно, строка

Текст уведомления.

icon Необязательно, строка

URL-адрес, который будет использоваться для значка уведомления.

click_action Необязательно, строка

Действие, связанное с щелчком пользователя по уведомлению.

Для всех значений URL требуется HTTPS.

Интерпретация ответа на нисходящее сообщение XMPP

В следующей таблице перечислены поля, которые появляются в ответе на нисходящее сообщение XMPP.

Таблица 3. Тело ответа XMPP нисходящего сообщения.

Параметр Использование Описание
from Обязательно, строка

Этот параметр указывает, кто отправил этот ответ.

Значением является регистрационный токен клиентского приложения.

message_id Обязательно, строка Этот параметр однозначно идентифицирует сообщение в соединении XMPP. Значение представляет собой строку, которая однозначно идентифицирует связанное сообщение.
message_type Обязательно, строка

Этот параметр указывает сообщение ack или nack от FCM на сервер приложений.

Если для параметра установлено значение nack , сервер приложений должен просмотреть error и error_description чтобы получить информацию об ошибке.

error Необязательно, строка Этот параметр указывает ошибку, связанную с нисходящим сообщением. Он устанавливается, когда message_type равен nack . Подробности смотрите в таблице 4 .
error_description Необязательно, строка Этот параметр предоставляет описательную информацию об ошибке. Он устанавливается, когда message_type равен nack .

Коды ответов об ошибках нисходящего сообщения

В следующей таблице перечислены коды ответов об ошибках для нисходящих сообщений.

Таблица 4. Коды ответов об ошибках нисходящего сообщения.

Ошибка XMPP-код Рекомендуемое действие
Отсутствует регистрационный токен INVALID_JSON Убедитесь, что запрос содержит токен регистрации (в поле registration_id в текстовом сообщении или в поле to или registration_ids в JSON).
Неверная регистрация APN INVALID_JSON При регистрации iOS убедитесь, что запрос на регистрацию от клиента содержит действительный токен APNs и идентификатор приложения.
Неверный регистрационный токен BAD_REGISTRATION Проверьте формат регистрационного токена, который вы передаете на сервер. Убедитесь, что он соответствует регистрационному токену, который клиентское приложение получает при регистрации в FCM . Не обрезайте и не добавляйте дополнительные символы.
Незарегистрированное устройство DEVICE_UNREGISTERED Существующий регистрационный токен может перестать быть действительным в ряде сценариев, в том числе:
  • Если клиентское приложение отменяет регистрацию в FCM .
  • Регистрация клиентского приложения автоматически отменяется, что может произойти, если пользователь удалит приложение. Например, в iOS, если APNs сообщили, что токен APNs недействителен.
  • Если срок действия токена регистрации истек (например, Google может принять решение обновить токены регистрации или срок действия токена APNs для устройств истек).
  • Если клиентское приложение обновлено, но новая версия не настроена на получение сообщений.
Во всех этих случаях удалите этот регистрационный токен с сервера приложений и прекратите использовать его для отправки сообщений.
Несоответствующий отправитель SENDER_ID_MISMATCH Регистрационный токен привязан к определенной группе отправителей. Когда клиентское приложение регистрируется в FCM , оно должно указать, каким отправителям разрешено отправлять сообщения. Вам следует использовать один из этих идентификаторов отправителя при отправке сообщений в клиентское приложение. Если вы переключитесь на другого отправителя, существующие регистрационные токены не будут работать.
Неверный JSON INVALID_JSON Убедитесь, что сообщение JSON правильно отформатировано и содержит допустимые поля (например, убедитесь, что передан правильный тип данных).
Сообщение слишком большое INVALID_JSON Убедитесь, что общий размер полезных данных, включенных в сообщение, не превышает ограничений FCM : 4096 байт для большинства сообщений или 2048 байт в случае сообщений в темах. Сюда входят как ключи, так и значения.
Неверный ключ данных INVALID_JSON Убедитесь, что полезные данные не содержат ключ (например, from , gcm или любое значение с префиксом google ), который используется внутри FCM . Обратите внимание, что некоторые слова (например, collapse_key ) также используются FCM , но разрешены в полезных данных, и в этом случае значение полезных данных переопределяется значением FCM .
Неверное время жизни INVALID_JSON Убедитесь, что значение, используемое в time_to_live является целым числом, представляющим продолжительность в секундах от 0 до 2 419 200 (4 недели).
Неверное сообщение ACK BAD_ACK Прежде чем повторить попытку, убедитесь, что ack сообщение имеет правильный формат. Подробности смотрите в таблице 6 .
Тайм-аут SERVICE_UNAVAILABLE

Сервер не смог вовремя обработать запрос. Повторите тот же запрос, но необходимо:

  • Внедрите экспоненциальную отсрочку в механизме повторных попыток. (например, если вы подождали одну секунду перед первой повторной попыткой, подождите не менее двух секунд перед следующей, затем четыре секунды и так далее). Если вы отправляете несколько сообщений, задержите каждое из них независимо на дополнительную случайную величину, чтобы избежать одновременной отправки нового запроса для всех сообщений.
  • Начальная задержка повтора должна быть установлена ​​на одну секунду.

Примечание. Отправители, вызывающие проблемы, рискуют попасть в черный список.

Внутренняя ошибка сервера INTERNAL_SERVER_
ERROR		 Сервер обнаружил ошибку при попытке обработать запрос. Вы можете повторить тот же запрос, следуя требованиям, указанным в разделе «Тайм-аут» (см. строку выше).
Превышена частота сообщений устройства DEVICE_MESSAGE_RATE
_EXCEEDED		 Скорость отправки сообщений на конкретное устройство слишком высока. Уменьшите количество сообщений, отправляемых на это устройство, и не повторяйте отправку на это устройство немедленно.
Превышено количество сообщений в темах TOPICS_MESSAGE_RATE
_EXCEEDED		 Частота сообщений подписчикам по определенной теме слишком высока. Уменьшите количество сообщений, отправляемых по этой теме, и не повторяйте отправку немедленно.
Соединение Дренаж CONNECTION_DRAINING Сообщение не удалось обработать, поскольку соединение разряжается. Это происходит потому, что FCM периодически необходимо закрывать соединение для балансировки нагрузки. Повторите отправку сообщения через другое соединение XMPP.
Неверные учетные данные APN INVALID_APNS_CREDENTIAL Не удалось отправить сообщение, предназначенное для устройства iOS, поскольку необходимый ключ аутентификации APN не был загружен или срок его действия истек. Проверьте действительность своих учетных данных для разработки и производства.
Аутентификация не удалась AUTHENTICATION_FAILED Не удалось пройти аутентификацию с помощью внешних служб push-уведомлений. Проверьте, используете ли вы правильные сертификаты Web Push.

Синтаксис восходящего сообщения

Восходящее сообщение — это сообщение, которое клиентское приложение отправляет на сервер приложений. В настоящее время только XMPP поддерживает восходящий обмен сообщениями. Дополнительную информацию об отправке сообщений из клиентских приложений см. в документации вашей платформы.

Интерпретация восходящего сообщения XMPP

В следующей таблице описаны поля раздела XMPP, созданные FCM в ответ на запросы восходящих сообщений от клиентских приложений.

Таблица 5. Сообщения XMPP восходящего потока.

Параметр Использование Описание
from Обязательно, строка

Этот параметр указывает, кто отправил сообщение.

Значением является регистрационный токен клиентского приложения.

category Обязательно, строка Этот параметр указывает имя пакета приложения клиентского приложения, отправившего сообщение.
message_id Обязательно, строка Этот параметр указывает уникальный идентификатор сообщения.
data Необязательно, строка Этот параметр определяет пары ключ-значение полезных данных сообщения.

Отправка сообщения ACK

В следующей таблице описан ответ ACK, который сервер приложений должен отправить в FCM в ответ на восходящее сообщение, полученное сервером приложений.

Таблица 6. Ответ на сообщение восходящего потока XMPP.

Параметр Использование Описание
to Обязательно, строка

Этот параметр указывает получателя ответного сообщения.

Значение должно быть регистрационным токеном клиентского приложения, отправившего восходящее сообщение.

message_id Обязательно, строка Этот параметр указывает, для какого сообщения предназначен ответ. Значение должно быть значением message_id из соответствующего восходящего сообщения.
message_type Обязательно, строка Этот параметр указывает ack сообщение от сервера приложений в CCS. Для восходящих сообщений всегда должно быть установлено значение ack .

Сообщения сервера FCM (XMPP)

Это сообщение, отправленное из FCM на сервер приложений. Вот основные типы сообщений, которые FCM отправляет на сервер приложений:

  • Контроль: эти сообщения, созданные CCS, указывают на то, что требуется действие со стороны сервера приложений.

В следующей таблице описаны поля, включенные в сообщения, которые CCS отправляет на сервер приложений.

Таблица 7. Управляющие сообщения FCM (XMPP).

Параметр Использование Описание
Общее поле
message_type Обязательно, строка

Этот параметр указывает тип сообщения: управление.

Если установлено значение control , сообщение включает control_type для указания типа управляющего сообщения.

control_type Необязательно, строка

Этот параметр определяет тип управляющего сообщения, отправляемого из FCM .

В настоящее время поддерживается только CONNECTION_DRAINING . FCM отправляет это управляющее сообщение перед закрытием соединения для балансировки нагрузки. По мере истощения соединения больше не разрешается отправлять сообщения в соединение, но существующие сообщения в конвейере продолжают обрабатываться.