Данный документ описывает способ задания дополнительной информации в полезной нагрузке push–уведомления. Данный документ предназначен для разработчиков клиентских и серверных приложений Peers.TV.
Дополнительная информация может быть использована приложением для выполнения тех или иных действий при переходе по push–уведомлению в приложение, например, открытие расписания заданного телеканала.
Поддерживаемые платформы:
С целью задействовать специфичные особенности каждой из поддерживаемых платформ список поддерживаемых действий может различаться.
Для однозначного интерпретирования назначения дополнительных параметров в полезной нагрузке push–уведомления вводится понятие тип события. Тип события описывает назначение события, тип и назначение параметров, передаваемых в полезной нагрузке push–уведомления.
Сущности канал, передача, выпуск телепередачи разделяют одно пространство идентификаторов, поэтому, для простоты, далее вместо упомянутых сущностей будем использовать понятие элемент каталога, по необходимости внося уточнения о типе каталога.
Обязательные параметры:
| параметр | значение |
|---|---|
pdid |
идентификатор push-рассылки |
type |
тип события |
Известные типы событий и их параметры:
| № | Назначение | Что происходит | параметр | тип | смысл параметра |
|---|---|---|---|---|---|
0 |
Зарезервировано. Редакционное сообщение | Открывается приложение | отсутствует | ||
1 |
Рекомендация канала пользователям | Открывается расписание(или эфир канала) | catalogItem |
число |
Идентификатор канала |
3 |
Доступно новое обновление приложения | Открывается страничка в AppStore/Play Market | отсутствует | ||
5 |
Рекомендация тематической подборки | Открывается тематическая подборка | collection |
число |
Идентификатор тематической коллекции |
6 |
Предложение перейти на интернет-ресурс | Осуществляется переход на интернет-ресурс | url |
строка |
Ссылка на интернет-ресурс. |
8 |
Рекомендация выпуска передачи или хайлайта | Открывается выпуск[1] или хайлайт | catalogItem |
число |
Идентификатор выпуска передачи или хайлайта |
| Устарело | |||||
2 |
Рекомендация записи выпуска телепередачи | Открывается просмотр записи | catalogItem |
число |
Идентификатор выпуска телепередачи |
7 |
Уведомление о выходе выпуска телепередачи в эфир | Открывается эфир канала[2] | catalogItem |
число |
Идентификатор выпуска телепередачи |
channelId |
число |
Идентификатор канала (только для платформы Android) | |||
В случае редакционного сообщения указывать тип сообщения не нужно.
Замечание: список известных событий будет расширяться по мере необходимости. Крайне не рекомендуется использовать одно событие для логически разных реакций приложения. Все описанные параметры событий являются обязательными.
При отправке ссылок в качестве параметров рекомендуется использовать shortener-сервисы, например goo.gl.
Перечень событий, описанный выше, может только дополняться. Конкретные события, их параметры не могут быть изменены, в случае подобной необходимости должны быть созданы и описаны новые события.
Для отслеживания эффективности push–уведомлений(количество переходов по действию) необходимо указывать в дополнительных параметрах идентификатор рассылки pdid(Push delivery ID). Выполнив переход по push–уведомлению, клиентское приложение должно отправить на сервер статистики соответствующее событие.
В зависимости от платформы способ формирования запросов и задания дополнительных параметров может отличаться.
Общая схема работы:
Основные и дополнительные параметры указываются в элементе data запроса к GCM шлюзу. После получения push–уведомления клиентскому приложению доступны пары “ключ” – “значение” из элемента data, переданного в запросе. Все параметры находятся на одном уровне.
Основные параметры не подлежат изменению, но список может быть расширен. Основные параметры должны обладать префиксом ‘gcm_’.
Перечень основных параметров:
| название | значение | обязательный | смысл |
|---|---|---|---|
gcm_title |
строка |
нет | Заголовок сообщения |
gcm_message |
строка |
да | Текст сообщения |
Заголовок сообщения может использоваться в заголовке диалогового окна или в Центре уведомлений. Если параметр gcm_title не задан, то в качестве заголовка может использоваться название приложения.
Ограничения GCM:
Примеры сообщений для GCM шлюза:
Уведомление о новом выпуске телепередачи
{
"data": {
"gcm_title": "Передача записана",
"gcm_message": "Мы записали для вас новый выпуск вашей любимой передачи \"Язь против еды\"",
"pdid": 123,
"type": 2,
"catalogItem": 120394723
},
"registration_ids": ["4","8","15","16","23","42"]
}
Уведомление о наличии обновления
{
"data": {
"gcm_title": "Новое обновление",
"gcm_message": "Доступно новое обновление!",
"pdid": 124,
"type": 3
},
"registration_ids":["4","8","15","16","42"]
}
Основные параметры задаются в элементе aps, дополнительные — на верхнем уровне сообщения.
Перечень основных параметров описан в официальной документации от Apple.
Платформа iOS вносит существенные ограничения на размер полезной нагрузки всего push–уведомления, на данной момент эта величина составляет 256 байт с учетом активной, используемой ОС, и пассивной нагрузки.
Таким образом для текстового сообщения за вычетом дополнительных параметров остается около 200 байт. В случае использования кириллицы длина сообщения может составлять до 100 символов.
Ограничения APNS:
Примеры сообщений для APNS шлюза:
Уведомление о новом выпуске телепередачи
{
"aps": {
"alert" : "We've recorded an amazing telecast special for you."
},
"pdid": 123,
"type": 2,
"catalogItem": 120394723
}
Уведомление о наличии обновления
{
"aps": {
"alert" : "Please check for new updates!"
},
"pdid": 124,
"type": 3
}
gcm_title является необязательным для передачи в теле push–уведомления.channelId для события “Уведомление о выходе выпуска телепередачи в эфир” (только для платформы Android).8type в примерахЕсли трансляция закончилась — начать воспроизведение архивной записи, либо сообщить, что передача недоступна в архиве. Если трансляции не закончилась — начать воспроизведении эфира канала. ↩
Если передача закончилась на момент просмотра, то можно сообщить об этом пользователю, либо открыть передачу в записи. ↩