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

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

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

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

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

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

N.B.

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

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

Push-уведомления на Android отправляются через API Firebase Cloud Messaging (FCM).

C июня 2024 года Google прекращает поддержку устаревшего FCM Legacy HTTP Server Protocol в пользу актуального FCM HTTP v1 API.

Основные изменения:

Смена эндпоинта

Старый эндпоинт: https://fcm.googleapis.com/fcm/send

Новый эндпоинт: https://fcm.googleapis.com/v1/projects/{project_id}/messages:send

Где {project_id} — это ID вашего проекта.
Токен авторизации

Теперь для авторизации серверного кода при отправке сообщений через FCM API v1 требуется использовать ключи доступа OAuth2 вместо Server key.

Чтобы настроить отправку push-уведомлений через Firebase Cloud Messaging API, выполните следующие шаги:

Авторизуйтесь в аккаунте Google.
Перейдите на портал Firebase.
Выберите необходимый проект, а если его нет, создайте его (нажав Add Project и выполнив несложные действия по инструкции, отображаемой на экране) и добавьте в него ваше Android-приложение.
Перейдите в консоль Firebase и откройте Settings > Service Accounts.
Нажмите Generate New Private Key и подтвердите создание ключа. Ключ будет сохранен на вашем устройстве в формате JSON.
Для отправки push-уведомлений операторам храните JSON-файл, содержащий private key, по следующему пути: /etc/webim/fcm/service-accounts/<любое название>.json.
Для отправки push-уведомлений посетителям храните JSON-файл, содержащий private key, по следующему пути: <client-data-dir>/<account_name>/fcm/service-accounts/<любое название>.json, где client-data-dir - путь, указанный в конфигурационном файле main.ini, а account_name - название вашего аккаунта.
Внесите ID Firebase-проекта, в котором зарегистрировано МП оператора, в параметр fcm_agent_project_id, расположенный в main.ini (для отправки push-уведомлений операторам), или оставьте пустым, если МП оператора не планируется использовать.
Внесите ID Firebase-проекта, в котором зарегистрировано МП посетителя (клиентское мобильное приложение), в параметр fcm_project_id, расположенный в настройках аккаунта (для отправки push-уведомлений посетителям), или оставьте пустым, если МП посетителя не планируется использовать. ID проектов можно найти в JSON-файле в поле project-id.

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

Push-уведомления на iOS отправляются через Apple Push Notification service (APNs).

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

N.B.

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

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

Выполните вход в Apple Developer Center и выберите раздел Identifiers, затем нажмите на кнопку со значком плюса.
Выберите App IDs и нажмите Continue.
Заполните форму нового App ID: введите Description (описание) вашего App ID, в поле Bundle ID выберите Explicit и укажите в строке ввода Bundle ID в виде обратного доменного имени, например com.push.webim.test (т.е. test.webim.push.com в обратном порядке).
На этой же странице в списке Capabilities отметьте функциональность, которую вы реализуете в вашем приложении, а также Push Notifications, затем нажмите Continue.

N.B.

Убедитесь, что вы создали App ID без подстановочного знака. Для идентификаторов с подстановочным знаком нельзя использовать службу push-уведомлений. Не путайте App ID и Bundle ID: Bundle ID имеет вид com.company.appname и определён в info.plist.
Подтвердите настройки App ID, нажав Register.
Вернитесь в раздел Identifiers и выберите только что созданный вами App ID.
Прокрутите до Push Notifications и нажмите Configure.
В секции Development SSL Certificate нажмите Create Certificate.

Далее откроется форма создания сертификата. Для создания сертификата потребуется CSR-файл, сгенерированный на вашем устройстве Mac.
Откройте на Mac сервис Keychain Access. В шапке приложения (полоска сверху) нажмите Keychain Access и перейдите в Create Assistant -> Request a Certificate From a Certificate Authority.
В окне информации о сертификате заполните форму, указав ваш Email и имя. Выберите сохранение на диске и нажмите Continue. CSR-файл будет создан и сохранён на устройстве Mac.
Вернитесь на открытую страницу Apple Developer Center. В форме создания сертификата нажмите Choose File и загрузите с устройства созданный CSR-файл. Нажмите Continue.
Далее появится страница, где будет отображена информация о новом APNs-сертификате (имя сертификата, дата окончания действия, тип сертификата и информация о создателе сертификата). Нажмите Download, чтобы загрузить его
Откройте Keychain Access в разделе Login -> Certificates появится только что загруженный APNs-сертификат. Выберите его и нажмите Export.
В форме экспорта укажите формат .p12.
Нажмите Save. Далее Mac OS попросит вас подтвердить сохранение: в первой форме просто нажмите Enter, в следующей введите ваш пароль администратора и нажмите Allow.

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

