Webim Cordova Plugin

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


Установка

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

Наверх



Заключение

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