Webim Cordova Plugin

Webim Cordova Plugin служит для интеграции функций чата Webim в мобильные приложения Android и iOS, написанные на единой платформе Apache Cordova.

Актуальная версия плагина: 1.0, выпущена 04.04.2019

Оглавление

Установка
Список методов

метод init

метод requestDialog

метод getMessagesHistory

метод typingMessage

метод sendMessage

метод sendFile

метод onMessage

метод onFile

метод onTyping

метод onConfirm

метод onDialog

метод onBan

метод close

Список объектов

объект Message

объект DialogState

объект Employee

Заключение

УСТАНОВКА

Исходный код плагина размещён на GitHub.

Для использования плагина в вашем приложении необходимо подключить плагин специальной командой в корне проекта.
Например:

cordova plugin add https://github.com/webim/webim-cordova-plugin.git

Список методов

С тем, как вызывать методы плагина, можно ознакомиться в Cordova Plugin Development Guide.

метод webimsdk.init(param, successCallback, errorCallback)

Метод используется для инициализации сессии Webim. Без вызова этого метода невозможны вызовы остальных методов.

Параметр param — JSON со следующими полями:

Поле accountName — название аккаунта клиента в системе Webim. Обычно представляет из себя URL-сервера (например, https://demo.webim.ru), но может иметь и вид названия аккаунта одним словом (например, «demo»), если сервер находится в домене webim.ru. Тип параметра  String. Без этого параметра метод исполнится с ошибкой.

Поле location  размещение внутри сервиса Webim, которое будет использоваться при чате. Тип параметра  String. Скорее всего, сразу же можно использовать значения «mobile» и/или «default». Для создания и дальнейшего использования дополнительных размещений необходимо связаться со службой поддержки сервиса Webim. Без этого поля будет использовано размещение «mobile».

Поле visitorFields  поля авторизационных данных пользователя, тип  JSON. Подробную информацию об этих полях (включая, какие из них являются обязательными, и как необходимо их формировать) можно почерпнуть в Базе знаний Webim. Все данные авторизованного пользователя сохраняются и будут доступны при авторизации с любого устройства. Без этого поля при создании сессии, пользователь будет анонимным, со случайным образом сгенерированным ID. Этот ID сохраняется в настройках приложения, и в случае потери этих настроек (например, при переустановке приложения), копия данных на устройстве, включая историю сообщений, будут удалены (но всегда останутся на сервере и смогут быть скачаны повторно).

Функция successCallback(jsonString) исполняется при успешном завершении работы метода. Параметр jsonString содержит поле result с информацией о завершении исполнения метода.

Функция errorCallback(jsonString) исполняется при неуспешном завершении работы метода. Параметр jsonString содержит поле result с информацией о завершении исполнения метода.

метод webimsdk.requestDialog(successCallback, errorCallback)

Метод начинает чат. При отправке сообщения или файла пользователем чат начинается автоматически, поэтому вызов метода не является обязательным. Но, если настройки аккаунта предусматривают приветственные сообщения, до начала чата приветственные сообщения получены не будут.

Функция successCallback(jsonString) исполняется при успешном завершении работы метода. Параметр jsonString содержит поле result с информацией о завершении исполнения метода.

Функция errorCallback(jsonString) исполняется при неуспешном завершении работы метода. Параметр jsonString содержит поле result с информацией о завершении исполнения метода.

метод webimsdk.getMessagesHistory(limit, offset, succesCallback, errorCallback)

Метод используется для запроса сообщений из истории сообщений, которая еще не отображается в текущей ленте сообщений.

Параметр limit  количество следующих сообщений, не более которого должен запросить метод. Тип  Int, значение может быть любым положительным больше 1 (если передано значение меньше 1, метод не выполнит никакой работы).

Параметр offset — признак начала истории. Тип  Int, значение 0 показывает, что историю нужно показывать с последнего отправленного сообщения, другие значения означают, что метод продолжает загружать историю с момента, на котором остановился прошлый вызов метода.

Функция successCallback(messages) исполняется при успешном завершении работы метода. Параметр messages содержит массив объектов типа Message.

Функция errorCallback(jsonString) исполняется при неуспешном завершении работы метода. Параметр jsonString содержит поле result с информацией о завершении исполнения метода.

метод webimsdk.typingMessage(message, successCallback, errorCallback)

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

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

Параметр message  сообщение, которое уже ввел посетитель в соответствующее поле, но не отправил его. Тип  String, передача пустой строки в качестве параметра соответствует ситуации, когда посетитель прекратил ввод сообщения либо стер написанное из поля ввода.

Функция successCallback(text) исполняется при успешном завершении работы метода. Параметр text  текст печатаемого сообщения Тип — String.

Функция errorCallback(jsonString) исполняется при неуспешном завершении работы метода. Параметр jsonString содержит поле result с информацией о завершении исполнения метода.

метод webimsdk.sendMessage(message, successCallback, errorCallback)

Метод используется для отправки сообщения посетителя в сервис Webim.

Параметр message  отправляемое сообщение. Тип  String. Максимальная длина сообщения  32000 символов. Более длинные сообщения будут обрезаны сервером при их получении.

Функция successCallback(message) исполняется при успешном завершении работы метода. Параметр message содержит объект типа Message c отправленным сообщением.

Функция errorCallback(jsonString) исполняется при неуспешном завершении работы метода. Параметр jsonString содержит поле result с информацией о завершении исполнения метода.

метод webimsdk.sendFile(filePath, successCallback, errorCallback)

Метод используется для отправки файла от посетителя оператору.

Параметр filePath  путь к файлу на устройстве.

Функция successCallback(id) исполняется при получении сервером файла. Параметр id — идентификационный номер сообщения. Тип — String.

Функция errorCallback(jsonString) исполняется при неуспешном завершении работы метода. Параметр jsonString содержит поле result с информацией о завершении исполнения метода.

метод webimsdk.onMessage(successCallback, errorCallback)

Метод, который отслеживает события прихода новых сообщений от оператора, служебных сообщений или начала отправки сообщения посетителем.

Функция successCallback(message) исполняется при успешном завершении работы метода. Параметр message содержит объект типа Message.

Функция errorCallback() никогда не исполняется.

метод webimsdk.onFile(successCallback, errorCallback)

Метод, который отслеживает события прихода файловых сообщений.

Функция successCallback(message) исполняется при успешном завершении работы метода. Параметр message содержит объект типа Message.

Функция errorCallback() никогда не исполняется.

метод webimsdk.onTyping(successCallback, errorCallback)

Метод, который отслеживает событие, при котором оператор печатает сообщение.

Функция successCallback(message) исполняется при успешном завершении работы метода. Параметр message содержит пустую строку.

Функция errorCallback() никогда не исполняется.

метод webimsdk.onConfirm(successCallback, errorCallback)

Метод, который отслеживает событие получения сервером сообщения посетителя.

Метод, который отслеживает события прихода новых сообщений от оператора, служебных сообщений или начала отправки сообщения посетителем.

Функция successCallback(id) исполняется при успешном завершении работы метода. Параметр id содержит идентификационный номер сообщения, полученного сервером. Тип — String.

Функция errorCallback() никогда не исполняется.

метод webimsdk.onDialog(successCallback, errorCallback)

Метод, который отслеживает событие смены оператора.

Функция successCallback(dialogState) исполняется при успешном завершении работы метода. Параметр dialogState содержит объект типа DialogState с новым оператором.

Функция errorCallback() никогда не исполняется.

метод webimsdk.onBan(successCallback, errorCallback)

Метод, который реагирует на попытку инициализации сессии посетителем, который заблокирован на сервере.

Функция successCallback(jsonString) исполняется, если посетитель заблокирован. Параметр jsonString — сообщение о том, что посетитель заблокирован. Тип — String.

Функция errorCallback() никогда не исполняется.

метод webimsdk.close(succesCallback, errorCallback)

Метод, который останавливает сетевую активность.

Функция successCallback(jsonString) исполняется при успешном завершении работы метода. Параметр jsonString содержит поле result с информацией о завершении исполнения метода.

Функция errorCallback(jsonString) исполняется при неуспешном завершении работы метода. Параметр jsonString содержит поле result с информацией о завершении исполнения метода.

Список объектов

объект Message

Объект содержит информацию о сообщении.

Поле id — уникальный идентификационный номер сообщения. Тип — String.

Поле text — текст сообщения. Тип — String.

Поле url — ссылка на файл. Поле присутствует только у файловых сообщений. Тип — String.

Поле timestamp — время отправки сообщения в миллисекундах . Тип — String.

Поле sender — имя отправителя сообщения. Если сообщение системное, то поле отсутствует. Тип — String.

Поле operator — объект оператора. Если сообщение написано не оператором, то поле отсутствует. Тип — Employee.

объект DialogState

Объект содержит информацию о новом операторе чата. Для отслеживания смены оператора необходимо использовать метод onDialog.

Поле employee — новый оператор текущего чат. Тип — Employee.

объект Employee

Объект содержит информацию об операторе.

Поле id — уникальный идентификационный номер оператора. Тип — String.

Поле firstname имя оператора. Тип — String.

Поле avatar — ссылка на аватар оператора. Тип — String.

Заключение

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