Введение
Настройка
Описание логики SDK 3.0
Push нотификации
Введение
SDK 3.0 для iOS позволяет вам использовать ваше мобильное приложение для общения с вашими пользователями.
Для клиента в мобильном приложении чат выглядит следующим образом:
- Скачать непосредственно SDK можно в нашем репозитории: https://github.com/LiveTex/sdk-ios;
- Библиотека, которая позволяет легко и просто интегрировать наш чат с уже готовым ui в ваше приложение: https://github.com/LiveTex/sdk-ui-ios (инструкция) Графические элементы вынесены отдельно, что позволяет вам кастомизировать их под цветовую гамму вашего приложения;
- Демо-приложение, которое вы можете собрать с ключом точки контакта из вашего аккаунта LiveTex и проверить работу чата, доступно в отдельном репозитории: https://github.com/LiveTex/sdk-ios-example;
Готовый чат и SDK 3.0 написаны на языке Swift.
Минимальная поддерживаемая версия iOS 9.0.
Настройка
Шаг 1. Настроить аккаунт LiveTex и точки контакта
Для работы с SDK 3.0 вам потребуется следующее:
- Пройдите регистрацию, как описано тут;
- После регистрации и активации пробного доступа пройдите в личном кабинете в раздел Настройки - Точки контакта. Нажмите на кнопку “Добавить” в верхней правой части и в появившемся модальном окне выберите из выпадающего списка значение “Мобильное приложение”. Далее укажите название для точки контакта и нажмите кнопку “Добавить”.
- После добавления новая точка контакта появится в списке. Напротив неё вы сможете увидеть идентификатор и Ключ доступа, как на этом снимке:
Кликните на Ключ доступа и Скопируйте token:
Данный ключ доступа будет использовать при инициализации SDK 3.0 (LivetexAppID) и при авторизации в Visitor API. - Перейдите в личном кабинете в раздел Настройки - Маршрутизация и добавьте к созданной точке контакта тех сотрудников, которые должны принимать обращения из приложения. Подробнее в этой статье.
Шаг 2. Настройка iOS приложения
Полученные данные в шаге 1 потребуются для работы приложения. Для инициализации готового чата и SDK 3.0 в коде приложения для iOS потребуется указать ключ доступа точки контакта.
Для этого добавьте в файл Info.plist запись, которая показана ниже, заменив для ключа LivetexAppID значение на ваш ключ доступа:
<key>Livetex</key>
<dict>
<key>LivetexAppID</key>
<string>998218:c96fc85d-80d7-51f3-a39d-c68d0efc80fe</string>
</dict>
Ключ доступа точки контакта будет использоваться при инициализации SDK 3.0 и при авторизации в Visitor API с использованием класса LivetexAuthService и метода requestAuthorization
Пример базового использования библиотеки можно посмотреть в демо приложении LiveTex Messaging.
Установка LiveTex в мобильное приложение
Откройте Ваш проект в XCode, затем перейдите на вкладку General → Найдите раздел Framework, Libraries, and Embedded Content → Нажмите Add items(значок плюс) → Add other… → Выберите LivetexCore.xcframework из проекта LivetexMessaging в папке LivetexCore.
Авторизация и установление соединения с сервером:
let loginService = LivetexAuthService(token: "visitorToken", deviceToken: "apns deviceToken")
loginService.requestAuthorization { [weak self] result in
DispatchQueue.main.async {
switch result {
case let .success(token):
let sessionService = LivetexSessionService(token: token)
sessionService.connect()
case let .failure(error):
print(error.localizedDescription)
}
}
}
Отправка событий
let event = ClientEvent(.text("Hello world")) sessionService.sendEvent(event)
Получение событий
sessionService.onEvent = { [weak self] event in
switch event {
case let .state(result):
doSomething()
case .attributes:
doSomething()
}
}
Описание логики SDK 3.0
Основные классы
LivetexAuthService - класс для авторизации. Для авторизации необходимо использовать метод requestAuthorization. В ответ система выдаст идентификатор пользователя visitorToken и эндпойнты, которые будут использоваться сервисом LivetexSessionService для подключения к системе LiveTex, передачи и получения событий.
При инициализации класса LivetexAuthService можно передать visitorToken, customVisitorToken, deviceToken и authPath.
visitorToken - идентификатор пользователя в системе LiveTex, является результатом выполнения метода requestAuthorization. При первом подключении visitorToken не указывается. Выданный visitorToken необходимо сохранить и использовать при последующих подключениях для объединения всей переписки в одну историю.
customVisitorToken - если в вашей системе у пользователя есть свой идентификатор, то можно авторизовать пользователя с его помощью, передав его при инициализации в параметре customVisitorToken. В таком случае система LiveTex в методе requestAuthorization создаст и вернёт visitorToken связанный с customVisitorToken. При последующих подключениях для создания единой истории переписки можно для удобства использовать только customVisitorToken.
В более сложных случаях может появиться необходимость явно связать ранее созданный visitorToken с customVisitorToken для создания единой истории переписки. Это можно сделать, если при инициализации LivetexAuthService указать оба идентификатора. Идентификатор пользователя visitorToken будет привязан к customVisitorToken, если ранее была по нему была авторизация и если он не привязан ни к какому другому customVisitorToken, иначе будет возвращен новый visitorToken привязанный к customVisitorToken.
deviceToken - push-токен устройства в APNS для инициализации возможности отправлять
push-нотификаций пользователю когда приложение не подключено к системе.
authPath - позволяет переопределить адрес по умолчанию для подключения к LiveTex. Актуально для коробочных решений.
LivetexSessionService - класс передачи и получения событий.
Вся логика чата построена на обмене событиями (которые проходят по вебсокету). Для получения событий необходимо реализовать handler onEvent. События делятся на отправляемые клиентов и получаемые от сервиса.
События отправляемые клиентом
text - текстовое сообщение.
file - файловое сообщение.
typing - набор текста клиентом.
rating - оценка клиентом назначенного на него оператора.
attributes - отправка атрибутов клиента.
department - отправка клиентом выбранной группы.
getHistory - получение сообщений ранее написанных в диалоге.
События получаемые от сервиса
state - отражает текущее состояние диалога. При открытии соединения, изменении статуса диалога или назначении оператора клиент получает структуру state.
update - событие об изменении сообщений в диалоге. При любом изменении сообщений в диалоге клиент получает событие update, в котором в поле messages содержатся новые сообщения либо изменившиеся старые.
Событие update всегда приходит при открытии websocket канала и содержит последние 10 сообщений.
text - текстовое сообщение.
file - файловое сообщение.
employeeTyping - событие набора текста оператором.
attributesRequest - запрос атрибутов обращения. На это событие необходимо всегда реагировать на клиентской стороне отправкой события attributes.
departmentsRequest - запрос на выбор группы. В случае маршрутизации обращения в очередь, сервис запрашивает выбор группы. На это событие необходимо всегда реагировать отправкой department с выбором конкретной группы.
result - результат выполнения клиентской команды. После получения и обработки команды клиента сервис возвращает result с тем же correlationId.
Push нотификации
В данном разделе мы рассмотрим, как настроить отправку push-уведомлений в ваше мобильное приложение. Есть два способа отправлять push-уведомления на устройство: Отправка уведомлений реализована на вашем сервере (Рекомендуемый) и Отправка уведомлений с сервера LiveTex.
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-нотификаций (APNS). |
|
text |
string |
- |
текст сообщения |
|
url |
string |
- |
ссылка на файл |
Возможные варианты комбинации text/url:
- задан text, не задан url - текстовое сообщение;
- не задан text, задан url - сообщение содержащее файл;
- задан text, задан url - отправлен файл с комментарием.
2. Отправка уведомлений с сервера LiveTex через APNS.
Шаг 1: Создание файла запроса для генерации сертификата
Создайте файл запроса на подписание сертификата (CSR), используемый Apple для создания сертификата push-уведомлений.
- Запустите Keychain Access(Связка ключей)
- Нажмите пункт меню Keychain Access(Связка ключей), разверните CertificateAssistant(Ассиcтент сертификации), а затем выберите Request a Certificate from a Certificate Authority(Запросить сертификат у бюро сертификации).
- Заполните поля E-mail пользователя и Общее имя, выберите Saved to disk(Сохранен на диске), а затем — Продолжить. Оставьте поле CA Email Address(Адрес e-mail БС) пустым, так как оно является необязательным.
- Задайте имя CSR-файлу в поле Сохранить как, выберите расположение в поле Место и нажмите кнопку Сохранить.
При этом CSR-файл сохраняется в выбранном месте. Расположением по умолчанию является рабочий стол. Запомните расположение, выбранное для файла.
Теперь необходимо зарегистрировать приложение в Apple, включить push-уведомления и передать экспортированный CSR-файл для создания сертификата push-уведомлений.
Шаг 2: Регистрация приложения для работы с push-уведомлениями
Чтобы отправлять push-уведомления в приложение iOS, зарегистрируйте приложение для получения push-уведомлений. Войдите в ваш аккаунт Apple developer.
Войдите на портал и выберите раздел Identifiers. Затем выберите + , чтобы зарегистрировать новое приложение.
На экране Register a new Identifier установите переключатель App IDs. Затем нажмите кнопку Continue.
Заполните следующие поля для нового приложения и нажмите кнопку Continue
- Description: Введите имя приложения
- Bundle ID: Введите идентификатор приложения
- Push-уведомления: Установите в разделе Capabilities флажок Push-уведомления
При этом будет создан идентификатор вашего приложения, а также запрошено подтверждение информации. Выберите Continue, а затем нажмите Register, чтобы подтвердить новый идентификатор приложения.
После нажатия кнопки Register вы увидите новый идентификатор приложения в виде элемента строки на странице Certificates, Identifiers & Profiles.
Шаг 3: Создание сертификата APNS
На странице Certificates, Identifiers & Profiles в разделе Identifiers перейдите к только что созданному элементу строки идентификатора приложения и выберите соответствующую строку с только что созданным идентификатором приложения, чтобы отобразить окно Edit your App ID Configuration.
Сертификат нужен для того, чтобы центр уведомлений мог работать с APNS. Напротив параметра Push-уведомления нажмите кнопку Configure, чтобы создать сертификат.
Откроется окно Apple Push Notification service SSL Certificates. Нажмите кнопку Create Certificate в разделе Development SSL Certificates.
Появится экран Create a New Certificate.
Нажмите Choose File, перейдите к папке, в которой сохранен CSR-файл, созданный в Шаге 1, и дважды щелкните имя сертификата, чтобы загрузить его. Затем нажмите кнопку Continue.
После того как сертификат будет создан на портале, нажмите кнопку Download . Сохраните сертификат и запомните расположение, в котором он сохранен.
После загрузки цифрового сертификата дважды щелкните на скачанный сертификат push-уведомлений. Keychain Access автоматически импортирует цифровой сертификат и свяжет его с секретным ключом, сгенерированным при создании запроса
В программе Keychain Access щелкните правой кнопкой мыши на новый сертификат push-уведомлений. Нажмите Экспортировать, укажите имя файла, выберите формат .p12 и нажмите кнопку Сохранить.
При создании файла .p12 Keychain Access потребует назначить пароль для защиты секретного ключа. Обязательно укажите пароль. Полученный файл (.p12) необходимо отправить на почту support@livetex.ru, указав ваш ключ разработчика или идентификатор вашего аккаунта в Livetex. с указанием установленного для сертификата пароля. Обязательно укажите, для какого профиля сертификат, development (Sandbox) или production.
Комментарии