Отправка универсальных пуш-уведомлений

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

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

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

RuStore

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

В качестве «Авторизационного токена» используйте «сервисный токен».

FCM

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

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

HMS

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

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

Тело запроса

Параметр Тип Обязательное Описание
providers object (providers) да Провайдеры для отправки push-уведомлений
tokens object (tokens) да Push-токены по провайдерам
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 да Авторизационный токен

tokens

Параметр Тип Обязательное Описание
rustore array (string) нет Push-токены RuStore
fcm array (string) нет Push-токены Firebase
hms array (string) нет Push-токены Huawei

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%  ошибка в провайдере.

  • tokens.%provider_name%  ошибка в токене провайдера.

  • message.%field%  ошибка в сообщении.

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

  • internal  внутренняя ошибка провайдера.
  • validation error  ошибка валидации на стороне провадейра.
  • invalid auth token  ошибка auth токена.
  • too many requests  слишком много запросов.
  • invalid tokens  ошибка в push токенах, будет список через запятую обрезанных токенов (первые 6 символов).

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

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

Providers

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

Tokens

  1. Должен быть хотя-бы один push-токен на провайдера.

Message

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

Ограничения

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

 

Обновлено 6 июня 2023 г.
Was this information helpful?