Current version 0.1.0

Push Expert – сервис для рассылки браузерных уведомлений. С помощью Push Expert вы сможете легко добавить возможность отправки нотификаций в браузеры пользователей на свой ресурс, что позволит вам проводить таргетированные рассылки посетителям, оперативно реагировать на обращения клиентов и многое другое.

Мы предлагаем вам следующие варианты интеграции Push Expert на ваш ресурс:

  • Самый простой способ – внедрение сервиса Push Expert с помощью кода интеграции. Вам нужно всего лишь добавить код сервиса в шаблон сайта и вы получите доступ к базовому функционалу Push Expert. Если у вашей компании есть сообщества в социальных сетях, то вы можете воспользоваться этим способом интеграции;
  • Продвинутый способ – использование Website SDK Push Expert. Этот метод позволит вам самим управлять показами запросов на получение уведомлений в браузерах, а также присваивать зарегистрированным пользователям теги для дальнейших рассылок;
  • Универсальный способ – полная интеграция Server API Push Expert с вашим ресурсом. Таким образом, вы сможете автоматически уведомлять клиентов вашего интернет-магазина об изменении статуса заказа, избирательно рассылать уведомления о событиях, которые будут интересны определенному кругу ваших пользователей, или рекламные предложения, а также многое другое.

В качестве основного домена, можно выбрать из списка: "push.expert", "push.report" или "push.community". Данный домен отображается в уведомлениях и используется во всех ссылках для кода интеграции.

Установка уведомлений к себе на сайт

Установите этот код в любое место HTML-кода на странице вашего сайта.

<script>
    !function(p,u,s,h,m,e){p.__cmbk=p.__cmbk||function(){(p.__cmbk.q=p.__cmbk.q||[]).push(arguments)};m=u.createElement(s);e=u.getElementsByTagName(s)[0];m.async=!0;m.src=h;e.parentNode.insertBefore(m,e);}(window,document,'script','//https://<your-project-domain>.push.expert/js/integration.js');
    </script>

Прямая ссылка на страницу подписки на уведомления

Данный вариант будет полезен для сообществ в социальных сетях. Просто прикрепите эту ссылку к вашей группе:

https://<your-project-domain>.%DOMAIN%

После установки Website SDK Push Expert на своём веб-ресурсе вы получите следующие дополнительные возможности:

  • Привязать браузер пользователя к некоторому тегу;
  • Привязать несколько браузеров к одному пользователю;
  • Настроить показ запросов о подписке на уведомления для групп пользователей;
  • Получить токен, который можно использовать непосредственно в Server API.

Пример

<script>
    !function(p,u,s,h,m,e){p.__cmbk=p.__cmbk||function(){(p.__cmbk.q=p.__cmbk.q
    || []).push(arguments)};m=u.createElement(s);e=u.getElementsByTagName(s)[0];m.async=!0;m.src=h;
    e.parentNode.insertBefore(m,e);}(window,document,'script','//<your project domain>.push.expert/js/integration.js');

    // назначить текущему токену тег(при регистрации)
    __cmbk('setRegistrationTag','test-users');
    // назначить userId текущему токену (при регистрации)
    __cmbk('setUser','yourInternalId');
    // получить текущий токен
    __cmbk('getToken', function (err, token) {
    if (!err) {console.log(token)            }
    });
    // отключить автоматический показ попапа
    __cmbk('disableAutoRender');
    // отобразить попап
    __cmbk('render');
    // изменить текст в реквесте на разрешение подписок
    __cmbk('setRequestMessage', 'Подключайте пуш-уведомления!');
    // настроить время(в секундах), через которое пользователь снова увидит запрос на показ уведомлений
    __cmbk('setCloseTimeout', 86400);
    // Доступны ли пуш-уведомления в текущем браузере
    __cmbk('availableInBrowser', function(err, isAvailable){
        if(isAvailable) {
          console.log('Push notifications are available');
        }
    });

    // подписка на события в попап-окне
    __cmbk('onEvent', eventType, cb);
    // поддерживаются события `subscription` и `popup.close`
    // - subscription
    __cmbk('onEvent', 'subscription', function(err, body){
        if(body.result) {
          console.log('Success, user hashToken', body.hashToken)
        } else {
          console.log('Error', body.error)
        }
    });
    // - popup
    __cmbk('onEvent', 'popup.close', function(err, body){
        //body = null
        console.log('popup closed');
    });


</script>

Взаимодействие с API

Вызов методов API Push Expert осуществляется при помощи POST-запросов по протоколу HTTPS на адрес: https://api.push.expert/v1/<method>/, при этом параметры авторизации и аргументы метода следует передать в теле запроса API-метода. Пример сURL-запроса:

