HTTP-протокол Firebase Cloud Messaging

Внимание! Отправка сообщений (включая восходящие сообщения) с помощью устаревших API FCM XMPP и HTTP устарела 20 июня 2023 г. и будет удалена начиная с июня 2024 г. Если вы используете устаревшие API отправки FCM , мы настоятельно рекомендуем вам перейти на API HTTP v1 или рассмотреть возможность использования Admin SDK для создания запросов на отправку.

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

Приложениям, использующим устаревший API HTTP FCM, следует рассмотреть возможность перехода на API HTTP v1. Дополнительную информацию о преимуществах API версии 1 и инструкции по миграции см. в руководстве по миграции .

При использовании устаревшего протокола HTTP ваш сервер приложений должен направлять все HTTP-запросы в эту конечную точку:

https://fcm.googleapis.com/fcm/send

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

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

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

В этом разделе представлен синтаксис для отправки нисходящих сообщений и интерпретации HTTP-ответов от Firebase Cloud Messaging .

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

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

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

Параметр	Использование	Описание
Цели
to	Необязательно, строка	Этот параметр указывает получателя сообщения. Значением может быть токен регистрации устройства, ключ уведомления группы устройств или отдельная тема (с префиксом /topics/ ). Чтобы отправить сообщение в несколько тем, используйте параметр condition .
registration_ids	Необязательно, массив строк	Этот параметр указывает получателя многоадресного сообщения — сообщения, отправленного более чем на один регистрационный токен. Значением должен быть массив регистрационных токенов, на которые будет отправлено многоадресное сообщение. Массив должен содержать от 1 до 1000 токенов регистрации. Чтобы отправить сообщение на одно устройство, используйте параметр to . Многоадресные сообщения разрешены только в формате HTTP JSON.
condition	Необязательно, строка	Этот параметр определяет логическое выражение условий, определяющих цель сообщения. Поддерживаемое условие: тема в темах имеет формат «ваша тема». Это значение нечувствительно к регистру. Поддерживаемые операторы: && , || . Поддерживается максимум два оператора на сообщение темы.
notification_key Устарело	Необязательно, строка	Этот параметр устарел. Вместо этого используйте to , чтобы указать получателей сообщения. Дополнительную информацию о том, как отправлять сообщения на несколько устройств, см. в документации вашей платформы.
Параметры
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 недели. Дополнительную информацию см. в разделе «Настройка срока жизни сообщения» .
restricted_package_ name (только для Android)	Необязательно, строка	Этот параметр указывает имя пакета приложения, которому должны соответствовать токены регистрации, чтобы получить сообщение.
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 .

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

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

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

Параметр	Использование	Описание
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.

Нисходящие HTTP-сообщения (обычный текст)

В следующей таблице приведен синтаксис целевых объектов, параметров и полезных данных в нисходящих HTTP-сообщениях в виде простого текста.

Таблица 3. Цели, параметры и полезная нагрузка для нисходящих HTTP-сообщений в виде простого текста.

Параметр	Использование	Описание
Цели
registration_id	Обязательно, строка	Этот параметр указывает клиентские приложения (токены регистрации), получающие сообщение. Многоадресная рассылка сообщений (отправка более чем на один регистрационный токен) разрешена только с использованием формата HTTP JSON.
Параметры
collapse_key	Необязательно, строка	Подробности смотрите в таблице 1 .
time_to_live	Дополнительно, номер	Подробности смотрите в таблице 1 .
restricted_package_name	Необязательно, строка	Подробности смотрите в таблице 1 .
dry_run	Необязательно, логическое значение	Подробности смотрите в таблице 1 .
Полезная нагрузка
data.<key>	Необязательно, строка	Этот параметр определяет пары ключ-значение полезных данных сообщения. Ограничений на количество параметров «ключ-значение» нет, но общий размер сообщения ограничен 4096 байтами. Например, в Android "data.score"."3x1" приведет к получению дополнительного именованного score намерения со строковым значением 3x1 . Ключ не должен быть зарезервированным словом («from», «message_type» или любым словом, начинающимся с «google» или «gcm»). Не используйте слова, определенные в этой таблице (например, collapse_key ).

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

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

Таблица 4. Заголовок ответа HTTP-сообщения нисходящего потока.

