Webim Mobile SDK 2.0 для Windows Phone 8.1

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

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

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

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

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

Структура SDK

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

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

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

Оффлайн чаты

Методы для работы с сервером Вебим реализованы асинхронно через 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 SessionDidReceiveErrorHandler(WMSession session, WMSessionError errorID);

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

Свойства:

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

Методы:

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

Класс чата WMChat
Свойства:
Перечисления:

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

Класс сообщения 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 AuthorID // Идентификатор оператора-автора сообщения. Пустое для собственных или системных сообщений.

Методы:

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)