Отправка сообщений группам устройств

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

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

Максимальное количество участников, разрешенное для ключа уведомления, – 20.

Как управлять группами устройств

Прежде чем отправлять сообщения группе устройств, необходимо:

  1. Получите токены регистрации для каждого устройства, которое хотите добавить в группу.
  2. Создайте notification_key, который идентифицирует группу устройств, сопоставляя определенную группу (обычно пользователя) со всеми связанными с ней токенами регистрации. Ключи уведомлений можно создавать на сервере приложения.

Базовое управление группами устройств (создание и удаление групп, а также добавление и удаление устройств) выполняется с помощью HTTP v1 API и краткосрочных токенов для авторизации запросов на отправку. Список поддерживаемых ключей приведен в разделе Ключи управления группами устройств.

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

Как создать группу устройств

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

HTTP-запрос POST

Отправьте запрос, подобный приведенному ниже, на адрес https://fcm.googleapis.com/fcm/notification:

https://fcm.googleapis.com/fcm/notification
Content-Type:application/json
access_token_auth: true
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
project_id:SENDER_ID

{
   "operation": "create",
   "notification_key_name": "appUser-Chris",
   "registration_ids": ["bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
                        "cR1rjyj4_Kc:APA91bGusqbypSuMdsh7jSNrW4nzsM...",
                        ... ]
}

notification_key_name – это имя или идентификатор (например, имя пользователя), уникальный для данной группы. notification_key_name и notification_key уникальны для группы токенов регистрации. Если у вас несколько клиентских приложений с одним и тем же идентификатором отправителя, важно, чтобы значение notification_key_name было уникальным для каждого из них. Это гарантирует, что сообщения будут отправляться только в целевое приложение.

Формат ответа

При успешном выполнении запроса возвращается объект notification_key, подобный следующему:

{
   "notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ"
}

Сохраните notification_key и соответствующий notification_key_name, чтобы использовать их в последующих операциях.

Как получить ключ уведомлений

Если вам нужно получить существующий ключ уведомления, используйте notification_key_name в GET-запросе, как показано ниже:

https://fcm.googleapis.com/fcm/notification?notification_key_name=appUser-Chris
Content-Type:application/json
access_token_auth: true
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
project_id:SENDER_ID
{}

Для каждого GET-запроса с определенным названием ключа уведомления сервер возвращает уникальную закодированную строку. Хотя каждая строка может выглядеть как отдельный ключ, на самом деле это допустимое значение notification_key.

Получение токенов (FCM) для групп устройств

Если вам нужно получить токены FCM, принадлежащие группе устройств, используйте notification_key в GET-запросе, как показано ниже:

https://fcm.googleapis.com/fcm/notification?notification_key=APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ
Content-Type:application/json
access_token_auth: true
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
project_id:SENDER_ID
{}

Ответ выглядит так:

{
   "notification_key_name": "appUser-Chris",
   "registration_ids": ["token1", "token2"]
}

Как добавлять и удалять устройства из группы устройств

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

HTTP-запрос POST

Например, чтобы добавить устройство с токеном регистрации bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1... в группу appUser-Chris, отправьте следующий запрос:

https://fcm.googleapis.com/fcm/notification
Content-Type:application/json
access_token_auth: true
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
project_id:SENDER_ID

{
   "operation": "add",
   "notification_key_name": "appUser-Chris",
   "notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ",
   "registration_ids": ["bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."]
}
Формат ответа

При успешном выполнении запроса на добавление или удаление устройства возвращается объект notification_key, подобный следующему:

{ "notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ" }

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

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

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

Как отправлять сообщения группам устройств

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

REST

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

{
   "message":{
      "token":"APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ",
      "data":{
        "hello": "This is a Firebase Cloud Messaging device group message!"
      }
   }
}

Команда cURL

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
"message":{
   "data":{
     "hello": "This is a Firebase Cloud Messaging device group message!"
   },
   "token":"APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ"
}}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send