Webim Cordova Plugin

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

Установка

Исходный код плагина размещён на 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.

Поле pushToken — поле типа String, в котором содержится значение push-токена для получения push-уведомлений.

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

Поле storeHistoryLocally. По умолчанию сессия не сохраняет историю сообщений внтури файла БД SQLite. Чтобы активировать сохранение истории сообщений, полю нужно присвоить значение True. Тип - Boolean.

Поле closeWithClearVisitorData. Если этот параметр стоит в значении True, то сессия закроется с удалением данных пользователя. Тип - Boolean.

Функция 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.sendSurveyAnswer(surveyAnswer, successCallback, errorCallback)

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

Параметр surveyAnswer - ответ на текущий вопрос.

Функция successCallback(jsonString) исполняется при успешном завершении исполнения метода.

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

webimsdk.surveyCancel(successCallback, errorCallback)

Закрывает опрос.

Функция successCallback(jsonString) исполняется при успешном завершении исполнения метода.

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

webimsdk.onMessage(successCallback, errorCallback)

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

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

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

webimsdk.onDeletedMessage(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.onSurvey(successCallback, errorCallback)

Метод, отслеживающий событие, когда пользователь может ответить в опросе.

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

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

webimsdk.onNextQuestion(successCallback, errorCallback)

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

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

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

webimsdk.onSurveyCancel(successCallback, errorCallback)

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

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

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

webimsdk.rateOperator(successCallback, errorCallback)

Метод для оценки оператора.

Параметр id — ID оператора. Тип — String.

Параметр rating — число в диапазоне от 1 до 5, отражающее оценку оператора. Если число находится вне диапазона, оно не будет отправлено на сервер. Тип — Int.

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

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

webimsdk.sendDialogToEmailAddress(emailAddress, successCallback, errorCallback)

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

Параметр emailAddress — адрес электронной почты, на который отправляется диалог. Тип — String.

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

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

webimsdk.onUnreadByVisitorMessage(successCallback, errorCallback)

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

Функция successCallback(unreadByVisitorMessageCount) исполняется, когда количество непрочитанных пользователем сообщений изменяется. Параметр unreadByVisitorMessageCount отражает количество непрочитанных пользователем сообщений. Тип - Int.

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

webimsdk.getUnreadByVisitorMessage(successCallback, errorCallback)

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

Функция successCallback(unreadByVisitorMessageCount) возвращает значение непрочитанных пользователем сообщений. Параметр unreadByVisitorMessageCount отражает количество непрочитанных пользователем сообщений. Тип - Int.

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

webimsdk.onLogging(successCallback, errorCallback)

Метод, отслеживающий появление новых записей в журнале логов.

Функция successCallback(log) возвращает новую запись в журнале логов. Параметр log содержит новую запись в журнале логов. Тип - 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.

Поле isFirst — принимает истинное значение, если сообщение первое в чате. Тип — Boolean.

DialogState

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

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

Employee

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

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

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

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

Survey

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

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

Поле config — конфигурация опроса. Тип — SurveyConfig.

Поле currentQuestionInfo — информация о текущем опросе в URL опроса. Тип — SurveyCurrentQuestionInfo.

SurveyConfig

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

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

Поле version — версия конфигурации опроса. Тип — String.

SurveyCurrrentQuestionInfo

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

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

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

SurveyQuestion

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

Поле type — тип опроса. Может быть stars, radio, comment. Тип — String.

Поле text — текстовое содержание вопроса. Тип — String.