Подписаться

LiveTex для iOS

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

Введение 

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

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

Image_from_iOS.png

  • Скачать непосредственно 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 вам потребуется следующее:

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

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

Шаг 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-уведомлений.

  1. Запустите Keychain Access(Связка ключей)
  2. Нажмите пункт меню Keychain Access(Связка ключей), разверните CertificateAssistant(Ассиcтент сертификации), а затем выберите Request a Certificate from a Certificate Authority(Запросить сертификат у бюро сертификации).pasted_image_0.png
  3. Заполните поля E-mail пользователя и Общее имя, выберите Saved to disk(Сохранен на диске), а затем —  Продолжить. Оставьте поле CA Email Address(Адрес e-mail БС) пустым, так как оно является необязательным.pasted_image_0__1_.png
  4. Задайте имя CSR-файлу в поле Сохранить как, выберите расположение в поле Место и нажмите кнопку Сохранить.pasted_image_0__2_.png

При этом CSR-файл сохраняется в выбранном месте. Расположением по умолчанию является рабочий стол. Запомните расположение, выбранное для файла.

Теперь необходимо зарегистрировать приложение в Apple, включить push-уведомления и передать экспортированный CSR-файл для создания сертификата push-уведомлений.

Шаг 2: Регистрация приложения для работы с push-уведомлениями

Чтобы отправлять push-уведомления в приложение iOS, зарегистрируйте приложение для получения push-уведомлений. Войдите в ваш аккаунт Apple developer

Войдите на портал и выберите раздел Identifiers. Затем выберите  +  , чтобы зарегистрировать новое приложение.pasted_image_0__3_.png

На экране Register a new Identifier установите переключатель App IDs. Затем нажмите кнопку Continue.pasted_image_0__4_.png

Заполните следующие поля для нового приложения и нажмите кнопку Continue

  • Description: Введите имя приложения
  • Bundle ID: Введите идентификатор приложенияpasted_image_0__5_.png
  • Push-уведомления: Установите в разделе Capabilities флажок  Push-уведомленияpasted_image_0__6_.png

 

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

После нажатия кнопки Register вы увидите новый идентификатор приложения в виде элемента строки на странице Certificates, Identifiers & Profiles.

Шаг 3: Создание сертификата APNS

На странице Certificates, Identifiers & Profiles в разделе Identifiers перейдите к только что созданному элементу строки идентификатора приложения и выберите соответствующую строку с только что созданным идентификатором приложения, чтобы отобразить окно Edit your App ID Configuration.

Сертификат нужен для того, чтобы центр уведомлений мог работать с APNS. Напротив параметра Push-уведомления нажмите кнопку Configure, чтобы создать сертификат.pasted_image_0__8_.png

Откроется окно Apple Push Notification service SSL Certificates. Нажмите кнопку Create Certificate в разделе Development SSL Certificates.pasted_image_0__9_.png

Появится экран Create a New Certificate.pasted_image_0__10_.png

Нажмите Choose File, перейдите к папке, в которой сохранен CSR-файл, созданный в Шаге 1, и дважды щелкните имя сертификата, чтобы загрузить его. Затем нажмите кнопку Continue.pasted_image_0__11_.png

После того как сертификат будет создан на портале, нажмите кнопку Download . Сохраните сертификат и запомните расположение, в котором он сохранен.

После загрузки цифрового сертификата дважды щелкните на скачанный сертификат push-уведомлений. Keychain Access автоматически импортирует цифровой сертификат и свяжет его с секретным ключом, сгенерированным при создании запроса

В программе Keychain Access щелкните правой кнопкой мыши на новый сертификат push-уведомлений. Нажмите Экспортировать, укажите имя файла, выберите формат .p12  и нажмите кнопку Сохранить.pasted_image_0__12_.png

При создании файла .p12 Keychain Access потребует назначить пароль для защиты секретного ключа. Обязательно укажите пароль. Полученный файл (.p12) необходимо отправить на почту support@livetex.ru, указав ваш ключ разработчика или идентификатор вашего аккаунта в Livetex. с указанием установленного для сертификата пароля. Обязательно укажите, для какого профиля сертификат, development (Sandbox) или production.

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

Комментарии