Перейти к содержанию

Push-уведомления

Webim поддерживает подключение push-уведомлений для устройств на базе Android и iOS. Для включения push-уведомлений необходимо предоставить сертификаты/приватные ключи Ваших мобильных приложений. Для этого свяжитесь, пожалуйста, с нашей службой поддержки. Push-уведомление приходит в формате JSON, который с помощью специальных методов можно преобразовать в объект WebimPushNotification/WebimRemoteNotification. Это можно делать как силами Вашего приложения, так и с помощью нашего Mobile SDK. Если Вы предпочитаете второй вариант, то Вам стоит ознакомиться с SDK для Android либо с SDK для iOS.

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

Для корректной настройки push-уведомлений необходимо передавать оригинальный токен без изменений.

Чтобы отписаться от push-уведомлений, в качестве токена нужно отправить значение none.

Также работу с push-уведомлениями можно посмотреть в коде демо-приложений.

NB

В версии 10.4 для APNs теперь отправка push-уведомлений осуществляется через 443 порт по протоколу HTTP версии 2.

Получение push-уведомлений на Android

Для Android используется система push-уведомлений FCM, и для подключения push-уведомлений нужно предоставить в техническую поддержку Webim полный FCM-ключ (около 150 символов). Для того, чтобы получить FCM API KEY, необходимый для отправки push-уведомлений в приложениях на базе Android, выполните ряд шагов:

  1. Авторизуйтесь в аккаунте Google.

  2. Перейдите на портал Firebase.

  3. Выберите необходимый проект, а если его нет, создайте его (нажав Add Project и выполнив несложные действия по инструкции, отображаемой на экране) и добавьте в него ваше Android-приложение.

  4. На странице проекта в меню слева нажмите на значок шестерёнки и выберите из выпадающего списка Project settings.

  5. Перейдите на вкладку Cloud Messaging и скопируйте токен из поля Server key.

Получение push-уведомлений на iOS

Для iOS используются сертификаты APNs двух типов: dev (нужен в процессе разработки) и dist (используется для стандартной работы приложения). Формат сертификата обязательно должен быть .p12.

NB

Для выполнения следующих действий требуется действительный аккаунт разработчика Apple, устройство Mac c Xcode и действительный сертификат разработчика, установленный в Цепочку ключей (Keychain).

Для получения сертификатов APNs выполните следующие действия:

  1. Выполните вход в Apple Developer Center и выберите раздел Identifiers, затем нажмите на кнопку со значком плюса.

  2. Выберите App IDs и нажмите Continue.

  3. Заполните форму нового App ID: введите Description (описание) вашего App ID, в поле Bundle ID выберите Explicit и укажите в строке ввода Bundle ID в виде обратного доменного имени, например com.push.webim.test (т.е. test.webim.push.com в обратном порядке).

  4. На этой же странице в списке Capabilities отметьте функционал, который вы реализуете в вашем приложении, а также Push Notifications, затем нажмите Continue.

    NB

    Убедитесь, что вы создали App ID без подстановочного знака. Для идентификаторов с подстановочным знаком нельзя использовать службу push-уведомлений. Не путайте App ID и Bundle ID: Bundle ID имеет вид com.company.appname и определён в info.plist.

  5. Подтвердите настройки App ID, нажав Register.

  6. Вернитесь в раздел Identifiers и выберите только что созданный вами App ID.

  7. Прокрутите до Push Notifications и нажмите Configure.

  8. В секции Development SSL Certificate нажмите Create Certificate.

    Далее откроется форма создания сертификата. Для создания сертификата потребуется CSR-файл, сгенерированный на вашем устройстве Mac.

  9. Откройте на Mac сервис Keychain Access. В шапке приложения (полоска сверху) нажмите Keychain Access и перейдите в Create Assistant -> Request a Certificate From a Certificate Authority.

  10. В окне информации о сертификате заполните форму, указав ваш email и имя. Выберите сохранение на диске и нажмите Continue. CSR-файл будет создан и сохранён на устройстве Mac.

  11. Вернитесь на открытую страницу Apple Developer Center. В форме создания сертификата нажмите Choose File и загрузите с устройства созданный CSR-файл. Нажмите Continue.

  12. Далее появится страница, где будет отображена информация о новом APNs-сертификате (имя сертификата, дата окончания действия, тип сертификата и информация о создателе сертификата). Нажмите Download, чтобы загрузить его

  13. Откройте Keychain Access в разделе Login -> Certificates появится только что загруженный APNs-сертификат. Выберите его и нажмите Export.

  14. В форме экспорта укажите формат .p12.

  15. Нажмите Save. Далее Mac OS попросит вас подтвердить сохранение: в первой форме просто нажмите Enter, в следующей введите ваш пароль администратора и нажмите Allow.

