WebimClientLibrary

SDK для интеграции сервиса Webim в мобильные приложения iOSiPhone/iPad

Оглавление

Установка
Пример приложения
Использование
Заключение
Дополнительная информация

Установка

CocoaPods

WebimClientLibrary доступен с помощью технологии CocoaPods (репозиторий). Чтобы установить SDK необходимо добавить в ваш Podfile для нужного target:
pod ‘WebimClientLibrary’, :git => ‘https://github.com/webim/webim-client-sdk-ios.git’

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

Carthage

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

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

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

Objective-C

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

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

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

Пример приложения

Чтобы запустить пример, «склонируйте» репозиторий и выполните команду pod install из директории Example.

Если у вас не установлен CocoaPods, перед этим необходимо их установить командой в терминале:

sudo gem install cocoapods

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

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-уведомлений в iOS, ваше приложение должно быть осведомлено о возможных типах уведомлений и присылаемых в них (уведомлениях) аргументах. Возможные значения параметра «loc-key»:

  • «P.CR» означает, что оператор прислал запрос контактных данных;
  • «P.OA» означает, что оператор взял чат в обработку;
  • «P.OF» означает, что оператор прислал файл;
  • «P.OM» означает, что оператор прислал сообщение;
  • «P.WM» означает, что оператор прислал виджет (для поддержки данного функционала необходимо обратиться в службу поддержки).

(Типы уведомлений со временем могут быть дополнены.)

Значения массива аргументов (параметр «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

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

 

Дополнительная информация

 

WebimClientLibrary использует библиотеки SQLite.swift и CryptoSwift. (Устанавливать отдельные зависимости в Podfile не нужно.)

Наверх