curl --header "x-project-id: <<ВАШ ИДЕНТИФИКАТОР ПРОЕКТА>>" --header "x-secret-key: <<СЕКРЕТНЫЙ КЛЮЧ>>" --data '{}' https://api.push.expert/v1/<<apiMethod>>

В результате успешного вызова метода API будет получен ответ в формате JSON:

{
    "body":  null || {}                                // содержание body зависит от конкретного api-метода
    "error": null || {"type":string,"message":string}  // если в результате выполнения api-запроса произошла какая-то ошибка
}

Авторизационные данные можно получить в разделе "Ключ API" в панели администрирования:

api-key

Отправление PUSH-уведомлениия (push-send)

Для выполнения API-метода можно использовать запросы: https://api.push.expert/v1/pushSend/ или https://api.push.expert/v1/push-send/.

Аргументы

Название параметра Описание
target таргетирование по подписчикам
{
    "tags": [],    // отправить всем токенам и пользователям, кто привязан к определенным тегам
    "users": [],   // список пользователей (userId выших пользователей, которые вы регистрируете у нас в системе),
    "tokens": [],  // список токенов, которые можно получить с помощью website-sdk
}
                            
title Заголовок сообщения PUSH-уведомления.
message Текст сообщения, которое будет отображено в PUSH-уведомлении
url URL-адрес, куда необходимо переадресовать получателя после клика по уведомлению
sendTime Время, когда необходимо доставить сообщение в UNIX-формате (необязательный параметр)
ttl Время в секундах, сколько PUSH-уведомление будет отображаться (необязательный параметр)
expireTime Время в формате UnixTimestamp, начиная с которого уведомления перестанут доставляться (необязательный параметр)
displayTag Групповой тег push-уведомления, при использовании которого повторные уведомления будут заменяться последним отправленным (необязательный параметр)

В ответ будет возращен результат добавления очереди на отправление уведомления:

{
    "error": null,
    "body": {
        "result": false/true, // если результат отрицательный, то body будет содержать сообщение об ошибке в
        "message": string     // поле message
    }
}

Возможные ошибки:

Название ошибки Описание
EmptyTarget аргумент target не содержит ни одного из полей, или не указано ни одного токена,пользователя или тега.

Привязать теги к пользователю(user-set-tags)

Для выполнения API-метода можно использовать запросы: https://api.push.expert/v1/userSetTags/ или https://api.push.expert/v1/user-set-tags/.

Метод позволяет присваивать пользователям вашего веб-ресурса теги до разрешения получения уведомлений в браузере.

Аргументы

Название параметра Описание
tags Теги, к которым нужно привязать текущего пользователя.
userId Идентификатор пользователя на вашем web-ресурсе. Если указанный userId отсутствует в базе данных, то он будет автоматически добавлен.varchar[64]

При успешном вызове метода в ответе будет возращено кол-во привязанных тегов(повторный вызов вернет нулевой результат):

{
    "error": null,
    "body": {
        "updatedRows": int // кол-во привязанных тегов
    }
}

Отвязать теги от пользователя(user-unset-tags)

Для выполнения API-метода можно использовать запросы: https://api.push.expert/v1/userUnsetTags/ или https://api.push.expert/v1/user-unset-tags/.

Метод позволяет отвязать теги пользовтелей, которые были ранее привязаны.

Аргументы

Название параметра Описание
tags Теги, от которых нужно отвязать пользователя.
userId Идентификатор пользователя на вашем web-ресурсе. Если указанный userId отсутствует в базе данных, то он будет автоматически добавлен.varchar[64]

При успешном вызове метода в ответе будет возращено кол-во отвязанных тегов(повторный вызов вернет нулевой результат):

{
    "error": null,
    "body": {
        "updatedRows": int, // кол-во отвязанных тегов
        "affectedTags": array // список затронутых тегов
    }
}

Получить все теги пользователя(user-get-all-tags)

Для выполнения API-метода можно использовать запросы: https://api.push.expert/v1/userGetAllTags/ или https://api.push.expert/v1/user-get-all-tags/.

Метод позволяет получить все теги пользовтеля, которые были ранее привязаны.

Аргументы

Название параметра Описание
userId Идентификатор пользователя на вашем web-ресурсе. Если указанный userId отсутствует в базе данных, то он будет автоматически добавлен.varchar[64]

При успешном вызове метода в ответе будет возращен список тегов:

{
    "error": null,
    "body": {
        "tags": array // список тегов
    }
}

Отвязать все теги от пользователя(user-unset-all-tags)

Для выполнения API-метода можно использовать запросы: https://api.push.expert/v1/userUnsetAllTags/ или https://api.push.expert/v1/user-unset-all-tags/.

Метод позволяет отвязать теги пользовтелей, которые были ранее привязаны.

