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

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

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

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

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

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

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

    Где project_id — это ID вашего проекта.

  2. Токен авторизации

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

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

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

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

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

  4. Перейдите в консоль Firebase и откройте Settings > Service Accounts.

  5. Нажмите Generate New Private Key и подтвердите создание ключа. Ключ будет сохранен на вашем устройстве в формате JSON.

  6. Для отправки push-уведомлений операторам храните JSON-файл, содержащий private key, по следующему пути: /etc/webim/fcm/service-accounts/<любое название>.json.

  7. Для отправки push-уведомлений посетителям храните JSON-файл, содержащий private key, по следующему пути: <client-data-dir>/<account_name>/fcm/service-accounts/<любое название>.json, где client-data-dir - путь, указанный в конфигурационном файле main.ini, а account_name - название вашего аккаунта.

  8. Внесите ID Firebase-проекта, в котором зарегистрировано МП оператора, в параметр fcm_agent_project_id, расположенный в main.ini (для отправки push-уведомлений операторам), или оставьте пустым, если МП оператора не планируется использовать.

  9. Внесите 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 выполните следующие действия:

  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.

    N.B.

    Убедитесь, что вы создали 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.

Внимание!

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

N.B.

После создания сертификата(ов), также убедитесь, что в проекте вашего 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.

N.B.

  • В рамках проекта 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 Представление типа 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.