Ответ	Описание
200	Сообщение успешно обработано. Тело ответа будет содержать более подробную информацию о статусе сообщения, но его формат будет зависеть от того, был ли запрос JSON или обычный текст. Более подробную информацию смотрите в таблице 5 .
400	Применяется только для запросов JSON. Указывает, что запрос не удалось проанализировать как JSON или он содержал недопустимые поля (например, передача строки там, где ожидалось число). Точная причина сбоя описана в ответе, и проблему следует устранить до повторной попытки запроса.
401	Произошла ошибка при проверке подлинности учетной записи отправителя.
5хх	Ошибки в диапазоне 500–599 (например, 500 или 503) указывают на то, что в серверной части FCM при попытке обработки запроса произошла внутренняя ошибка или что сервер временно недоступен (например, из-за тайм-аута). Отправитель должен повторить попытку позже, учитывая любой заголовок Retry-After включенный в ответ. Серверы приложений должны реализовывать экспоненциальную задержку.

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

Таблица 5. Тело ответа HTTP-сообщения нисходящего потока (JSON).

Параметр	Использование	Описание
multicast_id	Обязательно, номер	Уникальный идентификатор (номер), идентифицирующий многоадресное сообщение.
success	Обязательно, номер	Количество сообщений, обработанных без ошибок.
failure	Обязательно, номер	Количество сообщений, которые не удалось обработать.
results	Обязательно, массив объектов	Массив объектов, представляющих статус обработанных сообщений. Объекты перечислены в том же порядке, что и запрос (т. е. для каждого идентификатора регистрации в запросе его результат указан в том же индексе в ответе). message_id : строка, определяющая уникальный идентификатор для каждого успешно обработанного сообщения. error : строка, указывающая ошибку, произошедшую при обработке сообщения для получателя. Возможные значения можно найти в таблице 9 .

Таблица 6. Текст HTTP-ответа сообщения темы (JSON).

Параметр	Использование	Описание
message_id	Дополнительно, номер	Идентификатор сообщения темы, когда FCM успешно получил запрос и попытается доставить его на все подписанные устройства.
error	Необязательно, строка	Ошибка, возникшая при обработке сообщения. Возможные значения можно найти в таблице 9 .

Таблица 7. Успешный ответ для тела ответа нисходящего HTTP-сообщения (обычный текст).

Параметр	Использование	Описание
id	Обязательно, строка	Этот параметр указывает уникальный идентификатор сообщения FCM успешно обработанного.
registration_id	Необязательно, строка	Этот параметр указывает токен регистрации клиентского приложения, которому было обработано и отправлено сообщение.

Таблица 8. Ответ об ошибке для тела ответа нисходящего HTTP-сообщения (обычный текст).

Параметр	Использование	Описание
Error	Обязательно, строка	Этот параметр указывает значение ошибки при обработке сообщения для получателя. Подробную информацию см. в таблице 9 .

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

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

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

