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

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

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

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

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

  1. Получите регистрационные токены для каждого устройства, которое вы хотите добавить в группу.

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

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

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

Создание группы устройств

Чтобы создать группу устройств, отправьте запрос 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.

Добавление и удаление устройств из группы устройств

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

HTTP POST-запрос

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

{
   "operation": "add",
   "notification_key_name": "appUser-Chris",
   "notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ",
   "registration_ids": ["bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."]
}

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

Успешный запрос на добавление или удаление устройства возвращает notification_key подобный следующему:

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

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

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

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

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

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

Чтобы отправлять сообщения группам устройств, используйте API HTTP v1. Если вы в настоящее время отправляете сообщения группам устройств, используя устаревшие API отправки для HTTP или XMPP или любую из более старых версий Firebase Admin SDK для Node.js на основе устаревших протоколов, мы настоятельно рекомендуем вам перейти на HTTP v1. API при первой возможности. Устаревшие API отправки будут отключены и удалены в июне 2024 года.

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

ОТДЫХ 

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
,

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

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

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

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

  1. Получите регистрационные токены для каждого устройства, которое вы хотите добавить в группу.

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

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

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

Создание группы устройств

Чтобы создать группу устройств, отправьте запрос 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.

Добавление и удаление устройств из группы устройств

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

HTTP POST-запрос

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

{
   "operation": "add",
   "notification_key_name": "appUser-Chris",
   "notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ",
   "registration_ids": ["bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."]
}

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

Успешный запрос на добавление или удаление устройства возвращает notification_key подобный следующему:

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

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

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

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

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

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

Чтобы отправлять сообщения группам устройств, используйте API HTTP v1. Если вы в настоящее время отправляете сообщения группам устройств, используя устаревшие API отправки для HTTP или XMPP или любую из более старых версий Firebase Admin SDK для Node.js на основе устаревших протоколов, мы настоятельно рекомендуем вам перейти на HTTP v1. API при первой возможности. Устаревшие API отправки будут отключены и удалены в июне 2024 года.

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

ОТДЫХ 

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