Введение
Установка
Описание логики SDK 3.0
Push нотификации
Введение
Livetex SDK 3.0 для Android позволяет вам использовать ваше мобильное приложение для общения с вашими пользователями.
Для клиента в мобильном приложении чат выглядит следующим образом:
Скачать исходный код приложения можно в нашем репозитории:
https://github.com/LiveTex/sdk-android/
Исходный код демонстрационной версии приложения с пользовательским интерфейсом:
https://github.com/LiveTex/sdk-ui-android
Демо-приложение и SDK 3.0 написаны на Java. Минимальная поддерживаемая версия Android 5.0 (api 21).
Установка
Шаг 1. Установка LiveTex в мобильное приложение
В build.gradle,который в корне проекта, добавить репозиторий jitpack
allprojects {
repositories {
...
maven { url 'https://jitpack.io' }
}
}
В build.gradle, который в модуле приложения, добавить зависимость SDK 3.0 актуальной версии (см. Releases)
dependencies {
implementation 'com.github.LiveTex:sdk-android:x.y'
}
Настройка
Для начала нужно инициализировать объект LiveTex. Делается это обычно в Application классе (например App.java).
new LiveTex.Builder(Const.TOUCHPOINT).build();
Укажите Touchpoint - ключ доступа точки контакта с типом “Мобильное приложение”. Посмотреть можно в личном кабинете в разделе Настройки - Точки контакта (https://my.livetex.ru/settings/touch_points)
Использование
Пример базового использования библиотеки можно посмотреть в демо приложении. Подробнее об методах и логике SDK 3.0 смотрите в разделе Описание логики SDK 3.0.
Шаг 2. Настроить аккаунт LiveTex и точки контакта
Для работы с SDK 3.0 вам потребуется следующее:
- Пройдите регистрацию, как описано тут;
- После регистрации и активации пробного доступа пройдите в личном кабинете в раздел Настройки - Точки контакта. Нажмите на кнопку “Добавить” в верхней правой части и в появившемся модальном окне выберите из выпадающего списка значение “Мобильное приложение”. Далее укажите название для точки контакта и нажмите кнопку “Добавить”.
- После добавления новая точка контакта появится в списке. Напротив неё вы сможете увидеть идентификатор и Ключ доступа, как на этом снимке:
Кликните на Ключ доступа и Скопируйте token
Данный ключ доступа будет использовать при инициализации SDK 3.0 и при авторизации в Visitor API. - Перейдите в личном кабинете в раздел Настройки - Маршрутизация и добавьте к созданной точке контакта тех сотрудников, которые должны принимать обращения из приложения. Подробнее в этой статье.
Для инициализации Готового чата и SDK 3.0 в коде приложения для Android потребуется указать ключ доступа точки контакта для параметра TOUCHPOINT:
new LiveTex.Builder(Const.TOUCHPOINT).build();
В src/main/java/ru/livetex/demoapp/Const.java укажите значение для TOUCHPOINT
String TOUCHPOINT = "168:58dc*******************5690";
С помощью метода LiveTex.Builder.setDeviceToken можно указать push-токен приложения для инициализации отправки push-нотификаций пользователю:
new LiveTex.Builder(Const.TOUCHPOINT)
.setDeviceToken(pushToken)
.build();
Описание логики SDK 3.0
Основные классы
LiveTex - класс для настройки и получения доступа к компонентам.
NetworkManager - класс для работы с сетевым операциями, в том числе авторизация и подключение к вебсокету чата.
LiveTexMessagesHandler - класс для работы с логикой общения по вебсокету. Обработка входящих и исходящих событий.
Авторизация и подключение
Для авторизации и подключения необходимо вызвать метод NetworkManager.connect с указанием параметра authData. Конструкторы AuthData позволяют задать visitorToken и/или customVisitorToken.
visitorToken - идентификатор пользователя в системе LiveTex, является результатом выполнения метода NetworkManager.connect. Задается конструктором AuthData.withVisitorToken. При первом подключении необходимо в конструкторе указать visitorToken как null. Выданный visitorToken необходимо сохранить и использовать при последующих подключениях для объединения всей переписки в одну историю.
customVisitorToken - если в вашей системе у пользователя есть свой идентификатор, то можно авторизовать пользователя с его помощью используя AuthData.withCustomVisitorToken. В таком случае система LiveTex в методе NetworkManager.connect создаст и вернёт visitorToken связанный с customVisitorToken. При последующих подключениях для создания единой истории переписки можно для удобства использовать только customVisitorToken.
В более сложных случаях может появиться необходимость явно связать ранее созданный visitorToken с customVisitorToken для создания единой истории переписки. Это можно сделать, если в конструкторе AuthData.withVisitorAndCustomTokens указать оба идентификатора. Идентификатор пользователя visitorToken будет привязан к customVisitorToken, если ранее была по нему была авторизация и если он не привязан ни к какому другому customVisitorToken, иначе будет возвращен новый visitorToken привязанный к customVisitorToken.
Параметр reconnectRequired метода NetworkManager.connect позволяет включить режим автоматического восстановления соединения.
Чтобы закрыть соединение используйте метод NetworkManager.forceDisconnect.
События в чате
Вся логика чата построена на обмене событиями (которые проходят по вебсокету) в классе LiveTexMessagesHandler
Входящие события
Со стороны экрана чата нужно подписаться на входящие события (пример есть в ChatViewModel.subscribe)
dialogStateUpdate() - обновление состояния диалога. Здесь есть информация об операторе и метод isInputEnabled(), который показывает текущее состояние контролов чата. Если метод вернул false, то рекомендуется отключать UI элементы позволяющие пользователю что-либо отправить в чат. Это нужно, чтобы пользователь не прерывал работу бота. При особой логике работы можно игнорировать.
historyUpdate() - обновление истории диалога. Представляет собой отрезок сообщений, то есть могут прийти как и следующие сообщения, так и прошлые (при запросе предыдущей истории соответственно). Обновление происходит при любом добавлении/изменении сообщений в обращении и при открытии websocket канала. В последнем случае содержит последние 10 сообщений, написанных клиентом или оператором ранее.
attributesRequest() - событие запроса атрибутов. Для корректной логики на него обязательно нужно ответить sendAttributes(). Поступает при инициации взаимодействия со стороны клиента, то есть при начале нового обращения.
departmentRequest() - событие запроса выбора группы. Для корректной логики на него обязательно нужно ответить sendDepartmentSelectionEvent(). При начале обращения сервис запрашивает, в какую группу операторов требуется направить обращение. В уведомлении содержится список возможных для установки групп.
employeeTyping() - в случае набора текста оператором, раз в ~3 секунды будет приходить событие employeeTyping. То есть если событие не поступает более 3 секунд. то это указывает на то, что оператор перестал набирать ответное сообщение.
Исходящие события
sendTextMessage(text) - отправка обычного текстового сообщения.
sendFileMessage(FileUploadedResponse) - отправка файла (картинка, документ и прочее). Перед отправкой файл нужно загрузить через ApiManager (смотрите пример в ChatViewModel.sendFileMessage)
sendRatingEvent(isPositiveFeedback) - посетитель может оценить назначенного на него оператора, но только в том случае, если поле rating в структуре employee в событии state не определено. После отправки команды но проставление оценки, клиенту будет передано событие state, где в структуре employee поле rating примет переданное в команде значение. Поле value может иметь значение 1 (положительно) или 0 (отрицательно).
sendDepartmentSelectionEvent(departmentId) - выбор департамента (группы операторов), ответ на departmentRequest().
sendAttributes(...) - отправка свойств пользователя, ответ на attributesRequest(). Набор обязательных и опциональных полей зависит от проекта.
sendTypingEvent(text) - отправка уведомления о том, что пользователь печатает текст.
getHistory(messageId) - получение предыстории сообщений, которые идут до указанного. Поле messageId должно содержать id сообщения в диалоге, от которого необходимо получить более ранние сообщения. Ответ придет в historyUpdate(), но здесь в подписке вы получите количество предыдущих сообщений. 0 означает что все сообщения загружены.
sendButtonPressedEvent(payload) - отправка нажатия на экшн кнопку (которая внутри входящего сообщения бота).
Push нотификации
В этом разделе будет описано, как настроить отправку push-уведомлений в ваше приложение на Android. Есть два способа отправлять push-уведомления на устройство:
- Отправка уведомлений реализована на вашем сервере (Рекомендуемый)
- Отправка уведомлений с сервера LiveTex через Firebase Cloud Messaging.
1. Отправка уведомлений реализована на вашем сервере (Рекомендуемый)
Вы можете прислать нам URL вашего сервера, на который с сервера LiveTex будут поступать вебхуки с сообщениями в формате JSON. Ваш сервер на основе полученных данных сможет отправить push-уведомление.
Плюсы такого подхода:
- Безопасность. Вам не требуется передавать третьей стороне ключи и пароли для работы с уведомлениями для вашего приложения.
- Гибкость. Вы сами регулируете содержание уведомлений и контролируете их отправку.
Сервер LiveTex посылает вебхук при новом сообщении от оператора в том случае, если связь с приложением прервалась и приложение не восстанавливает соединение с сервером LiveTex заданное время. Из всех сообщений, которые были высланы оператором за время отведенное на восстановление соединения, в вебхуке будет только последнее сообщение. Для отображения в приложении всех сообщений, которые были отправлены, пока отсутствовало соединение, при возвращении на экран чата необходимо загрузить историю при помощи метода getHistory/messageHistory.
Отправляемые в JSON данные:
|
Поле |
Тип данных |
Обязательность |
Описание |
|
version |
string |
+ |
Строка, версия протокола (сейчас только 1) обязательно |
|
platform |
string |
+ |
"ios" | "android" - перечисление может быть либо ios либо android |
|
to |
string |
+ |
id устройства пользователя, переданное в параметре deviceToken при инициализации SDK. Обычно в данном параметре указывается идентифкатор полученный от сервиса push-нотификаций (FCM). |
|
text |
string |
- |
текст сообщения |
|
url |
string |
- |
ссылка на файл |
Возможные варианты комбинации text/url:
- задан text, не задан url - текстовое сообщение;
- не задан text, задан url - сообщение содержащее файл;
- задан text, задан url - отправлен файл с комментарием.
2. Отправка уведомлений с сервера LiveTex через Firebase Cloud Messaging.
Шаг 1: Подключите сервисы Google к вашему приложению
Если у вас уже есть проект в Firebase с подключенными уведомлениями, то вы можете перейти к следующему шагу.
Если пока еще нет, то откройте страницу консоли FCM и создайте новый проект:
Нажмите на “Добавить проект”, в открывшемся окне укажите название проекта, выберите родительский проект, если это предлагается, и нажмите “Продолжить”.
На шаге 2 и 3 настройте Google Analytics для вашего проекта, если это требуется. Если такой необходимости нет, то на втором шаге отключите параметр “Включить Google Аналитику в этом проекте” и нажмите на появившуюся кнопку “Создать проект”. Если это будет необходимо, то включить аналитику вы сможете после создания.
Запустится процесс создания проекта, после завершения которого нажмите “Далее”, у вас откроется ваш проект. Прокрутите страницу вниз до раздела Cloud Messaging и нажмите на него:
На открывшейся странице нажмите на иконку Android:
Далее введите название вашего пакета Android и нажмите на “Зарегистрировать приложение”:
Шаг 2: Подключите клиент для приёма уведомлений
Нажмите на “Скачать google-services.json” для загрузки файла конфигурации. Вам необходимо разместить данный файл в в корневой каталог модуля вашего приложения:
Нажмите “Далее” и затем в build.gradle вашего приложения добавьте следующие строки для указания зависимостей:
dependencies {
implementation 'com.google.firebase:firebase-messaging:20.+'
}
В нижней части вашего build.gradle, обязательно последней строкой, должно быть указано:
apply plugin: 'com.google.gms.google-services'
Вновь нажмите “Далее” и затем “Открыть консоль”.
Шаг 3: Передайте ваш Server key в LiveTex
Выберите в консоли настройки вашего проекта
И перейдите на вкладку Сервисные аккаунты. Если сервисный аккаунт ещё не создан, то нажмите Создать серверный аккаунт. Аккаунт будет создан автоматически. После создания сервисного аккаунта страница будет выглядеть так:
Если закрытый ключ ещё не создан, то нажмите “Создание закрытого ключа”. Появится модальное окно с информацией и кнопкой для подтверждения процесса создания ключа. После нажатия на кнопку “Создать ключ” браузер скачает файл с расширением .json, в котором будет содержаться закрытый ключ. Полученный файл необходимо отправить на почту support@livetex.ru, указав ваш ключ разработчика или идентификатор вашего аккаунта в Livetex.
После добавления ключа с нашей стороны сервер LiveTex сможет отправлять уведомления в подключенное в ваш Firebase-проект приложение.
Комментарии