Аргументы

Название параметра Описание
userId Идентификатор пользователя на вашем web-ресурсе. Если указанный userId отсутствует в базе данных, то он будет автоматически добавлен.varchar[64]

При успешном вызове метода в ответе будет возращено кол-во отвязанных тегов(повторный вызов вернет нулевой результат):

{
    "error": null,
    "body": {
        "updatedRows": int, // кол-во отвязанных тегов
        "affectedTags": array // список затронутых тегов
    }
}

Привязать теги к токену (token-set-tags)

Для выполнения api-метода можно использовать запросы: https://api.push.expert/v1/tokenSetTags/ или https://api.push.expert/v1/token-set-tags/.

Рекомендуется использовать этот метод, если пользователь не зарегистрирован или у вас не поддерживаются учетные записи, в остальных случаях вам будет достаточно метода привязки пользователя к тегам.

Аргументы

Название параметра Описание
tags теги, к которым нужно привязать текущий браузер(токен)
token HASH-токен браузера, который можно получить при помощи website-sdk

При успешном вызове метода в ответе будет возращено кол-во привязанных тегов(если повторно вызвать метод, то результат будет 0):

{
    "error": null,
    "body": {
        "updatedRows": int // кол-во обновленных строк,
    }
}

Возможные ошибки:

Название ошибки Описание
TokenNotFound Токен, который был передан в аргументах не зарегестрирован в системе.

Получить все теги для токена (token-get-all-tags)

Для выполнения api-метода можно использовать запросы: https://api.push.expert/v1/tokenGetAllTags/ или https://api.push.expert/v1/token-get-all-tags/.

Аргументы

Название параметра Описание
token HASH-токен браузера, который можно получить при помощи website-sdk

При успешном вызове метода в ответе будет возращено список тегов:

{
    "error": null,
    "body": {
        "tags": array // список токенов, которые были отвязаны от токена
    }
}

Возможные ошибки:

Название ошибки Описание
TokenNotFound Токен, который был передан в аргументах не зарегестрирован в системе.

Отвязать теги от токена (token-unset-tags)

Для выполнения api-метода можно использовать запросы: https://api.push.expert/v1/tokenUnsetTags/ или https://api.push.expert/v1/token-unset-tags/.

Аргументы

Название параметра Описание
tags теги, от которых нужно отвязать токен
token HASH-токен браузера, который можно получить при помощи website-sdk

При успешном вызове метода в ответе будет возращено кол-во отвязанных токенов(повторный вызов метода вернет нулевой результат):

{
    "error": null,
    "body": {
        "updatedRows": int // кол-во отвязанных токенов,
        "affectedTags": array // список токенов, которые были отвязаны от токена
    }
}

Возможные ошибки:

Название ошибки Описание
TokenNotFound Токен, который был передан в аргументах не зарегестрирован в системе.

Отвязать все теги от токена (token-unset-all-tags)

Для выполнения api-метода можно использовать запросы: https://api.push.expert/v1/tokenUnsetAllTags/ или https://api.push.expert/v1/token-unset-all-tags/.

Аргументы

Название параметра Описание
token HASH-токен браузера, который можно получить при помощи website-sdk

При успешном вызове метода в ответе будет возращено кол-во отвязанных токенов(повторный вызов метода вернет нулевой результат):

{
    "error": null,
    "body": {
        "updatedRows": int // кол-во отвязанных токенов,
        "affectedTags": array // список токенов, которые были отвязаны от токена
    }
}

Возможные ошибки:

Название ошибки Описание
TokenNotFound Токен, который был передан в аргументах не зарегестрирован в системе.

Привязать пользователя к токену (user-set-token).

Для выполнения api-метода можно использовать запросы: https://api.push.expert/v1/userSetToken/ или https://api.push.expert/v1/user-set-token/.

Для привязки пользователя к токену чаще всего достаточно использовать Website SDK, но возможны ситуации, когда пользователь подписался на уведомления до регистрации, таким образом вам возможно потребуется привязать идентификатор пользователя(который будет создан вами при регистрации) к уже суещствующему токену. Привязка уже существующего токена через SDK не поддерживается, т.к. это не безопасно.

Аргументы

Название параметра Описание
token HASH-токен, который можно получить с помощью Website SDK
userId Идентификатор пользователя на вашем web-ресурсе. Если указанный userId отсутствует в базе данных, то он будет автоматически добавлен.

При успешном вызове метода в ответе будет возращен пустой результат:.

{
    "error": null,
    "body": {
        "result": true,
        "message": "success" || "already"
    }
}

Возможные ошибки:

Название ошибки Описание
TokenNotFound Токен, который был передан в аргументах не зарегестрирован в системе.