Отправка push-уведомлений

Для отправки push-уведомления необходимо сформировать запрос на сервер Сервиса уведомлений (Подсистема Сервис уведомлений), указанный в api_url.

POST  {api_url}/projects/{project_id}/messages

Заголовок Content-Type должен иметь значение application/json.

Заголовок Authorization должен иметь значение Bearer access_token, полученный в запросе авторизации.

К адресу сервера Сервиса уведомлений необходимо добавить фрагмент с указанием project_id.

Параметры тела запроса приведены в таблице. Все параметры обязательные.

Параметр	Тип	Описание
target	String	Указывается registrationId, полученный из приложения после его регистрации на сервере Сервиса уведомлений
type	Enum (String)	Поддерживается значение device
ttl	String	Время жизни push-уведомления, например, 5h30m. Может быть задано только в следующих единицах: s — секунды, h — часы, m — минуты
notification	OBJ Notification	Содержание push-уведомления

Параметры объекта Notification приведены в таблице. Все параметры необязательные.

Параметр	Тип	Описание
title	string	Заголовок (до 512 символов)
message	string	Тело сообщения (до 2048 символов)
data	Object	Объект для параметров ключ-значение, можно передавать любые необходимые приложению поля (до 1024 байт)
action	string	Действие, которое будет выполнено в приложении, после нажатия пользователем на уведомление. Действия задаются разработчиком приложений. Например, если у приложения есть D-Bus сервис, в котором определен метод «Open», тогда «Open» можно передать в поле и метод будет вызван системой при клике на уведомление. Поле должно содержать не более 255 символов. Метод должен быть один на поле и метод не должен содержать параметры. Для того, чтобы была возможность вызвать action, push-уведомление должно отобразиться в системном трее.

Примечание. Ключ-значение нужно задавать строкой. Например:

{
  "notification": {
    "data": {
      "Key0": "Value0",
      "Ga": "56",
      "newData": {
        "Key1": "Value1",
        "Key2": "Value2"
      },
      "message": "Hello, World!",
      "title": "Hello Title"
    },
    "target": "RegistrationID",
    "ttl": "2h",
    "type": "device"
  }
}

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

Код и статус ошибки	Описание	Действия для устранения ошибки
400 Bad Request	ttl limit is exceeded	Необходимо проверить допустимое время жизни push-уведомления
400 Bad Request	unsupported message type	Необходимо проверить доступные типы доставки уведомлений
400 Bad Request	invalid notification title length	Необходимо проверить доступные ограничения на создание уведомлений
400 Bad Request	invalid notification message length	Необходимо проверить доступные ограничения на создание уведомлений
400 Bad Request	invalid target	Необходимо проверить доступные значения
400 Bad Request	target not found (указанный registration_id не найден)	registration_id необходимо получить после регистрации устройства и приложения на сервере Сервиса уведомлений
401 Unauthorized	Истек срок действия токена авторизации	Необходимо получить новый токен авторизации
401 Unauthorized	Client authentication failed, the provided client JSON Web key is expired (не удалось выполнить аутентификацию. Срок действия предоставленного ключа истек)	Необходимо обратиться к администратору Сервиса уведомлений с просьбой выпустить новый ключ безопасности проекта и прислать его, после чего следует установить новый ключ и повторить запрос
403 Forbidden	Отсутствуют необходимые права доступа для выполнения запроса	Необходимо обратиться к системному администратору для назначения прав
413 Request Entity Too Large	Общий размер JSON-объекта в теле сообщения превышает 4 кб	Необходимо уменьшить размер JSON-объекта в теле сообщения
429 Too Many Requests	Достигнут лимит количества запросов в секунду	Необходимо сократить количество запросов в секунду для проекта
500 Internal Server Error	Внутренняя системная ошибка сервере Сервиса уведомлений	Необходимо обратиться к системному администратору
504 Gateway Timeout	Инфраструктура Сервиса уведомлений недоступна	Необходимо обратиться к системному администратору

Пример запроса:

POST https://global-push.domain/api/projects/project-from-ui-bthsc2iq44tso869omt0/messages
Content-Type: application/json
{
    "target": "442125d4-6041-4f72-ab4b-1e5fd3ad389a",
    "ttl": "2h",
    "type": "device",
    "notification": {
        "title": "some title",
        "message": "some message",
        "data": {
            "another_key": "value"
        },
	   "action": "command"
    }
}

Пример ответа в случае успеха имеет следующий вид:

{
    "expiredAt": "2020-10-06T07:44:43.967576Z",
    "id": "1526c09c-1ca4-48ea-8357-e1b8aa2f3fc3",
    "notification": {
        "data": {
            "another_key": "value"
        },
        "message": "some message",
        "title": "some title",
	   "action": "command"
    },
    "status": "",
    "string": "", "target": "442125d4-6041-4f72-ab4b-1e5fd3ad389a",
    "type": "device"
}

Push-уведомление с данными в полях title и/или message будет отображаться в системном трее устройства. Исключением является случай, когда приложение запущено и развёрнуто, тогда все данные попадут в приложение и push-уведомление не будет отображаться в системном трее. Если приложение не было запущено в момент получения устройством push-уведомления, тогда приложение не будет запускаться, а push-уведомление будет отображаться в системном трее.

Push-уведомление с данными в поле data будет доставляться напрямую в приложение, минуя отображение в системном трее устройства. Если приложение не было запущено, оно будет запущено в фоне.

Push-уведомление с данными в поле data, title и/или message будет отображено в системном трее и доставлено в приложение одновременно. Исключением будет случай, когда приложение запущено и развёрнуто, тогда все данные попадут в приложение и Push-уведомление не будет отображаться в системном трее.