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

Скачать
Webim Mobile SDK
2.2
для Windows Phone 8.1
 win phone 8 

Библиотека Webim Mobile SDK 2.2 предоставляет разработчикам мобильных приложений на платформе Microsoft Windows Phone 8.1 в среде разработки Visual Studio Express 2013 средства для интеграции в эти приложения чата между их пользователями и операторами компании-разработчика на основе технологий, использующихся в онлайн консультанте Webim.

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

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

 


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

  1. Скачайте и распакуйте архив SDK в директорию, которая будет добавлена в проект.
  2. С помощью IDE добавьте ссылку на сборку в проект (проект->References->Add Reference... и выберите WebimSDK.dll с помощью окна браузинга).
  3. На экране чата внизу разместите надпись "Предоставлено: webim.ru", где webim.ru подчёркнуто и является кликабельной ссылкой на сайт Webim.

Нами предлагается пример приложения, написанный на C# с использованием библиотеки Webim Mobile SDK для Windows 8.1.
Это приложение позволяет открыть чат между пользователем телефона и оператором. Скачать приложение или открыть на github.com. Адрес административного раздела https://demo.webim.ru. Приложение работает под учётной записью demo.


 

Структура SDK

Все данные находятся в пространстве имён WebimSDK. SDK предоставляют интерфейс работы с чатом в режиме реалтайм и в режиме оффлайн, когда сообщения не требуют присутствия оператора онлайн.

 

Реалтайм чаты

АПИ реалтайм работают асинхронно и возвращают состояние запроса - булевское значение. Для работы с реалтайм чатами реализован механизм делегирования и с помощью подписки на события можно понимать текущее состояние сессии чата. Реакция на то или иное событие должно вести к обновлению соответствующих частей приложения. Так, например, при отсылке текстового сообщения срабатывает событие, в которое приходит информация о новом сообщении от сервера.

Для успешной работы реалтайм чата необходимо наличие сети Интернет. Взаимодействие с сервером/оператором ведется с помощью экземпляра класса WMSession.

 

Оффлайн чаты

Методы для работы с сервером Webim реализованы асинхронно через async task и возвращают класс WMAPIResponse, описывающий состояние ответа на запрос.
Работа с данными извне происходит через экземпляр класса сессии - WMOfflineSession. Так, с помощью него можно получить список чатов, ассоциированный с пользователем. SDK создаёт файл с сериализованными данными, хранящийся в локальной директории приложения. Данный файл используется при инициализации, и, когда нет доступа к сети Интернет, данные чатов остаются доступными пользователю.

Для работы с сервером SDK использует класс HttpClient, следовательно, возможные исключения выбрасываются в место вызова async метода. Сетевые запросы происходят по протоколу HTTPS.

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


 

Структуры данных

Класс реалтайм сессии WMSession

Перечисления:

enum WMSessionState {
WMSessionStateUnknown, // Начальное (не инициализированное) состояние сессии
WMSessionStateIdle,  // Режим ожидания
WMSessionStateIdleAfterChat, // Режим после чата
WMSessionStateChat,  // Происходит чат с оператором
WMSessionStateOfflineMessage, // Реалтайм чат с оператором не возможен (нет операторов)
}

Делегаты и события:

delegate void SessionDidReceiveFullUpdateHandler(WMSession session);
delegate void SessionDidStartChatHandler(WMSession session, WMChat chat);
delegate void SessionDidChangeChatStatusHandler(WMSession session);
delegate void SessionDidChangeSessionStatusHandler(WMSession session);
delegate void SessionDidUpdateOperatorHandler(WMSession session, WMOperator chatOperator);
delegate void SessionDidReceiveMessageHandler(WMSession session, WMMessage message);
delegate void SessionDidChangeOperatorTypingHandler(WMSession session, bool typing);
delegate void SessionDidReceiveErrorHandler(WMSession session, WMSessionError errorID);

event SessionDidReceiveFullUpdateHandler SessionDidReceiveFullUpdate;
// Произошло полное обновление данных, необходимо обновить все связанные данные
event SessionDidStartChatHandler SessionDidStartChat;
// Реакция на начало чата
event SessionDidChangeChatStatusHandler SessionDidChangeChatStatus;
// Чат изменил состояние, необходимо действовать в соответствии с состоянием чата, если он есть
event SessionDidChangeSessionStatusHandler SessionDidChangeSessionStatus;
// Сессия изменила состояние
event SessionDidUpdateOperatorHandler SessionDidUpdateOperator;
// У чата появился, сменился или исчез оператор
event SessionDidReceiveMessageHandler SessionDidReceiveMessage;
// В чат пришло сообщение - от оператора или от посетителя
public event SessionDidChangeOperatorTypingHandler SessionDidChangeOperatorTyping;
// Оператор начал или закончил набор текста ответа посетителю
event SessionDidReceiveErrorHandler SessionDidReceiveError;
// Произошла ошибка

Свойства:

bool HasOnlineOperators; // Если значение false, то реалтайм чат невозможен
WMSessionState State;  // Состояние сессии
WMChat Chat;  // Реалтайм чат, может быть null

Методы:

