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

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

При использовании устаревшего протокола 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> Необязательно, строка

Этот параметр определяет пары ключ-значение полезных данных сообщения. Ограничений на количество параметров «ключ-значение» нет, но общий размер сообщения ограничен 4000 байтами.

Например, в Android "data.score"."3x1" приведет к получению дополнительного именованного score намерения со строковым значением 3x1 .

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

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

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

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

Ответ Описание
200 Сообщение успешно обработано. Тело ответа будет содержать более подробную информацию о статусе сообщения, но его формат будет зависеть от того, был ли запрос JSON или обычный текст. Более подробную информацию смотрите в таблице 5 .
400 Применяется только для запросов JSON. Указывает, что запрос не удалось проанализировать как JSON или он содержал недопустимые поля (например, передача строки там, где ожидалось число). Точная причина сбоя описана в ответе, и проблему следует устранить до повторной попытки запроса.
401 Произошла ошибка при проверке подлинности учетной записи отправителя.
5xx Ошибки в диапазоне 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 удалит группу устройств.