Подробная документация по API

Подробная документация по API
В данной статье собрана самая последняя и самая подробная документация по работе с API. Мы описали как отправлять уведомления, получать информацию о подписчиках и отправленных уведомлениях

PushAll API - это интерфейс управления вашим каналом и всем что с ним связано. При создании канала вы имеете ID и ключ необходимые для доступа через API.
Для работы с API нужно придерживаться основных положений:
  • По возможности используйте одно соединение. Для этого, при отправке создавайте один объект cUrl (PHP: $ch = curl_init();) и используйте его для всех последующих операций.
  • Вы можете отправлять запросы как через GET так и через POST, но лучше придерживаться POST-метода
  • Не используйте множественные Unicast для отправки одинаковых уведомлений разным пользователям - используйте вместо этого Multicast или Broadcast
  • Не используйте уведомления высокого приоритета и уведомления с высоким TTL, если в этом нет крайней необходимости
Адрес для работы с API один - https://pushall.ru/api.php Не передавайте ваш ключ на другие адреса API сторонних сервисов.
API возвращает ответ в виде JSON объекта, который состоит из ответа, который зависит от выбранного типа запроса, либо из ключа error с описанием ошибки.

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

Для отправки уведомлений вы должны использовать один из четырех типов запроса:
  • SelfAPI (type=self) - отправка самому себе. Этот тип не требует создания канала и связан только с вашим аккаунтом.
  • Broadcast API (type=broadcast) - отправка всем подписчикам канала. Этот тип требует канал и отправляет уведомление всем подписчикам с учетом их фильтров
  • Multicast API (type=multicast) - отправка определенным подписчикам канала. Этот тип требует канал и отправляет уведомление всем перечисленным подписчикам с учетом их фильтров
  • Unicast API (type=unicast) - отправка одному подписчику канала. Этот тип требует канал и отправляет уведомление одному подписчику канала без учета фильтров

Все выше представленные типы отправки поддерживают общие параметры:
  • id - в случае с SelfAPI это ID вашего аккаунта, в случае с другими типами - ID вашего канала.
  • key - в случае с SelfAPI это ключ вашего аккаунта, в случае с другими типами - ключ вашего канала.
  • title - заголовок Push-уведомления. Рекомендуется 15-80 символов, не более.
  • text - основной текст Push-уведомления. Рекомендуется 100-500 символов, не более.
  • icon - иконка уведомления. Не рекомендуется использовать, по-умолчанию используется иконка канала, которая кэшируется на устройстве.
  • url - адрес по которому будет осуществлен переход по клику. Вводить с "http://"/"https://" При желании можно использовать адреса вида tel: или mailto:
  • hidden - 1 - сразу скрыть уведомление из истории пользователей, 2 - скрыть только из ленты, 0 - не скрывать (по-умолчанию 0)
  • encode - ваша кодировка. (не обязательно) например cp1251
  • priority - приоритет.
    Это очень важный параметр, которому надо уделить внимание.
    0 - по по-умолчанию. -1 - не важные, менее заметны, не будят устройство. 1 - более заметные, быстрее сажают аккумулятор. По возможности используйте -1, иногда можно 0, используйте 1 в случае крайней необходимости. Скорее всего в будущем для broadcast и/или multicast высокий приоритет будет запрещен.
  • ttl - время жизни в секундах. По-умолчанию 25 дней - 2160000 секунд, или тот что выбран у вас в настройке канала, или тот что указан в ограничениях вашей категории канала. Выбирайте TTL с умом - чем ближе TTL к времени актуальности информации, чем ниже навязчивость оповещений.
  • filter - управление фильтрацией. Этот параметр ведет себя по разному для разных типов уведомлений. Для SelfAPI не работает, для Broadcast и Multicast можно передать filter=-1 и тогда фильтрация будет выключена принудительно. Не используйте этот метод слишком часто, т.к. пользователи рассчитывают на то, что фильтры будут всегда работать. Это можно использовать, например если вам нужно отправить всем важное сообщение о технических работах, или изменении в настройках вашего канала. Для Unicast можно передать filter=1 и принудительно включить фильтрацию, полезно, если вы используете множественные Unicast и хотите при этом задействовать встроенную фильтрацию PushAll

Rich Push Notifications

