Webim Mobile SDK для интеграции в мобильные приложения Android

Оглавление

Установка
Пример приложения
Использование
Дополнительные возможности
Заключение

Установка

Информация о выпусках (Release notes)

SDK внедряется в приложение добавлением следующей зависимости в файл build.gradle проиложения:

compile 'com.webimapp.sdk:webimclientsdkandroid:3.+'

Также в приложении должно быть указано следующее разрешение в файле AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />

На экране чата внизу разместите надпись «Предоставлено: webim.ru», где webim.ru подчёркнуто и является кликабельной ссылкой на сайт Webim.

Пример приложения

Пример выложен на GitHub:

https://github.com/webim/webim-android-sdk-demo

Использование

WebimSession

Использование функционала библиотеки начинается с создания объекта сессии.

Метод класса Webim newSessionBuilder() возвращает объект класса-строителя SessionBuilder (оба класса и их методы описаны в файле Webim.java). После, на созданном объекте SessionBuilder вызываются методы, задающие параметры сессии. После задания всех необходимых параметров на этом объекте запускается метод build(), который возвращает объект WebimSession.

Типичный пример использования:

WebimSession webimSession = Webim.newSessionBuilder().setAccountName(«ACCOUNT_NAME»).setLocation(«LOCATION_NAME»).build()

Где ACCOUNT_NAME – название вашего аккаунта в системе Webim, а LOCATION_NAME – название локации, которую необходимо использовать в мобильном приложении.

Описание всех параметров, которые можно задать при создании сессии, а также ошибок, которые могут возникать в процессе, можно также найти в файле Webim.java. Обязательными из них являются только два – имя аккаунта и размещение.

После создании сессии, ее необходимо запустить методом resume() (т.к. объект сессии изначально создается приостановленным).

При необходимости сессию можно приостанавливать (метод pause()) и возобновлять (метод resume()), а также уничтожать (метод destroy()) – все эти методы описаны в файле WebimSession.java.

MessageStream

Все методы, касающиеся потока сообщений, описаны в файле MessageStream.java.

Для использования этих методов необходимо получить объект класса MessageStream. Это достигается методом getStream() экземпляра WebimSession.

Примеры методов:

sendMessage(String) – отправить сообщение,

rateOperator(Operator.Id, int) – оценить оператора,

closeChat() – закрыть чат.

MessageTracker

Метод newMessageTracker(MessageListener) объекта MessageStream создает объект класса MessageTracker, с помощью которого можно управлять потоком сообщений в контексте приложения клиента.

Например, метод getNextMessages(int, GetMessagesCallback) запрашивает определенное количество сообщений из истории сообщений.

Описание методов можно найти в файле MessageTracker.java.

MessageListener

Интерфейс MessageListener описывает методы, позволяющие отследить изменения в потоке сообщений. В пользовательском приложении необходим класс, который реализует методы данного интерфейса: messageAdded(Message, Message), messageRemoved(Message), allMessagesRemoved(), messageChanged(Message, Message). Эти методы автоматически вызываются при добавлении сообщения, удаления сообщения, удаления всех сообщений и изменении сообщения, соответственно.

Полные описания методов можно найти в файле MessageListener.java.

Message

Методы интерфейса MessageListener оперируют объектами класса Message, описанном в файле Message.java.

С помощью методов экземпляров класса Message можно получить все необходимые данные о конкретном сообщении: уникальный номер сообщение (метод getId()), текст сообщения (метод getText()), информацию о вложенном файле (метод getAttachment()) и т.д.

Все связанные с этим классом инструменты (методы для работы с вложениями, типы сообщений и пр.) также описаны в файле Message.java.

Дополнительные возможности

В файле Operator.java описаны методы для получения информации о том или ином операторе. Конкретный объект оператора можно получить методом getCurrentOperator() объекта MessageStream.

В файле WebimPushNotification.java описаны методы для работы с push-уведомлениями, получаемыми от сервиса Webim.

Объект конкретного уведомления можно получить методом parseGcmPushNotification(Bundle) класса Webim. У этого же класса также имеется метод getGcmSenderId(), который позволяет узнать, было ли отправлено push-уведомление сервисом Webim или каким-либо другим сервисом.

В файле FatalErrorHandler.java имеется описание интерфейса FatalErrorHandler, методы которого могут быть реализованы конкретным мобильным приложением для отслеживания возникающих в процессе работы ошибок. Все конкретные ошибки описаны в этом же файле.

В файле MessageStream.java имеются описания дополнительных интерфейсов, методы которых могут реализовывать классы приложения для отслеживания тех или иных специфических событий. Например, методы интерфейса ChatStateListener реагируют на изменения состояния чата (описания возможных состояний чата имеются в этом же файле).

В файле WebimLog.java имеется описание интерфейса WebimLog, метод log(String) которого может быть реализован конкретным мобильным приложением для отслеживания пользовательских сетевых запросов и ответов сервера.

В файле ProvidedAuthorizationTokenStateListener.java имеется описание интерфейса ProvidedAuthorizationTokenStateListener. Если клиент предоставляет собственный механизм авторизации посетителя, это может быть реализовано с помощью передачи специального токена, который используется вместо посетительских полей. В момент генерации (или получения переданного значения) этого токена, вызывается метод updateProvidedAuthorizationToken(String). Это означает, что сервис клиента должен передать данный токен в сервис Webim.

В файле Department.java описаны методы для получения информации о том или ином отделе. Список отделов можно получить методом getDepartmentList() объекта MessageStream.

Заключение

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

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

Публичные интерфейсы, классы и методы описаны в файлах (в алфавитном порядке):

  • Department
  • FatalErrorHandler.java
  • Message.java
  • MessageListener.java
  • MessageStream.java
  • MessageTracker.java
  • Operator.java
  • ProvidedAuthorizationTokenStateListener.java
  • Webim.java
  • WebimError.java
  • WebimLog.java
  • WebimPushNotification.java
  • WebimSession.java

Описание каждого класса, интерфейса, метода и т.д. можно найти в справочнике.