Чтобы создать production-сертификат для вашего iOS-приложения, выполните пункты 6-14 этой инструкции, но в пункте 8 нажмите Create Certificate в секции Production SSL Certificate.

NB

После создания сертификата(ов), также убедитесь, что в проекте вашего iOS-приложения в Xcode включено Automatic signing, а в разделе Capabilities вашего проекта включены push-уведомления.

В версии Webim 10.1 стало возможным добавлять сертификаты APNs через интерфейс Консоли управления (см. Сертификаты).

Подключение нескольких приложений

К одному аккаунту Webim может быть подключено несколько мобильных приложений (2 и более) как на Android, так и на iOS. Ниже описан порядок подключения дополнительных приложений.

Подключение нескольких Android-приложений

К одному проекту Firebase можно привязать несколько Android-приложений. Так как ключ FCM API KEY относится к проекту в целом, то все приложения, добавленные в проект, смогу получать push-уведомления по этому ключу. Чтобы привязать дополнительные Android-приложения, достаточно выполнить следующее:

  1. Откройте страницу вашего проекта в Firebase.

  2. Рядом с уже созданным приложением нажмите кнопку Add app.

  3. Выберите платформу Android.

NB

  • В рамках проекта Firebase можно добавить приложение в том числе и на платформе iOS, но в этом случае push-уведомления не будут приходить на устройства, где установлено такое приложение, так как сервис Webim не поддерживает данную функциональность.

  • Все Android-приложения, которые подключены к одному аккаунту Webim, должны быть привязаны к одному проекту в Firebase. Получение push-уведомлений на приложения, привязанные к разным проектам Firebase, не предусмотрено.

Подключение нескольких iOS-приложений

Для подключения дополнительных iOS-приложений в Apple Developer Center требуется создать новый App ID и получить сертификаты APNs в формате .p12 (см. инструкцию) для каждого дополнительного приложения, после чего обратиться в техническую поддержку и предоставить эти сертификаты. Далее сотрудники Webim с помощью этих сертификатов настроят отправку push-уведомлений для всех дополнительно привязанных приложений на вашем аккаунте.

Проксирование push-уведомлений

Начиная с версии 10.4, в Webim имеется возможность проксирования отправляемых push-уведомлений. Чтобы включить проксирование, необходимо обратиться в техническую поддержку Webim (для облачных клиентов) или настроить параметр proxies, содержащийся в редакторе настроек аккаунта (account config) (для hosted-клиентов). В обоих случаях требуется предоставить/указать следующие параметры для подключения к прокси-серверу, через который будет осуществляться отправка push-уведомлений:

Параметр Описание
host IP-адрес прокси-сервера, например 127.0.0.1.
port Порт подключения к серверу, например 3128.
user Имя пользователя, например user1.
password Пароль пользователя, например P@ssw0rd.

Параметры push-уведомлений

Для автоматической обработки и отображения push-уведомлений Ваше приложение должно быть осведомлено о возможных типах уведомлений и об аргументах, присылаемых в этих уведомлениях. Звёздочкой отмечены названия обязательных параметров.

Типы данных

Тип Описание
Double Вещественный тип числа.
Long/Int Целочисленный тип.
String Строковый тип.
Enum Значение из списка возможных (строковый тип).
Array<*> Список значений (массив).

Уведомление

Название параметра Тип Пример Описание
type* Enum P.OM Тип push-уведомления.

Возможные значения:

P.OM, P.OF, P.CR, P.OA, P.WM
event* Enum add Действие push-уведомления.

Возможные значения:

add, del
message Message См. описание объекта Message. Сообщение push-уведомления.

Обязателен, если typeP.OM, P.OF, P.CR.
params Array ["Никита К","1232"] Параметры push-уведомления.

Обязателен, если typeP.OA, P.OM, P.OF:
  • Для P.OA – массив из одного элемента: имя оператора
  • Для P.OF – массив из двух элементов: имя оператора, название файла
  • Для P.OM – массив из двух элементов: имя оператора, текст сообщения

Возможные значения параметра loc-key (iOS) и type (Android):

  • P.CR означает, что оператор прислал запрос контактных данных.

  • P.OA означает, что оператор взял чат в обработку.

  • P.OF означает, что оператор прислал файл..=

  • P.OM означает, что оператор прислал сообщение.

  • P.WM означает, что оператор прислал виджет (для поддержки данного функционала необходимо обратиться в службу поддержки).

Значения массива аргументов — параметр loc-args (iOS) и params (Android):

  • Для P.CR – массив пустой.

  • Для P.OA – массив из одного элемента: имя оператора.

  • Для P.OF – массив из двух элементов: имя оператора, название файла.

  • Для P.OM – массив из двух элементов: имя оператора, текст сообщения.

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

Возможные значения параметра event (Android)

  • add – push-уведомление необходимо показать

  • del – push-уведомление необходимо удалить