Ошибка	HTTP-код	Рекомендуемое действие
Отсутствует регистрационный токен	200 + ошибка: MissingRegistration	Убедитесь, что запрос содержит токен регистрации (в поле registration_id в текстовом сообщении или в поле to или registration_ids в JSON).
Неверный регистрационный токен	200 + ошибка: ИнвалидРегистрация	Проверьте формат регистрационного токена, который вы передаете на сервер. Убедитесь, что он соответствует регистрационному токену, который клиентское приложение получает при регистрации в уведомлениях Firebase. Не обрезайте и не добавляйте дополнительные символы.
Незарегистрированное устройство	200 + ошибка: не зарегистрирован	Существующий регистрационный токен может перестать быть действительным в ряде сценариев, в том числе: Если клиентское приложение отменяет регистрацию в FCM . Если клиентское приложение автоматически отменяется регистрации, что может произойти, если пользователь удалит приложение. Например, в iOS служба обратной связи APNs сообщила, что токен APNs недействителен. Если срок действия токена регистрации истек (например, Google может принять решение обновить токены регистрации или срок действия токена APNs для устройств iOS истек). Если клиентское приложение обновлено, но новая версия не настроена на получение сообщений. Во всех этих случаях удалите этот регистрационный токен с сервера приложений и прекратите использовать его для отправки сообщений.
Неверное имя пакета	200 + ошибка: InvalidPackageName	Убедитесь, что сообщение было адресовано регистрационному токену, имя пакета которого соответствует значению, переданному в запросе.
Ошибка аутентификации	401	Учетную запись отправителя, использованную для отправки сообщения, не удалось аутентифицировать. Возможные причины: Заголовок авторизации отсутствует или имеет неверный синтаксис в HTTP-запросе. Проект Firebase, к которому принадлежит указанный ключ сервера, неверен. Только ключи устаревшего сервера — запрос исходит от сервера, не внесенного в белый список в IP-адресах ключей сервера. Убедитесь, что токен, который вы отправляете в заголовке аутентификации, является правильным ключом сервера, связанным с вашим проектом. Подробности см. в разделе Проверка действительности ключа сервера . Если вы используете устаревший ключ сервера, вам рекомендуется перейти на новый ключ, не имеющий ограничений по IP. См. раздел Перенос ключей устаревшего сервера .
Несоответствующий отправитель	200 + ошибка: MismatchSenderId	Регистрационный токен привязан к определенной группе отправителей. Когда клиентское приложение регистрируется в FCM , оно должно указать, каким отправителям разрешено отправлять сообщения. Вам следует использовать один из этих идентификаторов отправителя при отправке сообщений в клиентское приложение. Если вы переключитесь на другого отправителя, существующие регистрационные токены не будут работать.
Неверный JSON	400	Убедитесь, что сообщение JSON правильно отформатировано и содержит допустимые поля (например, убедитесь, что передан правильный тип данных).
Неверные параметры	400 + ошибка: Инвалидпараметерс	Убедитесь, что предоставленные параметры имеют правильное имя и тип.
Сообщение слишком большое	200 + ошибка: MessageTooBig	Убедитесь, что общий размер полезных данных, включенных в сообщение, не превышает ограничения FCM : 4096 байт для большинства сообщений или 2048 байт в случае сообщений в темах. Сюда входят как ключи, так и значения.
Неверный ключ данных	200 + ошибка: Инвалиддатакей	Убедитесь, что данные полезной нагрузки не содержат ключ (например, from или gcm , или любое значение с префиксом google ), который используется внутри FCM . Обратите внимание, что некоторые слова (например, collapse_key ) также используются FCM , но разрешены в полезных данных, и в этом случае значение полезных данных будет переопределено значением FCM .
Неверное время жизни	200 + ошибка: ИнвалидТтл	Убедитесь, что значение, используемое в time_to_live является целым числом, представляющим продолжительность в секундах от 0 до 2 419 200 (4 недели).
Тайм-аут	5xx или 200 + ошибка: Недоступно	Сервер не смог вовремя обработать запрос. Повторите тот же запрос, но вам необходимо: Учитывайте заголовок Retry-After , если он включен в ответ сервера соединений FCM . Внедрите экспоненциальную отсрочку в механизме повторных попыток. (например, если вы подождали одну секунду перед первой повторной попыткой, подождите не менее двух секунд перед следующей, затем 4 секунды и так далее). Если вы отправляете несколько сообщений, задержите каждое из них независимо на дополнительную случайную величину, чтобы избежать одновременной отправки нового запроса для всех сообщений. Отправители, вызывающие проблемы, рискуют попасть в черный список.
Внутренняя ошибка сервера	500 или 200 + ошибка:InternalServerError	Сервер обнаружил ошибку при попытке обработать запрос. Вы можете повторить тот же запрос, следуя требованиям, указанным в разделе «Тайм-аут» (см. строку выше). Если ошибка не исчезнет, ​​обратитесь в службу поддержки Firebase .
Превышена частота сообщений устройства	200 + ошибка: Скорость сообщения устройства Превышено	Скорость отправки сообщений на конкретное устройство слишком высока. Если приложение Apple отправляет сообщения со скоростью, превышающей ограничения APN, оно может получить это сообщение об ошибке. Уменьшите количество сообщений, отправляемых на это устройство, и используйте экспоненциальную отсрочку для повторной отправки.
Превышено количество сообщений в темах	200 + ошибка: ТемыСообщениеОценка Превышено	Частота сообщений подписчикам по определенной теме слишком высока. Уменьшите количество сообщений, отправляемых по этой теме, и используйте экспоненциальную отсрочку для повторной отправки.
Неверные учетные данные APN	200 + ошибка: Инвалидапнскредентиал	Не удалось отправить сообщение, предназначенное для устройства Apple, поскольку необходимый ключ аутентификации APN не был загружен или срок его действия истек. Проверьте действительность своих учетных данных для разработки и производства.

Управление группой устройств

В следующей таблице перечислены клавиши для создания групп устройств, а также добавления и удаления участников. Дополнительную информацию см. в руководстве для вашей платформы iOS+ или Android .

Табл. 10. Ключи управления группами устройств.

Параметр	Использование	Описание
operation	Обязательно, строка	Операция для запуска. Допустимые значения: create , add и remove .
notification_key_name	Обязательно, строка	Определяемое пользователем имя группы устройств, которую необходимо создать или изменить.
notification_key	Обязательно (кроме операции create , строка	Уникальный идентификатор группы устройств. Это значение возвращается в ответе при успешной операции create и требуется для всех последующих операций с группой устройств.
registration_ids	Обязательно, массив строк	Токены устройства, которые нужно добавить или удалить. Если вы удалите все существующие регистрационные токены из группы устройств, FCM удалит группу устройств.