Вы также можете использовать Rich Push Notifications, с добавлением крупного изображения и двух кнопок. Для этого вы можете передать поле additional с полями bigimage и actions в JSON. Пример массива POST для broadcast при передаче через PHP
array(
    "type" => "broadcast",
    "id" => "1", //ID канала
    "key" => "0077f8aba41b8f6e0030e9b2b0b23f7b", //ключ канала
    "text" => "Тестовое сообщение", //текст уведомления - не более 500 символов
    "title" => "Заголовок", //заголовок уведомления - не более 100 символов
    "url" => "https://pushall.ru", //адрес для перехода по клику
    "ttl" => 60, //время актуальности в секундах, после которого доставка не нужна
    "additional" => 
    	json_encode(
	    	array(
	    		'bigimage'=> 'https:\/\/urlimage',
	    		'actions' => 
	    			array(
	    				array('title' => 'text',
	    					'url' => 'https:\/\/url1'),
						array('title' => 'text2',
							'url' => 'https:\/\/url2')
						)
	    		)
    	)
  )


SelfAPI

Необходим для отправки самому себе. Вы можете настроить, например в вашем торрент клиенте, отправку команды через cUrl, и получать уведомления о окончании загрузки торрента. Или у себя в мониторинге настроить отправку PUSH-уведомлений о каких-либо ошибках или проблемах связанных с вашими разработками. Также вы можете использовать этот тип оповещений, для настройки получения уведомлений из IFTTT (пример настройки)
Ключ для SelfAPI можно получить в разделе Администрирование во вкладке "API - общее"
Пример кода для отправки уведомления:
$ch = curl_init();
curl_setopt_array($ch, array(
CURLOPT_URL => "https://pushall.ru/api.php",
CURLOPT_POSTFIELDS => array(
    "type" => "self",
    "id" => "1",
    "key" => "0077f8aba41b8f6e0030e9b2b0b23f7b",
    "text" => "Тестовое сообщение",
    "title" => "Заголовок"
  ),
  CURLOPT_RETURNTRANSFER => true
));
$return=json_decode(curl_exec($ch)); //получить ответ или ошибку
curl_close($ch);

Ограничения Self API: нельзя отправлять более одного уведомления чаще чем раз в 3 секунды
Нельзя отправлять дубликаты уведомления содержащие одинаковые заголовок и текст чаще чем раз в 10 минут.

При отправке, вы получите ответ от API вида:
{"success":4,"lid":1607175} - это означает, что 4 устройства были использованы при отправке, а ID вашего уведомления 1607175. Для SelfAPI это число на данный момент практически бесполезно, т.к. нет API для получения данных о отправленных Self уведомлениях.

Broadcast API

Необходим для отправки всему каналу. Для отправки этим и последующими методами нужно создать канал. При использовании этого типа работают пользовательские фильтры, что ведет к тому, что не все подписчики получат уведомления, а лишь те, у кого подошли фильтры под ваше уведомление.
array(
    "type" => "broadcast",
    "id" => "1", //ID канала
    "key" => "0077f8aba41b8f6e0030e9b2b0b23f7b", //ключ канала
    "text" => "Тестовое сообщение", //текст уведомления - не более 500 символов
    "title" => "Заголовок", //заголовок уведомления - не более 100 символов
    "url" => "https://pushall.ru", //адрес для перехода по клику
    "ttl" => 60, //время актуальности в секундах, после которого доставка не нужна
  )


Ограничения Broadcast API: нельзя отправлять более одного уведомления чаще чем раз в 30 секунд
Нельзя отправлять дубликаты уведомления содержащие одинаковые заголовок и текст чаще чем раз в 10 минут.
Такие ограничения на broadcast сделаны прежде всего, чтобы исключить возможность ошибочного запуска скрипта с вашей стороны. Будет крайне неприятно, если все 10-100 тысяч подписчиков получат 10 уведомлений за минуту.

API вернет приблизительно такой ответ:
{"benchmark":{"start":"0.06941500 1460901106"},"success":1,"ttl":0,"unfilt":1,"all":1,"lid":1607191,"status":"Run in background"}
Время начала отправки, предварительные данные отправки (success, unfilt, all) - скорее всего будут позже убраны из ответа (сейчас они показывают данные по отправке через GCM, а не полные для всех устройств), как и статус "Run in background".
Для определения успешности отправки стоит ориентироваться на LID. Отправка теперь всегда идет в фоне, то есть статистику по отправке и хронометрах можно будет получить при помощи ShowList API.

Multicast API

