Подписаться

LiveTex для Android

Введение
Установка
Описание логики SDK 3.0
Push нотификации

Введение 

Livetex SDK 3.0 для Android позволяет вам использовать ваше мобильное приложение для общения с вашими пользователями.

Для клиента в мобильном приложении чат выглядит следующим образом:

Screenshot_2020-07-10-15-50-08-580_ru.livetex.demoapp.png

Скачать исходный код приложения можно в нашем репозитории:
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 вам потребуется следующее:

  1. Пройдите регистрацию, как описано тут;
  2. После регистрации и активации пробного доступа пройдите в личном кабинете в раздел Настройки - Точки контакта. Нажмите на кнопку “Добавить” в верхней правой части и в появившемся модальном окне выберите из выпадающего списка значение “Мобильное приложение”. Далее укажите название для точки контакта и нажмите кнопку “Добавить”.
  3. После добавления новая точка контакта появится в списке. Напротив неё вы сможете увидеть идентификатор и Ключ доступа, как на этом снимке:
    chrome_0ruEBCigxT.png
    Кликните на Ключ доступа и Скопируйте token

    chrome_F6PGAFsduj.png

    Данный ключ доступа будет использовать при инициализации SDK 3.0 и при авторизации в Visitor API.
  4. Перейдите в личном кабинете в раздел Настройки - Маршрутизация и добавьте к созданной точке контакта тех сотрудников, которые должны принимать обращения из приложения. Подробнее в этой статье.

Для инициализации Готового чата и 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-уведомления на устройство:

  1. Отправка уведомлений реализована на вашем сервере (Рекомендуемый)
  2. Отправка уведомлений с сервера 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 и создайте новый проект:

Нажмите на “Добавить проект”, в открывшемся окне укажите название проекта, выберите родительский проект, если это предлагается, и нажмите “Продолжить”._________09-07-2020_131602.pngНа шаге 2 и 3 настройте Google Analytics для вашего проекта, если это требуется. Если такой необходимости нет, то на втором шаге отключите параметр “Включить Google Аналитику в этом проекте” и нажмите на появившуюся кнопку “Создать проект”. Если это будет необходимо, то включить аналитику вы сможете после создания.

_________09-07-2020_131910.png

Запустится процесс создания проекта, после завершения которого нажмите “Далее”, у вас откроется ваш проект. Прокрутите страницу вниз до раздела Cloud Messaging и нажмите на него:

_________09-07-2020_132301.png

На открывшейся странице нажмите на иконку Android:

_________09-07-2020_132444.png

Далее введите название вашего пакета Android и нажмите на “Зарегистрировать приложение”:

_________09-07-2020_134310.png

Шаг 2: Подключите клиент для приёма уведомлений

Нажмите на “Скачать google-services.json” для загрузки файла конфигурации. Вам необходимо разместить данный файл в в корневой каталог модуля вашего приложения:

_________09-07-2020_152343.png

Нажмите “Далее” и затем в build.gradle вашего приложения добавьте следующие строки для указания зависимостей:

dependencies {
    implementation 'com.google.firebase:firebase-messaging:20.+'
}

В нижней части вашего build.gradle, обязательно последней строкой, должно быть указано:

apply plugin: 'com.google.gms.google-services'

Вновь нажмите “Далее” и затем “Открыть консоль”.

Шаг 3: Передайте ваш Server key в LiveTex

Выберите в консоли настройки вашего проекта

_________09-07-2020_155655.png

И перейдите на вкладку Сервисные аккаунты. Если сервисный аккаунт ещё не создан, то нажмите Создать серверный аккаунт. Аккаунт будет создан автоматически. После создания сервисного аккаунта страница будет выглядеть так:

_________09-07-2020_155939.png

Если закрытый ключ ещё не создан, то нажмите “Создание закрытого ключа”. Появится модальное окно с информацией и кнопкой для подтверждения процесса создания ключа. После нажатия на кнопку “Создать ключ” браузер скачает файл с расширением .json, в котором будет содержаться закрытый ключ. Полученный файл необходимо отправить на почту support@livetex.ru, указав ваш ключ разработчика или идентификатор вашего аккаунта в Livetex.

После добавления ключа с нашей стороны сервер LiveTex сможет отправлять уведомления в подключенное в ваш Firebase-проект приложение.

Была ли эта статья полезной?
Пользователи, считающие этот материал полезным: 0 из 0
Еще есть вопросы? Отправить запрос

Комментарии