Если push-уведомление имеет тип P.OF или P.OM, то параметр message содержит в себе сообщение, в ином случае этого параметра нет.

Message

Название параметра Тип Пример Описание
name* String Никита К Имя автора сообщения.
avatar* String /webim/images/avatar/wmtest2_181510.png URL аватара автора сообщения.
kind* Enum operator Тип сообщения.

Возможные типы: operator, file_operator, cont_req.
clientSideId* String 03ef89e10352b87809e67f74504c4bb6 ID сообщения.
ts* Double 1.531582962567873E9 Время сообщения в микросекундах.
text* String Текст сообщения Текст сообщения или строковое представление формата JSON с файлом, сериализованное в строку.

text

kind Тип Пример Описание
operator String Здравствуйте, чем я могу Вам помочь? Текстовое сообщение оператора.
file_operator String См. описание параметра Сообщение с файлом от оператора, содержащее сериализированный JSON.
cont_req String Введите, пожалуйста, Вашу контактную информацию. Сообщение с запросом контактной информации.

file_operator

Параметр Тип Пример Описание
is_voice Booleam False Параметр, указывающий является ли сообщение голосовым.
client_content_type String image/jpeg Content type файла, указанный при отправке фронтэндом.
image.size.width Int 1125 Ширина изображения в пикселях.
image.size.length Int 2000 Высота изображения в пикселях.
visitor_id String fbd431f77834ba107b120cfa07fec70d Идентификатор посетителя в guid-формате.
filename String 3_(3).jpg Название файла.
content-type String image/jpeg Content type файла, распознанный при анализе файла.
guid String 4bfc1ae213b84cd586abc2c787b87a8e Идентификатор файла.
size Int 176001 Размер файла в байтах.

ImageItem

Название параметра Тип Пример Описание
size* ImageSizeItem {"width": 300, "height": 300} Размеры превью изображения.

ImageSizeItem

Название параметра Тип Пример Описание
width* Int 300 Ширина превью изображения.
height* Int 300 Высота превью изображения.

В уведомлениях в iOS используются в основном те же параметры. Среди специфических для этой платформы упомянем:

Название параметра Тип Пример Описание
loc-key* String P.OM Тип уведомления.
loc-args Array Массив с параметрами (см. выше). Параметры push-уведомления.

Обязателен, если type – P.OA, P.OM, P.OF:
  • Для P.OA – массив из одного элемента: имя оператора
  • Для P.OF – массив из двух элементов: имя оператора, название файла
  • Для P.OM – массив из двух элементов: имя оператора, текст сообщения
sound String default Звук уведомления.
webim* Int 1 Параметр для идентификации приложения. Всегда равен 1.

Примеры для FCM Android

Оператор взял чат в обработку:

{params=["Никита К"], type=P.OA, event=add}

Пришло сообщение:

{
            params=[
                "Никита К",
                "1232"
            ],
            type=P.OM,
            event=add,
            message={
                "kind": "operator",
                "clientSideId": "03ef89e10352b87809e67f74504c4bb6",
                "name": "Никита К",
                "avatar": "/webim/images/avatar/wmtest2_181510.png",
                "text": "1232",
                "ts": 1.531582962567873E9
            }
}

Пришёл файл:

{
            params=   [
                "Никита К",
                "p.jpg"
            ],
            type=P.OF,
            event=add,
            message=   {
                "kind": "file_operator",
                "clientSideId": "a49529502be8482ba9134756c4a4a211",
                "name": "Никита К",
                "avatar": "/webim/images/avatar/wmtest2_181510.png",
                "text": {
                    "client_content_type": "image/jpeg",
                    "image": {
                        "size": {
                        "width": 300,
                        "height": 300
                        }
                    },
                    "visitor_id": "1b0c5d865529418a91f728c525b6d9fd",
                    "filename": "p.jpg",
                    "content_type": "image/jpeg",
                    "guid": "ac741895c19a47078bc54f722951957f",
                    "size": 53323
                },
                "ts": 1.531584932619524E9
            }
}

Оператор запросил контактные данные:

{
            params=[

            ],
            type=P.CR,
            event=add,
            message={
                "kind": "cont_req",
                "clientSideId": "525a9cd6c49a46de90ca4c9016681b56",
                "name": "Никита К",
                "avatar": "/webim/images/avatar/wmtest2_181510.png",
                "text": "Please enter your contact information.",
                "ts": 1.531584937099446E9
            }
}

Пример для APNs iOS

Пример push-уведомления для iOS:

{
        "aps": {
            "alert": {
                "loc-key": "P.OM",
                "loc-args": ["Имя Оператора", "Сообщение"]
            },
            "sound": "default",
        },
        "webim": 1
}

NB

В зависимости от типа сообщения, в коде push-уведомления для iOS изменяются только значения loc-key и loc-args.