Необходим для отправки определенной группе пользователей. При использовании этого типа работают пользовательские фильтры, то есть не все, кого вы укажите получат уведомления, а лишь те, у кого ваше уведомление пройдет через фильтр.
Вы должны перечислить ID пользователей, которые подписаны на ваш канал, которые должны получить уведомление. Это нужно сделать в параметре uids в формате JSON. То есть символы [ ], между которыми ID пользователей через запятую, которые должны получить уведомление.
Пример кода для отправки уведомления:
array(
    "type" => "multicast",
    "id" => "1",
    "key" => "0077f8aba41b8f6e0030e9b2b0b23f7b", //ключ канала
    "text" => "Тестовое сообщение", //текст уведомления - не более 500 символов
    "title" => "Заголовок", //заголовок уведомления - не более 100 символов
    "url" => "https://pushall.ru", //адрес для перехода по клику
    "ttl" => 60, //время актуальности в секундах, после которого доставка не нужна
    "uids" => "[1,2,3,4,5]"
  )

Ограничения Multicast API: на данный момент ограничений по времени отправки нет, однако в случае злоупотреблений, оно будет введено на пользователя не чаще чем раз в 3 секунды, это является рекомендованным временем на данный момент.
Нельзя отправлять дубликаты уведомления содержащие одинаковые заголовок и текст чаще чем раз в 10 минут.
Ответ от API схож с ответом Broadcast API.

Unicast API

Необходим для отправки одному подписчику канала. При использовании этого типа не работают пользовательские фильтры.
Вы должны указать ID пользователя, которому хотите отправить уведомление в параметре UID.
Пример кода для отправки уведомления:
array(
    "type" => "unicast",
    "id" => "1",
    "key" => "0077f8aba41b8f6e0030e9b2b0b23f7b", //ключ канала
    "text" => "Тестовое сообщение", //текст уведомления - не более 500 символов
    "title" => "Заголовок", //заголовок уведомления - не более 100 символов
    "url" => "https://pushall.ru", //адрес для перехода по клику
    "ttl" => 60, //время актуальности в секундах, после которого доставка не нужна
    "uid" => "1"
  )

Ограничения Unicast API: на данный момент ограничений по времени отправки нет, однако в случае злоупотреблений, оно будет введено на пользователя не чаще чем раз в 3 секунды, это является рекомендованным временем на данный момент.
Нельзя отправлять дубликаты уведомления содержащие одинаковые заголовок и текст чаще чем раз в 10 минут.

Ответ от API: {"success":5} указывает число устройств, которые участвовали при отправке.
Стоит учитывать, что ни один тип не дает точного числа устройств при отправке, точное число и статистику можно узнать лишь по окончании полной отправки используя ShowList API.

ShowList API

Позволяет получать ленту вашего канала, информацию о отправленных уведомлениях, информацию о ваших подписчиках.
Пример кода для получения ленты канала
array(
    "type" => "showlist",
    "id" => "1",
    "key" => "0077f8aba41b8f6e0030e9b2b0b23f7b",
    "limit" => 10, //ограничение количества уведомлений,
    "lid" => 1 //необязательный параметр с переданным ID уведомления
  )

Ответ приходит в виде JSON и состоит из одного массива data, который содержит внутри себя внутренние массивы, ключем которых является lid, примерная структура отображена на скриншоте ниже:

В данных, полученных этим методом можно получить статистику по хронометражу отправки (за исключением возможных отправок с задержкой), а также статистку принятых, удаленных или открытых уведомлений. Нужно учитывать, что многие методы приёма уведомлений не могут полноценно обрабатывать статистку, например iOS, Safari, Telegram не могут определить приём уведомления или закрытие.
Если передать параметр lid, можно получить данные по одному уведомлению, в том числе, если это уведомление отправлено через multicast или unicast.

ShowList API - Users

Позволяет получать информацию о ваших подписчиках. Просто передайте subtype = users и вы получите список ваших подписчиков, передайте uid и вы получите данные по одному из подписчиков.
Пример кода для получения данных о подписчиках
array(
    "type" => "showlist",
    "subtype" => "users",
    "id" => "1",
    "key" => "0077f8aba41b8f6e0030e9b2b0b23f7b",
    "uid" => 1 //необязательный параметр ID подписчика
  )

Возвращаемые данные схожи с теми, что и в обычном ShowList, только ключ это ID пользователя, а внутри массива находятся подписчики.
Если передать ID пользователя, который не подписан, будет возвращено - {"data":null}
При помощи этого метода, можно сверять, какие пользователи передали вам свой ID через callback-адрес, а какие нет.

