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

УСТАНОВКА

CocoaPods

Webim Mobile SDK доступен с помощью технологии CocoaPods (репозиторий). Чтобы установить SDK необходимо добавить в ваш Podfile для нужного target:
pod ‘WebimClientLibrary’

В Podfile должна быть указана директива use_frameworks!.

Carthage

WebimMobileSDK доступен также и с помощью Carthage. Строка для добавления в Cartfile:

github «webim/webim-client-sdk-ios» ~> 3.9.0

3.9.0 – это минимальная версия, поддерживающая Carthage. Вы также можете использовать и дальнейшие.

Objective-C

Интегрируете WebimMobileSDK в Objective-C-приложение? Попробуйте нашу обертку – WebimClientLibraryWrapper.

Предыдущую, Objective-C, реализацию (версии 2.x) можно установить из ветки version2 репозитория на Github.
Если вы уже используете предыдущую версию и не планируете переходить на новую, обновлять Podfile необходимости нет: прежние зависимости (до версии 2.7.0 включительно) продолжат функционировать. Но для использования этой версии с номерами 2.8.0 и выше необходимо переключить зависимость на ветку version2.

Инструкция к версии 2.x.

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

В отличие от веб-интерфейса, мобильное приложение на Webim Mobile SDK не проверяет наличие доступных (онлайн) операторов. Иными словами, мобильный чат всегда исходит из того, что кнопка вызова оператора всегда находится в статусе «онлайн». Webim Mobile SDK всегда позволяет начать чат, однако, если отсутствуют операторы, готовые ответить в этом чате, то клиент будет находиться в чате один до тех пор, пока такой оператор появится или чат будет закрыт по тайм-ауту.

Webim поддерживает подключение к Webim Server нескольких разных мобильных приложений на iOS к одной учетной записи заказчика.

Webim Mobile SDK для iOS поддерживает выбор размещения при создании чата. Мы рекомендуем всегда создавать как минимум одно отдельное размещение для мобильного приложения. Если мобильных приложений несколько, минимум одно размещение для каждого МП.

Взаимодействие с чатом проходит в рамках сессии, которая создается в тот момент, когда МП собирается предложить пользователю чат. Для работы с ней используется объект WebimSession.

WebimSession

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

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

let webimSession = 
    try Webim.newSessionBuilder().set(accountName: ACCOUNT_NAME).set(location: LOCATION_NAME).build()

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

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

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

MessageStream

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

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

send(message:) – отправить сообщение,
rateOperatorWith(id:,byRating:) – оценить оператора,
closeChat() – закрыть чат.

MessageTracker

Метод new(messageTracker:) объекта MessageStream создает объект класса MessageTracker, с помощью которого можно управлять потоком сообщений в контексте приложения клиента.
Например, метод getNextMessages(byLimit:,completion:) запрашивает определенное количество сообщений из истории сообщений.

Описание методов экземпляра MessageTracker можно найти в файле MessageTracker.swift.

MessageListener

Протокол MessageListener описывает методы, позволяющие отследить изменения в потоке сообщений. В пользовательском приложении необходим класс, который реализует методы данного протокола: added(message:,after:), removed(message:), removedAllMessages(), changed(message:,to:). Эти методы автоматически вызываются при добавлении сообщения, удаления сообщения, удаления всех сообщений и изменении сообщения, соответственно.

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

Message

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

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

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

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

В файле WebimPushNotification.swift описаны методы для работы с push-уведомлениями, получаемыми от сервиса Webim.
Объект конкретного уведомления можно получить методом parse(remoteNotification:) класса Webim. У этого же класса также имеется метод isWebim(remoteNotification:), который позволяет легко узнать, было ли отправлено push-уведомление сервисом Webim или каким-либо другим сервисом.

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

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

Push-уведомления

Для включения push-уведомлений необходимо предоставить APNS-сертификаты ваших мобильных приложений. При этом можно использовать два комплекта сертификатов: для разработки (dev) и для продуктива (dist). Они могут как совпадать, так и отличаться (один сертификат и для разработческой версии МП, и для продуктивной). Каждый комплект состоит из двух файлов: cert (собственно сертификат) и private_key (приватный ключ к данному сертификату). Возможно также отключение как одного, так и другого комплекта сертификатов через настройки account config. Для размещения сертификатов на сервере Webim и изменения настроек account config свяжитесь, пожалуйста, с нашей службой поддержки.

Итоговые имена файлов сертификатов:

ios_push_cert.dev.pem
ios_push_private_key.dev.pem
ios_push_cert.dist.pem
ios_push_private_key.dist.pem

Для автоматической обработки и отображения push-уведомлений в iOS, ваше приложение должно быть осведомлено о возможных типах уведомлений и присылаемых в них (уведомлениях) аргументах.

Тип push-уведомления определяется параметром loc-key. Список возможных типов и их особенности описаны в статье Push-уведомления.

Значения массива аргументов (параметр loc-args):

для «P.CR» – массив пустой;
для «P.OA» – имя оператора;
для «P.OF» – имя оператора, название файла;
для «P.OM» – имя оператора, текст сообщения;
для «P.WM» – массив пустой.

Пример обработки уведомления с помощью файла Strings.localizable:

«P.OM» = «Получено новое сообщение от %@: %@.»

ЗАКЛЮЧЕНИЕ

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

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

FatalErrorHandler.swift
Message.swift
MessageListener.swift
MessageStream.swift
MessageTracker.swit
Operator.swift
ProvidedAuthorizationTokenStateListener.swift
Webim.swift
WebimError.swift
WebimPushNotification.swift
WebimSession.swift

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