API Push-уведомлений: Работа с RuStore, FCM и HMS

API разрабатывалось с целью предоставлять возможность отправки push-уведомлений по топикам через нескольких push-провайдеров одновременно.

Для отправки push-уведомления необходимо использовать метод POST https://vkpns-universal.rustore.ru/v1/send/topic.

Чтобы отправить push-уведомление в топик необходимо указать ID проекта и Авторизационный токен для каждого провайдера, по которому планируется отправка push-уведомлений.

RuStore

Используйте project_id (ID проекта) и ss_token (сервисный токен). Эти значения вы можете получить в системе Консоль RuStore. Для этого на странице приложения перейдите в раздел Push-уведомления и выберите Проекты. Отправка push-уведомлений.

FCM

Эти значения можно получить в системе RuStore Консоль. Примеры получения токена описаны в документации FCM.

• https://firebase.google.com/docs/cloud-messaging/migrate-v1#use-credentials-to-mint-access-tokens;
• https://firebase.google.com/docs/cloud-messaging/auth-server.

RuStore не хранит ID проекта и Авторизационный токен. Проверяйте токен самостоятельно.

HMS

Эти значения можно получить в системе RuStore Консоль. Пример получения Авторизационного токена есть в документации. ID проекта можно получить в консоли разработчика, не путать с ID приложения, описание есть в документации.

RuStore не хранит ID проекта и Авторизационный токен. Проверяйте токен самостоятельно.

Тело запроса

Параметр	Тип	Обязательное	Описание
providers	object (providers)	да	Провайдеры для отправки push-уведомлений.
topic	string	да	Имя топика.
message	object (message)	да	Структура push-уведомления.

providers

Параметр	Тип	Обязательное	Описание
rustore	object (provider)	нет	Провайдер RuStore.
fcm	object (provider)	нет	Провайдер Firebase.
hms	object (provider)	нет	Провайдер Huawei.

providers.provider

Параметр	Тип	Обязательное	Описание
project_id	string	да	ID проекта.
auth_token	string	да	Авторизационный токен.

message

Параметр	Тип	Обязательное	Описание
data	map	нет	Объект, содержащий пары "key": value.
notification	object (message.notification)	да	Базовый шаблон уведомления для использования на всех платформах.
android	object (message.android)	только в HMS	Специальные параметры Android для сообщений.

message.notification

Параметр	Тип	Обязательное	Описание
title	string	да	Название уведомления.
body	string	да	Основной текст уведомления.
image	string	нет	Содержит URL-адрес изображения, которое будет отображаться в уведомлении.

message.android

Параметр	Тип	Обязательное	Описание
ttl	string (duration format)	нет	Как долго (в секундах) сообщение должно храниться в хранилище. Пример: 3.5s.
notification	object (message.android.notification)	только в HMS	Уведомление для отправки на устройства Android.

message.android.notification

Параметр	Тип	Обязательное	Описание
title	string	да	Название уведомления.
body	string	да	Основной текст уведомления.
icon	string	нет	Значок уведомления.
color	string	нет	Цвет значка уведомления в формате #rrggbb.
image	string	нет	Содержит URL-адрес изображения, которое будет отображаться в уведомлении.
channel_id	string	нет	Идентификатор канала уведомления.
click_action	string	нет	Действие, связанное с кликом пользователя по уведомлению. В HMS по умолчанию стоит тип 1 (intent).

к сведению

В структуре message поддерживаются только представленные выше поля.

Тело успешного ответа

Параметр	Тип	Описание
status	string	В случае успешного ответа возвращается сообщение со статусом OK.

Тело ошибки

Параметр	Тип	Описание
code	number	Числовой код ошибки (404, 400, 403, 401, ...).
status	string	Общее описание ошибки.
errors	array (string)	Ошибки по провайдерам или ошибки валидации.

HTTP status соответствует полю code.

Ошибки делятся на три типа

• Ошибки валидации сообщения.
• Ошибки отправки по провайдерам.
• Ошибки сервиса.

Возможные ошибки при отправке сообщения

• VALIDATION_ERROR — неправильно указаны параметры запроса при отправке сообщения.
• PROVIDER_ERROR — ошибка отправки в провайдер пушей.
• INTERNAL_ERROR — внутренняя ошибка сервиса.

Возможные ошибки валидации при отправке сообщения

• providers.%provider_name% — ошибка в провайдере.
• message.%field% — ошибка в сообщении.

Возможные ошибки провайдеров при отправке сообщения, имеют формат %provider_name%: %error%

• internal — внутренняя ошибка провайдера.
• validation error — ошибка валидации на стороне провайдера.
• invalid auth token — ошибка auth-токена.
• too many requests — слишком много запросов.

Алгоритм валидации

Провайдер обязан иметь токены.

providers

Должен быть хотя бы один провайдер, без провайдеров запрос не валиден.

message

• Если есть непустой payload message.data (то есть хотя бы одна пара ключ-значение внутри), то сообщение валидно. Секции message.notification и message.android могут отсутствовать.
• Если поля message.data нет, то обязательно должен быть notification. В этом случае проверяется наличие либо поля message.notification, либо message.android.notification. Хотя бы что-то одно из этих полей должно присутствовать, но могут присутствовать оба (если присутствуют оба, то некоторые поля перезаписываются).

Ограничения

• Если в уведомлении нет поля ttl или оно равно 0, то учитывается стандартное значение, равное 4 неделям. Если отсутствует секция message.android, то она добавляется с полем ttl.
• Максимальный объем сообщения — 4096 байт.