PushAll Auth

Основная проблема, которая стоит перед разработчиком, которому нужно реализовать индивидуальные уведомления - как узнать, какой пользователь на сайте, соответствует пользователю в PushAll? Ведь для работы нужен ID пользователя в PushAll, а уведомления надо слать пользователю внешней системы.
Для этого и нужен Callback-адрес. Вам необходимо написать обработчик переходов пользователей, и прописать Callback-адрес на этот обработчик.
Вы даже можете использовать PushAll для аутентификации пользователя на вашем сайте без использования каких-либо других социальных сетей.

Алгоритм связи таков:
  1. Пользователь переходит из личного кабинета вашего сайта по кнопке "Подписаться на Push-уведомления" (по ссылке вашего канала)
  2. Пользователь подписывается на канал
  3. Сразу же после этого его редиректит обратно на ваш сайт по Callback-адресу
  4. Вы обрабатываете GET-параметры, и используя уже существующую на вашей стороне авторизацию по сессии записываете PushAll ID в профиль вашего пользователя.
Вам придут GET-параметры:
pushalluserid=ID&time=UNIXTIME&sign=ПОДПИСЬ
pushalluserid - ID пользователя
Для проверки подписи используйте md5($key.$pushalluserid.$time.$ipAddress).
Где ipAddress: $ipAddress = $_SERVER['REMOTE_ADDR'];
Где $key - ключ вашего канала. Где $time - UNIXTIME.
Вы можете сами установить необходимый уровень проверки, к примеру после проверки времени и IP считать ключ валидным 1 минуту.
Данные поля проверки необходимы, чтобы невозможно было передать чужие данные через редирект в другого сайта.

Также есть вариант с OAuth-подобной аутентификацией. Включите переключатель OAuth и вы получите code
Далее вам нужно сделать API-запрос:
POST/GET: https://pushall.ru/api.php?type=oauth&code=CODE&client_id=ID_КАНАЛА&client_secret=КЛЮЧ_КАНАЛА
Вы также можете передавать привычные id и key – скрипт понимает и то и другое.

Вам вернется JSON — {"access_token":"1"}
Где 1 — ID пользователя.

CODE живет всего 5 минут, его нужно успеть передать за это время. Он одноразовый – то есть получить по нему еще раз ID не получится. По-хорошему вам стоит указывать в Callback URL промежуточную страницу, которая будет обрабатывать CODE и аутентифицировать пользователя по принятому ID, и далее переходить уже на сам сайт.

Используя ссылку pushall.ru/sign.php?subid=ID_КАНАЛА можно аутентифицировать пользователя в один клик, если он уже подписан на ваш канал. Эта ссылка сейчас доступна только для публичных каналов.

Получив ID пользователя в PushAll, вы можете использовать его для Multicast API и Unicast API

О документации

Данная документация будет дополняться и обновляться, о обновлениях будут приходить оповещения через новостной канал.

История обновления документации:
- 17 апреля 2016 Создание первой предварительной версии документации.
- 05 мая 2016 Добавлена информация про filter
- 19 июня 2016 Добавлена документация по Callback-адресу
- 5 февраля 2017 PushAll Auth
- 18 февраля 2018 Улучшили оформление документации, описание полей, поправили описание Rich Notifications



Почитать другие статьи
Подробнее

Необычное свойство Push-уведомлений - время жизни.
События проходят и теряют свою актуальность. Письмо, которое вы отправили человеку, сообщающее о новой акции не имеет смысла после конца акции. Как поступить? Пуш-уведомления умеют "умирать", когда в них больше нет необходимости.
Почитать другие статьи

Как создать новый канал Push-уведомлений?
Мы уже разобрались что такое push-уведомления и какие они бывают в браузерах и на мобильных платформах. Но как создать канал push-уведомлений в сервисе PushAll?
Почитать другие статьи

Как отключить push-уведомления от сайтов в браузере
Начали всплывать оповещения на экране? Надоели запросы на включение push-уведомлений в браузере на всех сайтах? В этой статье мы научимся отключать уже включенные оповещения, а также выключать функции оповещений в браузере раз и навсегда!
Почитать другие статьи

Что такое PUSH уведомления?
Push уведомления - это небольшие всплывающие окна на экране вашего устройства. Они могут появляться на экране любого устройства, где есть область оповещений, или есть возможность вывода на экран данных принятых из сети Интернет.
Почитать другие статьи