Москва +7 499 322 3754 Серебряническая набережная, 29
Санкт-Петербург +7 812 385 5337 Чкаловский проспект, 15
Попробовать демо-версию

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

Скачать
Webim Mobile SDK
2.3
для Apple iOS
iOS

Библиотека Webim Mobile SDK 2.3 предоставляет разработчикам мобильных приложений на платформе Apple iOS средства для интеграции в эти приложения чата между их пользователями и операторами компании-разработчика на основе технологий, использующихся в онлайн консультанте Webim.

Содержание страницы:

Ссылки по теме:

 


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

Нами предлагается пример приложения, написанный на Objective-C с использованием библиотеки Webim Mobile SDK для iOS.

Это приложение позволяет открыть чат между пользователем телефона и оператором.

Скачать приложение или открыть на github.com

Адрес административного раздела https://demo.webim.ru

Приложение работает под учётной записью demo.


 

Инструкция по добавлению WEBIM MOBILE SDK в проект iOS

Чтобы подключить библиотеку Webim Mobile SDK в проект на платформе Apple iOS в XCode IDE, выполните следующие шаги:

  1. Скачайте и распакуйте Webim Mobile SDK для iOS
  2. Создайте проект, в котором будет использоваться Webim SDK.
  3. Подключите проект библиотеки. Необходимо добавить заголовочные файлы и файл

      libWebimClientLibrary-ХХ.a

  4. Откройте проект XCode и скопируйте в него перемещением файлы библиотеки из директории в Finder. Альтернативно можно использовать меню XСode > File > Add files…
  5. Для Target в настройках проекта в Build Settings нужно выставить флаг -ObjC для Other Linker Flags.
  6. Включите необходимые заголовочные файлы библиотеки в файлах имплементации, где предполагается использовать классы библиотеки.
  7. На экране чата внизу разместите надпись «Предоставлено: webim.ru«, где webim.ru подчёркнуто и является кликабельной ссылкой на сайт Webim.

Минимальная поддерживаемая версия операционной системы — iOS 5.0.


 

Структура

Webim Mobile SDK предоставляют простой и удобный интерфейс для работы с сервисом Webim. Все API сосредоточены в классе WMSession, который через механизм делегирования оповещает об изменении состояния чата. Для того, чтобы начать работать с чатом, необходимо инициализировать объект сессии и выставить ему делегата. Делегатом может быть любой контроллер, который будет управлять отображаемыми видами и следить за изменением состояния сессии. Делегат должен следовать протоколу WMSessionDelegate, описанному в файле WMSession.h.
Кроме выбора делегата необходимо определиться с размещением и учётной записью в сервисе Webim. Объект WMSession работает только с одним выбранным размещением.

Сессия инициализируется методом:

 - (id)initWithAccountName:(NSString *)accountName
                  location:(NSString *)location
                  delegate:(id<WMSessionDelegate>)delegate
              visitorFields:(NSDictionary *)visitorFields;

Параметр accountName — это имя аккаунта в системе Webim. В случае использования сервиса на своем домене, вместо аккаунта нужно предать полный URI до API сервиса.
Необязательный параметр visitorFields используется для идентификации пользователя. Значения словаря должны задаваться в соответствии с правилами идентификации, в чем могут помочь следующие константы, объявленные в WMSession.h:

extern NSString *const WMVisitorParameterDisplayName;
extern NSString *const WMVisitorParameterPhone;
extern NSString *const WMVisitorParameterEmail;
extern NSString *const WMVisitorParameterICQ;
extern NSString *const WMVisitorParameterProfileURL;
extern NSString *const WMVisitorParameterAvatarURL;
extern NSString *const WMVisitorParameterID;
extern NSString *const WMVisitorParameterLogin;
extern NSString *const WMVisitorParameterCRC

Онлайн сессия использует определенный набор асинхронных методов, имеющих блок завершения, описанный следующим типом:

typedef void (^WMResponseCompletionBlock)(BOOL successful);


 

Начало работы

Для начала необходимо стартовать сессию методом:

 — (void)startSession:(WMResponseCompletionBlock)block;

При успешном старте сессии на делегате вызовется метод

 — (void)sessionDidReceiveFullUpdate:(WMSession *)session;

Вызов данного метода возможно в любое время работы сессии на ряду с другими методами. Вызов полного обновления означает, что необходимо обновить все данные, связанные с работой СДК.
Чтобы остановить сессию, необходимо вызывать метод

 — (void)stopSession;

После вызова данного метода отключается обновление данных и вызовы методов делегата.
Внутренние данные сессии, такие как состояние, чат, оператор, — могут измениться по ходу работы. Для этого необходимо анализировать изменения, присылаемые на делегат. Например, можно анализировать состояние сессии методами делегата:

— (void)sessionDidChangeStatus:(WMSession *)session;
— (void)session:(WMSession *)session didChangeOnlineStatus:(WMSessionOnlineStatus)onlineStatus;
— (void)session:(WMSession *)session didChangeOperatorTyping:(BOOL)typing;

Для получения push-уведомлений необходимо передать токен девайса, полученный от APNS, методом класса:

+ (void)setDeviceToken:(NSData *)deviceToken;
— (void)setDeviceToken:(NSData *)deviceToken completion:(WMResponseCompletionBlock)block;

 + (void)setDeviceTokenString:(NSString *)token;

 


 

Вызов чата

Для использования чата интересно только одно состояние сессии: WMSessionStateOfflineMessage — выставление состояния сессии в этот флаг означает, что не осталось онлайн операторов и чат будет завершен. При первом запуске чат скорее всего не будет инициализирован, то есть session.chat == nil или session.chat.state == WMChatStateUnknown. Однако при повторной инициализации чат уже (ещё) может существовать, если это так, то необходимо отобразить этот чат. Он уже будет содержать сообщения. Объект WMChat имеет несколько состояний, которые важны для определения необходимости отображать этот чат пользователю.

  typedef enum {     WMChatStateUnknown,     WMChatStateQueue,     WMChatStateChatting,     WMChatStateClosed,     WMChatStateClosedByVisitor,     WMChatStateClosedByOperator,     WMChatStateInvitation, } WMChatState;

Если чат существует и находится в одном из состояний WMChatStateQueueWMChatStateChatting или WMChatStateClosedByOperator, то его необходимо отобразить пользователю. Если на делегате вызывается один из методов об изменении чата, то при изменении состояния на любое другое — чат должен закрыться. Обращения к такому чату (посылка сообщений, закрытие) будут возвращать ошибку. Перед началом чата необходимо убедиться в наличии операторов онлайн. Это можно узнать, вызвав метод WMSessionOnlineStatus session.onlineStatus. Статус WMSessionOnlineStatusOnline говорит о том, что возможен онлайн чат. Статус WMSessionOnlineStatusBusyOnline говорит о том, что очередь онлайн чатов закончена. Аналогично статус WMSessionOnlineStatusOffline — доступны оффлайн обращения и WMSessionOnlineStatusBusyOffline — оффлайн очередь переполнена.

Если чат не существует, то его можно инициировать методом сессии:

 - (NSString *)startChat:(WMResponseCompletionBlock)block;
 - (NSString *)startChatWithClientSideId:(NSString *)clientSideId
                         completionBlock:(WMResponseCompletionBlock)completionBlock;

Для индентификации чата локально, можно использовать так называемые clientSideId — это уникальная строка, с помощью которой клиентская сторона может сопоставить начатый чат и тот, что пришел на делегате. Оба метода возвращают этот идентификатор. Метод startChatWithClientSideId также принимает clientSideId, сгенерированный внешним алгоритмом.

Если вызов одного из этих методов будет удачным, то на делегате вызовется один из методов,  в зависимости от текущего состояния чата:

— (void)session:(WMSession *)session didStartChat:(WMChat *)chat;
— (void)sessionDidChangeChatStatus:(WMSession *)session;

 


 

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

Для закрытия чата вызывается метод:

 — (void)closeChat:(WMResponseCompletionBlock)block;

который аналогичным открытию чата образом влияет на делегат и состояние сессии и чата. Инициированный чат содержит указатель на массив сообщений, принадлежащих этому чату. Каждое из сообщений имеет тип, описанный в WMMessage.h. Условно они делятся на три типа:

  • сообщения от посетителя,
  • от оператора и
  • системные сообщения.

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

 - (NSString *)sendMessage:(NSString *)message
          withClientSideId:(NSString *)clientSideId
              successBlock:(void (^)(NSString *clientSideId))successBlock
              failureBlock:(void (^)(NSString *clientSideId, WMSessionError error))failureBlock;

message — текст сообщения
clientSideId — уникальный клиентский идентификатор сообщения
successBlock — блок, вызываемый при успешном добавлении сообщения в очередь на сервере
failureBlock — блок, вызываемый при ошибке отправки. В параметрах будет содержать уникальный идентификатор и ошибку
Метод возвращает в место вызова clientSideId, сгенерированный СДК или алгоритмом пользователя.

Реакцией на успешную доставку сообщения, также как и на появления системного или операторского сообщения, будет вызов на делегате метода:

 — (void)session:(WMSession *)session didReceiveMessage:(WMMessage *)message;

При работе с сообщениями оператора в реалтайм чатах также доступны данные оператора: в экземпляре класса WMMessage доступны поля senderUID — уникальный идентификатора оператора, senderName — имя оператора и senderAvatarURL — урл для скачивания аватара оператора.
Аналогично предыдущему работает метод отправки файлов:

 - (NSString *)sendFile:(NSData *)fileData
                   name:(NSString *)fileName
               mimeType:(NSString *)mimeType
       withClientSideId:(NSString *)clientSideId
           successBlock:(void (^)(NSString *clientSideId))succcessBlock
           failureBlock:(void(^)(NSString *clientSideId, WMSessionError error))failureBlock;

При пересылке необходимо указать тип вложения — mime type и соответсвующее ему расширение у имени файла. Так, для изображений необходимо указать, например, filename = «image.png» и mimeType = «image/png».
В случае файловых сообщений в на делегате будет WMMessage, содержащий поле WMFileParams *fileParams. Данное поле имеет описания вложения, такие как размер, имя и тип контента. Для тех сообщений, которые имеют вложение-изображение, будут содержаться данные в fileParams.imageParams. WMImageParams *imageParams описывают размер изображения, доступного к скачиванию.

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

 — (NSURL *)attachmentURLForMessage:(WMMessage *)message;

В реалтайм чате возможно задание состояния чата «посетитель начал набирать сообщение». Выставить это состояние можно методом

 — (void)setComposingMessage:(BOOL)isComposing draft:(NSString *)draft;

После вызова метода с параметром isComposing YES, необходимо вызывать его же со значением NO, чтобы в админке отображалось адекватное состояние сессии. При этом возможно передать текст, который печатает посетитель, заполнив параметр draft. Пустое значение draft удаляет хранимый черновик.

Если объект чата инициализирован, то он может содержать ссылку на объект оператора. В случае, если оператор меняется или берёт посетителя в обработку, на делегате вызывается метод

 — (void)session:(WMSession *)session didUpdateOperator:(WMOperator *)chatOperator

По объекту WMOperator можно определить имя оператора и путь для загрузки его аватара.
Оператор для чата в истории сообщений не определен, так как в процессе работы возможна смена операторов, отвечающих в чате. Операторы чата могут быть найдены по сообщениям в чате — поля WMMessage::SenderUID, SenderName и SenderAvatarURL в полученных сообщениях.