Внимание!

В систему можно загрузить сертификаты обоих типов, одновременно может быть включен только один тип уведомлений: либо dist, либо dev.

N.B.

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

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

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

Для получения push-уведомлений на устройства Huawei используется система Huawei Push Kit.

Перейдите на сайт Huawei Developer и создайте аккаунт разработчика. Для верификации потребуется паспорт, а сам процесс может занять до 3 дней.
Перейдите в раздел AppGallery Connect
Затем перейдите в Мои проекты
Создайте новый проект или выберите существующий
Добавьте ваше приложение в проект, указав необходимые данные (название, пакет и т.д.)
В проекте AppGallery Connect перейдите на вкладку Project Settings, выберите Push Kit и включите его, следуя инструкциям на экране:
Затем перейдите в настройки, в месте хранения данных выберите "Россия"
В настройках проекта создайте новое приложение:
После прохождения всех этапов и добавления pushkit в мобильное приложение, появится поля с OAuth 2.0

Для отправки уведомлений посетителю пропишите ID клиента и секрет клиента в account-config в строке huawei_push_kit_settings.

Для отправки уведомлений оператору пропишите те же данные в main.ini в строках hpk_agent_client_id и hpk_agent_secret_key.

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

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

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

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

Откройте страницу вашего проекта в Firebase.
Рядом с уже созданным приложением нажмите кнопку Add app.
Выберите платформу Android.

N.B.

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

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

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

Создайте файлы cert и private_key из файла p12 (для production и sandbox должны быть сгенерированы отдельные ключи, первые параметры dist или dev соответственно) с помощью следующего скрипта:

prepare_cert.sh
```
if ! (test "$1" == "dist" || test "$1" == "dev")
then
echo 'First argument must be dev or dist'
echo 'Example: prepare_certs.sh dist 1.p12 password'
exit 0
fi
openssl pkcs12 -in $2 -passin pass:"$3" -clcerts -nokeys -out ios_push_cert.$1.pem
openssl pkcs12 -in $2 -passin pass:"$3" -nocerts -out privateKey.pem -passout pass:"12345"
openssl rsa -in privateKey.pem -passin pass:"12345" -out ios_push_private_key.$1.pem
rm privateKey.pem
```
У вас должны получиться файлы следующего вида:
- ios_push_cert.dist.pem и ios_push_private_key.dist.pem для production-сертификата
- ios_push_cert.dev.pem и ios_push_private_key.dev.pem для sandbox-сертификата
Зайдите на сервер приложений Webim, перейдите в директорию /var/pro/client-data/cd/'account_name'/ios-certs/ и создайте в ней поддиректорию с названием 'new-app', где 'new-app' – это название нового приложения. Название должно быть задано латинскими буквами без пробелов и других знаков, например, myapp.
Поместите сертификат в созданную вами директорию.
Создайте пользователя и выдайте ему права для использования директории и файлов с сертификатом, чтобы Chat Backend мог иметь к ним доступ.
Push-токены должны приходить в формате 'new-app'_'token'. Пример push-токена может выглядеть так: myapp_1a6f32014a1a6f32014a1a6f32014a1a6f32014a1a6f32014a

Проксирование 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`	Представление типа `JSON` (см. message)	`message={ "kind": "operator", "clientSideId": "03ef89e10352b87809e67f74504c4bb6", "name": "Никита К", "avatar": "/webim/images/avatar/wmtest2_181510.png", "text": "1232", "ts": 1.531582962567873E9 }`	Сообщение push-уведомления. Обязателен, если `type` – `P.OM`, `P.OF`, `P.CR`.
`params`	`Array`	`["Никита К","1232"]`	Параметры push-уведомления. Обязателен, если `type` – `P.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.RO означает, что необходимо оценить оператора.
P.WM означает, что оператор прислал виджет (для включения данной функциональности необходимо обратиться в службу поддержки).

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

Для P.CR – массив пустой.
Для P.OA – массив из одного элемента: имя оператора.
Для P.OF – массив из двух элементов: имя оператора, название файла.
Для P.OM – массив из двух элементов: имя оператора, текст сообщения.
Для P.RO – массив пустой.
Для P.WM – массив содержит информацию о виджете (для включения данной функциональности необходимо обратиться в службу поддержки).

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

Возможные значения параметра 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`	`Boolean`	`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`	Размер файла в байтах.

image

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

size

Название параметра	Тип	Пример	Описание
`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
}

N.B.

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

Пример для Huawei Push Kit

Пример push-уведомления для Huawei может выглядеть следующим образом:

{
    "validate_only": false,
    "token": "токен",
    "data": {
        "pushtype": 1,
        "pushbody": Стандартное тело для push-уведомления Android
    } 
}