WMSession(string account, string location, WMVisitorExt visitorExt)
// Конструктор, принимает параметрами
// account - аккаунт, зарегистрированный в сервисе Webim
// location - размещение (см https://webim.ru/help/help-terms/)
// visitorExt - дополнительные поля посетителя (см https://webim.ru/help/identification/)
async Task StartSessionAsync()
// Метод инициализации сессии. Данный метод необходимо вызывать
// перед вызовом всех остальных методов
async Task StartChatAsync(string clientSideId = null)
// Переводит сессию в состояние чата. Вызывается, когда объект чата не инициализирован
// или находится в одном из состояний [WMSessionStateIdle, WMSessionStateIdleAfterChat]
// Опциональный аргумент clientSideId задает уникальный пользовательский идентификатор чата, который будет доступен через объект чата сессии.
async Task CloseChatAsync()
// Запрашивается выключение чата. Сессия должна быть в состоянии WMSessionStateChat
async Task MarkChatAsReadAsync()
// Помечает активный чат прочитанным со стороны посетителя
async Task SendMessageAsync(string text, string clientSideId = null)
// Добавление сообщения посетителем. Ответ-сообщение приходит на SessionDidReceiveMessage
// text - текст сообщения, максимально 32тыс символов, возможные ошибки придут ошибкой.
// Опциональный аргумент clientSideId задает уникальный пользовательский идентификатор сообщения
async Task SendFileAsync(byte[] fileData, string fileName, string mimeType, string clientSideId = null)
// Отсылка файла (аттач) посетителем. В ответе будет содержаться ссылка на файл, полную ссылку можно
// можно получить при помощи метода базовой сессии - AttachmentUriForMessage
// fileData - сырые данные файла
// fileName - имя файла, не обязательное
// mimeType - тип вложения (как, например, https://en.wikipedia.org/wiki/Internet_media_type)
async Task SendImageAsync(byte[] imageData, WMChatAttachmentImageType type, string clientSideId = null)
// Аналог передачи файла - изображения. Имя файла используется по-умолчанию.
// Тип вложения задается переданным типом параметром type
void SetComposingMessage(bool isComposing, string draft)
// Дает знать оператору о том, что посетитель начал ввод текста или закончил,
// в зависимости от флага isComposing
// draft - вводимый посетителем текст (может быть null)
async Task SetDeviceTokenAsync(string token)
// Задание токена девайса. Токен необходим для работы пуш-уведомлений.
async RateOperatorWithRateAsync(string authorID, WMOperatorRate rate)
// Оценка оператора по пятибальной шкале: authorID берется из сообщения WMMessage

 

Класс дополнительных данных посетителя реалтайм чата WMVisitorExt (идентификация)

Свойства:

string Name
string Phone
string Email
string CRC
string ICQ
string ProfileURL
string AvatarURL
string ID
string Login

 

Класс оператора при ответе реалтайм WMOperator

Свойства:

string Name
string AvatarPath

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

Класс чата WMChat

Свойства:

Перечисления:

enum WMChatStatus {
Sent,  // Удачно отослано (сохранено на сервере)
NotSent, // Возникли проблемы с отсылкой на сервер (сохранено локально)
Deleted // Помечено к удалению локально, возникли проблемы с сетью при удалении
}
string Uid // Уникальный идентификатор чата
bool HasUnreadMessages // Флаг, true если в чате есть непрочитанные сообщения
WMChatStatus Status // Состояние синхронизации с сервером
List<WMMessage> Messages // Список сообщений чата
string ClientSideId; // Уникальный клиентский идентификатор чата

 

Класс сообщения WMMessage

Перечисления:

enum WMMessageKind {
WMMessageKindUnknown,
WMMessageKindForOperator,
WMMessageKindInfo,
WMMessageKindVisitor,
WMMessageKindOperator,
WMMessageKindOperatorBusy,
WMMessageKindContactsRequest,
WMMessageKindContacts,
WMMessageKindFileFromOperator,
WMMessageKindFileFromVisitor
}
enum WMMessageStatus {
Sent,  // Отослано (сохранено на сервере)
Sending,
NotSent // Сохранено локально
}

Свойства:

string Uid  // Уникальный идентификатор сообщения
string ChatId  // Уникальный идентификатор чата
WMMessageKind Kind  // Тип сообщения
string Text  // Текст сообщения
DateTime Timestamp  // Дата получения сообщения сервером
double Ts // Юникс таймстемп даты получения сообщения сервером
string AttachmentPath // Свойство валидно только для WMMessageKindFileFromOperator и WMMessageKindFileFromVisitor, содержит путь до файла на сервере
WMMessageStatus Status // Состояние синхронизации с сервером
string SenderUID // Идентификатор оператора - автора сообщения. Пустое для собственных или системных сообщений. Используется в реалтайм чатах.
string SenderName // Имя автора сообщения. Валидно для сообщений оператора. Используется в реалтайм чатах.
string SenderAvatarURL // Uri аватара автора сообщения. Валидно для сообщений оператора. Используется в реалтайм чатах.
string ClientSideId; // Уникальный клиентский идентификатор сообщения

Методы:

bool isTextMessage()  // true, если экземпляр класса является текстовым сообщением
bool isFileMessage() // true, если сообщение является информационным - о передаче файла

 

Класс ответа на запрос истории WMHistoryChanges:

Свойства:

List<WMChat> NewChats // Список новых чатов (относительно имевшихся до запроса истории данных)
List<WMChat> ModifiedChats // Список чатов, в которых произошли изменения (в стостоянии чата, в соответсвующих сообщениях чата)
List<WMMessage> Messages  // Новые сообщения измененных чатов и сообщения новых чатов

 

Класс ответа на запрос  отсылки оффлайн данных WMSyncChanges

Свойства:

List<WMSyncBlob> SentChats // Список пар ид чатов, подтвержденных сервером
List<WMSyncBlob> SentMessages // Список пар ид сообщений, подтвержденных сервером
List<string> RejectedChats // Список ид чатов, которые при синхронизации были отвергнуты сервером и удалены из хранилища
List<string> RejectedMessages // Список ид сообщений, которые при синхронизации были отвергнуты сервером и удалены из чата и хранилища

 

Класс для представления изменений идентификаторов WMSyncBlob

Свойства:

string Previous // Уникальный идентификатор объекта до отправки на сервер
string Current // Уникальный идентификатор объекта, выданный сервером после вызова отсылки оффлайн сообщений

 

Класс-обертка над возвращаемыми данными асинхронных методов WMAPIResponse<T>:

Свойства:

bool Successful // Статус действия, false, когда сервер ответил ошибкой. True, если действие выполнилось с помощью сервера или без сети - локально.
WMBaseSession.WMSessionError WebimError // Возможная ошибка, возвращаемая сервером. WMSessionErrorUnknown - нет ошибки, WMSessionErrorNetworkError - ошибка сети (нет сети, таймаут и прочие)
int StatusCode // Статус код http запроса
string ReasonPhrase // Строка ответа сервера (в случае ошибки), может быть пустой
T ResponseData // Данные, предполагаемые для ответа на запрос


 

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

Для работы с оффлайн-обращениями необходимо создать экземпляр класса WMOfflineSession и держать на него ссылку. Конструктор принимает следующие аргументы:

WMOfflineSession(string account, string location, string token, string platform)

account - название аккаунта в системе Webim.ru, например, "demo"
location - выбранная локация
token - токен девайса или пуш-токен, используется для идентификации пользователя
platform - опциональный параметр платформы.

Следом за конструктором и перед первым доступом к остальным методам сессии необходимо её инициализировать методом

async Task Initialize()

После завершения данного метода можно считать, что данные загружены и класс готов работать в режиме оффлайн-сессии.

 


 

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

У объекта можно запросить список чатов методом

List<WMChat> ChatsList()

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

Список чатов обновляется вызовом метода

async Task<WMAPIResponse<WMHistoryChanges>> GetHistoryAsync()

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

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

async Task<WMAPIResponse<WMSyncChanges>> SendUnsentRequestsAsync()

Ошибки, описываемые SDK, следующие:

enum WMSessionError {
WMSessionErrorUnknown,
WMSessionErrorReinitRequired,
WMSessionErrorServerNotReady,
WMSessionErrorAccountBlocked,
WMSessionErrorVisitorBanned,
WMSessionErrorNetworkError,
WMSessionErrorNotConfigured,
WMSessionErrorAttachmentTypeNotAllowed,
WMSessionErrorAttachmentSizeExceeded,
WMSessionErrorMessageSizeExceeded,
WMSessionErrorResponseDataError,
}

При необходимости найти объект WMChat, которому соответствует объект WMMessage (как, например, Messages из ответа GetHistoryAsync()), можно использовать метод:

WMChat ChatForMessage(WMMessage message)

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

async Task<WMAPIResponse<WMMessage>> SendMessageAsync(string text, WMChat chat, string departmentKey)

text - ненулевая строка сообщения чата
chat - объект чата, в который необходимо добавить сообщение. В случае, когда он не задан, создается новый чат с этим сообщением
departmentKey - необязательный параметр, задает отделение, к которому будет обращен чат. Отделения заранее настраиваются в админке аккаунта.

Возвращаемый объект сообщения может иметь статус NotSent, что свидетельствует о том, что возникли проблемы при отсылки сообщения. Причину отказа можно посмотреть в поле WMAPIResponse.error. Сообщение будет сохранено локально.

Аналогично работает метод отсылки файла, только на вход принимает сырые данные файла, имя и стандартный MIME-type:

async Task<WMAPIResponse<WMMessage>> SendFileAsync(byte[] fileData, string fileName, string mimeType, WMChat chat, string departmentKey)

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

Uri AttachmentUriForMessage(WMMessage message)

Необходимо учитывать, что локальное сообщение будет указывать на полный путь до временного файла на диске.

Если пользователь прочитал все сообщения чата, то чат нужно/можно пометить прочитанным:

async Task<WMAPIResponse<bool>> MarkChatAsReadAsync(WMChat chat)

Для удаления чата используется метод:

async Task<WMAPIResponse<bool>> DeleteChatAsync(WMChat chat)