При необходимости дать пользователю обновить чат, у сессии можно вызвать метод:

 — (void)refreshSessionWithCompletionBlock:(WMResponseCompletionBlock)block;

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

 — (void)session:(WMSession *)session didReceiveError:(WMSessionError)errorID;

который возвращает номер ошибки из перечисления WMSessionError. Если на устройстве нет сети, то при вызове методов API на делегат будет возвращаться константа WMSessionErrorNetworkError. При смене режимов работы сети библиотека сама возобновляет соединение с сервером. При этом на делегате будет вызываться опциональный метод:

 — (void)session:(WMSession *)session didChangeConnectionStatus:(WMSessionConnectionStatus)status;

Ожидаемая реакция приложения на переключение статуса сети — оповещение пользователя и, по необходимости, либо ограничение доступа к чату (вид блокирующей деятельности), либо перехват соответствующих методов для дальнейшего восстановления данных.

Для оценки оператора по пятибальной шкале нужно использовать метод

 — (void)rateOperator:(NSString *)authorID withRate:(WMOperatorRate)rate completion:(WMResponseCompletionBlock)block;

Аргументами передается authorID из сообщения оператора и rate, выбранное из одного из перечисления WMOperatorRate.

enum WMOperatorRate {
WMOperatorRateOneStar,
WMOperatorRateTwoStars,
WMOperatorRateThreeStars,
WMOperatorRateFourStars,
WMOperatorRateFiveStars
};

 


 

Оффлайн-обращения

Обращения к оператору могут происходить в режиме «оффлайн». В этом режиме задержка ответа не критична, но важно время хранения и способ обращения с чатами на стороне сервера. За работу с таким типом чатов отвечает класс SDK WMOfflineSession. Как и для обычных чатов, необходимо инициализировать его перед вызовом любых других методов работы с классом.

 — (id)initWithAccountName:(NSString *)accountName location:(NSString *)location token:(NSString *)token platform:(NSString *)platform visitorFields:(NSDictionary *)visitorFields;

Параметр token является обязательным, он однозначно определяет пользователя системы, т. е. он должен быть уникальным. Более того, токен не должен меняться от запуска приложения к запуску, иначе произойдет потеря данных пользователя. При использовании ios пуш токена, сервис Webim будет уведомлять приложение через стандартный механизм пуш-уведомлений.
Параметр platform, если установлен, используется для определения сервером webim механизма отсылки уведомлений — использование пользовательского сервера или стандартного механизма ios пуш-уведомлений. Для использования этого параметра необходимо связаться со службой поддержки Webim.

Данные о чатах хранятся в памяти и доступны через свойство класса:

 @property (nonatomic, strong) NSMutableArray *appealsArray;

Данный массив хранит объекты типа WMChat. Каждый чат имеет ссылку на относящиеся к нему сообщения. В общем случае чаты и сообщения отсортированы по дате создания.

Для уменьшения трафика объекты SDK сохраняют своё состояние в файле на диске. Предполагается, что клиентское приложение будет периодически опрашивать сервер на предмет появления новых сообщений в чатах. Это осуществляется методом класса WMOfflineMessage:

 — (void)getHistoryForced:(BOOL)forced completion:(void (^)(BOOL successful, id changes, NSError *error))block;

Флаг forced заставляет SDK заново запросить всю историю. Не рекомендуюется злоупотреблять этим флагом из-за увеличения трафика.
Параметр block вызывается при завершении запроса.

Здесь и далее используется блок, вызываемый при завершении запроса. Он имеет следующую структуру:

  • флаг, сигнализирующий успепех запроса
  • один или несколько объектов, значения которых имеют значение при успешном завершении метода
  • объект ошибки, валидный только при неуспешном завершении метода

Ошибка может быть нескольких типов — ошибки домена Webim определяются константой WMWebimErrorDomain. В случае такой ошибки имеет место её код — он будет одним из значений перечисления WMSessionError из заголовочного файла WMBaseSession.h.
Остальные ошибки могут быть сетевыми NSURLConnection или критическими, наподобие 500-ой сервера.

