API Push-уведомлений: Интеграция с RuStore, FCM, HMS и APNS

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

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

Чтобы отправить push-уведомление, укажите 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 проекта и Авторизационный токен. Проверяйте токен самостоятельно.

APNS

• Отправка уведомления в APNS
• Установка соединения с APNS по токену

Тело запроса

Параметр	Тип	Обязательное	Описание
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.
apns	object (provider)	нет	провайдер APNS.

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.
apns	array (string)	нет	Push-токены APNS.

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)	только в HSM	Уведомление для отправки на устройства 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% — ошибка в провайдере.
• tokens.%provider_name% — ошибка в токене провайдера.
• message.%field% — ошибка в сообщении.

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

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

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

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

providers

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

tokens

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

Message

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

Ограничения

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