Отправка универсальных пуш-уведомлений по топикам
API разрабатывалось с целью предоставлять возможность отправки пуш-уведомлений по топикам через нескольких пуш-провайдеров одновременно.
Для отправки пуш-уведомления необходимо использовать метод POST https://vkpns-universal.rustore.ru/v1/send/topic.
Чтобы отправить пуш-уведомление в топик необходимо указать «ID проекта» и «Авторизационный токен» для каждого провайдера, по которому планируется отправка пуша.
RuStore
Используйте project_id (ID проекта) и ss_token (сервисный токен). Эти значения вы можете получить в системе RuStore Консоль. Для этого на странице приложения перейдите в раздел «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) | *нет | Специальные параметры Android для сообщений |
*в hms обязательное.
message.notification
| Параметр | Тип | Обязательное | Описание |
| title | string | да | Название уведомления |
| body | string | да | Основной текст уведомления |
| image | string | нет | Содержит URL-адрес изображения, которое будет отображаться в уведомлении |
message.android
| Параметр | Тип | Обязательное | Описание |
| ttl | string (duration format) | нет | Как долго (в секундах) сообщение должно храниться в хранилище. Пример: « 3.5s». |
| notification | object (message.android.notification) | *нет | Уведомление для отправки на устройства Android |
*в hms обязательное.
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 | int | Числовой код ошибки (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 байт.