Возвращаясь к методу запроса истории: параметр changes блока содержит в себе информацию о модификациях с предыдущего запроса. По сути, это словарь, значения которого достаются ключами, описанными в заголовочном файле WMOfflineSession:

extern NSString *const WMOfflineChatChangesNewChatsKey;
extern NSString *const WMOfflineChatChangesModifiedChatsKey;
extern NSString *const WMOfflineChatChangesMessagesKey;

С помощью данных ключей можно определить, какие чаты были добавлены, изменены и какие сообщения были добавлены в эти чаты.

Для связи объектов WMMessage и WMChat можно использовать метод класса WMOfflineSession:

 — (WMChat *)chatForMessage:(WMMessage *)message;

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

 - (void)sendMessage:(NSString *)text
              inChat:(WMChat *)chat
       departmentKey:(NSString *)departmentKey
         onDataBlock:(void (^)(BOOL successful, WMChat *chat, WMMessage *message, NSError *error))block
          completion:(void (^)(BOOL successful))completion;

Параметр text является обязательным.
Если параметр chat является пустым (передается nil), то метод создает новый чат с одним новым сообщением. Если параметр chat передан, то создастся новое сообщение в этом чате.
Параметр departmentKey назначает отдел новому чату, может быть пустым.
Блок onDataBlock вызывается сразу после ответа сервера и содержит объекты WMChat и WMMessage — новые объекты сообщения и чата, если было запрошено создание нового чата.
Блок completion вызывается после записи новых данных в хранилище.

Аналогично работает метод отправки изображения:

 - (void)sendImage:(NSData *)imageData
              type:(WMChatAttachmentImageType)type
            inChat:(WMChat *)chat
     departmentKey:(NSString *)departmentKey
       onDataBlock:(void (^)(BOOL successful, WMChat *chat, WMMessage *message, NSError *error))block
        completion:(void (^)(BOOL successful))completion;

В параметр imageData должно передаваться изображение в формате png или jpeg. Тип изображения при этом предается в параметр type.

 - (void)sendFile:(NSData *)fileData
             name:(NSString *)fileName
         mimeType:(NSString *)mimeType
           inChat:(WMChat *)chat
    departmentKey:(NSString *)departmentKey
      onDataBlock:(void (^)(BOOL successful, WMChat *chat, WMMessage *message, NSError *error))block
       completion:(void (^)(BOOL successful))completion;

Сообщения WMMessage, созданные данным методом будут иметь тип WMMessageKindFileFromVisitor. SDK предоставляет способ загрузки одного изображения через объект сессии:

 — (void)dowloadImageForMessage:(WMMessage *)message completion:(void (^)(BOOL successful, UIImage *image, NSError *error))block;

Однако получить URL файла можно вызвав метод

 — (NSURL *)attachmentURLForMessage:(WMMessage *)message;

SDK не хранит прикрепленные к чату файлы. Управление загрузкой и отображением целиком ложится на пользовательское приложение.

Для избежания регулярных скачиваний рекомендуется использовать кэш изображений — в памяти и/или на диске.

При появлении в истории ответа от оператора, соответствующий чат помечается как непрочитанный. Поэтому, после отображения чата пользователю необходимо пометить его прочитанным методом класса сессии:

 — (void)markChatAsRead:(WMChat *)chat completion:(void (^)(BOOL successful, NSError *error))block;

Удаление чата осуществляется с помощью:

 — (void)deleteChat:(WMChat *)chat completion:(void (^)(BOOL successful, NSError *error))block;

Смена пользователя

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

  1. Перестать запрашивать историю для сессии А
  2. Отключить слежение за сессией А. Например, для данных в appealsArray.
  3. Cделать очистку данных [WMSession clearCachedUserData] и освободить сессию А.
  4. Создать сессию B с другими желаемыми параметрами.
  5. Запросить историю сессии В.