Android Usedesk SDK (v3.11.0)

!Важно! В версии 3.10.5 изменены методы работы с библиотекой. О всех особенностях обновления со старых версий читайте тут.

Подключение к проекту
Локализация
Чат
База знаний
Локализация GUI
Предыдущие версии

Подключение к проекту

Минимальная версия Android 4.4 (API 19)

Chat SDK - библиотека для работы с чатом.

Chat GUI - библиотека для встраивания готовых элементов интерфейса чата (включает в себя Chat SDK).

KnowledgeBase SDK - библиотека для работы с Базой Знаний.

KnowledgeBase GUI - библиотека для встраивания готовых элементов интерфейса чата (включает в себя KnowledgeBase SDK).

Usedesk Sample App - пример использования библиотеки.

Добавьте в build.gradle вашего проекта строку:

allprojects {
    repositories {
        ...
        maven { url "https://jitpack.io" }
    }
}

Добавьте в dependencies build.gradle вашего модуля строки:

//sdk чата
implementation "com.github.Usedesk.Android_SDK:chat-sdk:$usedeskSdkVersion"
//графический интерфейс чата
implementation "com.github.Usedesk.Android_SDK:chat-gui:$usedeskSdkVersion"
//sdk базы знаний
implementation "com.github.Usedesk.Android_SDK:knowledgebase-sdk:$usedeskSdkVersion"
//графический интерфейс базы знаний
implementation "com.github.Usedesk.Android_SDK:knowledgebase-gui:$usedeskSdkVersion"

Добавьте в файл Manifest:

<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.CAMERA" />

Чат

Конфигурация

Для работы с чатом необходимо задать конфигурацию:

UsedeskChatSdk.setConfiguration(UsedeskChatConfiguration(...)

UsedeskChatConfiguration - конфигурация чата:

Переменная	Тип	Описание
urlChat *	String	Адрес сервера Чата
urlOfflineForm *	String	Адрес для отправки формы обратной связи. Стандартное значение `https://secure.usedesk.ru/`
urlToSendFile *	String	Адрес для отправки файлов. Стандартное значение `https://secure.usedesk.ru/uapi/v1/`
companyId *	String	Идентификатор компании
channelId *	String	Идентификатор канала
clientToken	String?	Токен, позволяющий однозначно идентифицировать клиента в системе. Указав null библиотека самостоятельно воспользуется сохранённым токеном на устройстве, использованным ранее с такими же полями `clientEmail`, `clientPhoneNumber`, `clientName` в конфигурации. Для первого входа указывается null, для последующих - полученный с сервера токен
clientEmail	String?	Почта клиента
clientName	String?	Имя клиента
clientNote	String?	Заметка о клиенте
clientPhoneNumber	Long?	Телефонный номер клиента
clientAdditionalId	String?	Дополнительный идентификатор клиента
clientInitMessage	String?	Сообщение, автоматически отправляемое от клиента при открытии чата
additionalFields	Map<Long, String>	Коллекция дополнительных полей, где key - Id поля, value - значение поля. Значения поля зависят от типа, для чекбоксов - `"true"` / `"false"`, для списков - текст, точно совпадающий с текстом значения списка, для текста - любой текст.
additionalNestedFields	List<Map<Long, String>>	Список коллекций вложенных списков, где каждый элемент списка - это коллекия значений одного вложенного списка, где key - Id поля, value - значение поля с текстом, точно совпадающим с текстом значения списка.

* - обязательный параметр

Для включения локальных уведомлений нужно создать 2 собственных класса:

Сервис, унаследованный от UsedeskSimpleNotificationsService (обычный сервис) или UsedeskForegroundNotificationsService (foreground сервис). Где можно переопределить некоторые методы:

Метод	Тип возвращаемого значения	Описание события
getContentPendingIntent	PendingIntent?	Действие при нажатии на уведомление
getDeletePendingIntent	PendingIntent?	Действие при удалении уведомления
getClosePendingIntent	PendingIntent?	Действие при закрытии foreground уведомления
getChannelId	String	Номер канала уведомления
getChannelTitle	String	Названия канала уведомления
createNotification	Notification?	Создание уведомления

Фабрику, унаследованную от UsedeskNotificationsServiceFactory для переопределения метода:

Метод	Тип возвращаемого значения	Описание события
getServiceClass	Class<?>	Класс сервиса

После чего указать SDK использовать фабрику:

UsedeskChatSdk.setNotificationsServiceFactory(CustomNotificationsServiceFactory())

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

Для использования готового пользовательского интерфейса чата воспользуйтесь UsedeskChatScreen , например при помощи метода newInstance:

supportFragmentManager.beginTransaction()
    .replace(
        R.id.container, 
        UsedeskChatScreen.newInstance(customAgentName, rejectedFileTypes, chatConfiguration)
    ).commit()

Для использования с Jetpack Navigation можно воспользоваться методом createBundle, например:

navController.navigate(
    R.id.action_configurationScreen_to_usedeskChatScreen,
    UsedeskChatScreen.createBundle(customAgentName, rejectedFileTypes, chatConfiguration)
)

Методы newInstance и createBundle принимают следующие аргументы:

Аргумент	Тип
customAgentName	String?	Если задан, то все имена агентов в чате будут заменены на значение параметра.
rejectedFileTypes	Collection?	Список расширений файлов, помечаемых как опасные (метод `onFileClick` родителя вызывается в любом случае).
chatConfiguration	UsedeskChatConfiguration?	Если задан, то `UsedeskChatScreen` берёт на себя обязанность вызова метода `UsedeskChatSdk.setConfiguration`.

Для полноценной работы фрагмента необходимо:

Передавать события onBackPressed, вызывая аналогичный метод у фрагмента, который вернёт true если событие было обработано, либо false если нет, например:

override fun onBackPressed() {
    val fragment = getCurrentFragment()
    if (fragment is UsedeskFragment && fragment.onBackPressed()) {
        return
    }
}

Для привязки жизненного цикла ViewModel к родителю необходимо расширить интерфейс IUsedeskChatViewModelStoreOwner .
Расширить интерфейс IUsedeskOnFileClickListener родителем, переопределив метод onFileClick, например:

override fun onFileClick(usedeskFile: UsedeskFile) {
    supportFragmentManager.beginTransaction()
        .replace(R.id.container, UsedeskShowFileScreen.newInstance(usedeskFile))
        .commit()
    //или
    navController.navigate(
        R.id.action_usedeskChatScreen_to_usedeskShowFileScreen,
        UsedeskShowFileScreen.createBundle(usedeskFile)
    )
}

Расширить интерфейс IUsedeskOnDownloadListener родителем, переопределив метод onDownload.

Для корректной работы прикрепления фото с камеры необходимо добавить в файл AndroidManifest.xml следующие строки:

<provider
    android:name="androidx.core.content.FileProvider"
    android:authorities="${applicationId}.provider"
    android:exported="false"
    android:grantUriPermissions="true">
    <meta-data
        android:name="android.support.FILE_PROVIDER_PATHS"
        android:resource="@xml/usedesk_provider_paths" />
</provider>

Для возможности отображения видео во весь экран необходимо расширить интерфейс IUsedeskOnFullscreenListener

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

После установки конфигурации нужно проинициализировать чат:

val usedeskChat = UsedeskChatSdk.init(requireContext())

После инициализации можно получить экземпляр IUsedeskChat вызвав:

val usedeskChat = UsedeskChatSdk.requireInstance()

Теперь можно добавлять слушателей событий:

val listener = object : IUsedeskActionListener{...}
usedeskChat.addListener(listener)

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

usedeskChat.removeListener(listener)

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

UsedeskChatSdk.release(false)

Если передать в метод значение false, то ресурсы будут освобождены только в том случае, если все слушатели были удалены. Если передать значение true, то ресурсы будут свобождены немедленно. Попытка получить экземпляр без инициализации или после освобожения вызовет исключение.

IUsedeskActionListener - интерфейс для прослушивания событий чата:

Метод	Параметры	Описание события
onConnectionState	UsedeskConnectionState	Состояние подключения к серверу
onMessageReceived	UsedeskMessage	Каждое сообщение
onNewMessageReceived	UsedeskMessage	Каждое новое сообщение
onMessagesReceived	List<UsedeskMessage>	Список сообщений из чата при каждом изменении
onMessageUpdated	UsedeskMessage	Обновление полученного ранее сообщения
onFeedbackReceived	-	Отзыв доставлен
onOfflineFormExpected	UUsedeskOfflineFormSettings	Ожидается Форма Обратной Связи
onException	UsedeskException	Возникшее исключение

IUsedeskActionListenerRx - класс для прослушивания событий чата:

Метод	Параметры	Описание события
onConnectionStateObservable	Observable<UsedeskConnectionState>	Состояние подключения к серверу
onMessageObservable	Observable<UsedeskMessage>	Каждое сообщение
onNewMessageObservable	Observable<UsedeskMessage>	Каждое новое сообщение
onMessagesObservable	Observable<List<UsedeskMessage>>	Список сообщений из чата на момент подключения
onMessageUpdateObservable	Observable<UsedeskMessage>	Обновление полученного ранее сообщения
onFeedbackObservable	Observable<UsedeskEvent<Any?>>	Отзыв доставлен
onOfflineFormExpectedObservable	Observable<UsedeskOfflineFormSettings>	Ожидается Форма Обратной Связи
onExceptionObservable	Observable<Exception>	Возникшее исключение

Запуск сервиса уведомлений:

UsedeskChatSdk.startService(context)

Остановка сервиса уведомлений:

UsedeskChatSdk.stopService(context)

Для логирования ошибок обработки ответов сервера можно воспользоваться классом UsedeskLog:

enable() - включение логирования.
disable() - выключение логирования.
addLogListener(logListener: (String) -> Unit) - добавление слушателя логов.
removeLogListener(logListener: (String) -> Unit) - удаление слушателя логов.

База знаний

Конфигурация

Для работы с SDK Базы Знаний необходимо задать конфигурацию:

UsedeskKnowledgeBaseSdk.setConfiguration(UsedeskKnowledgeBaseConfiguration(...))

UsedeskKnowledgeBaseConfiguration - конфигурация Базы Знаний:

Переменная	Тип	Описание
urlApi *	String	Адрес api сервера. Стандартное значение `https://api.usedesk.ru/`
accountId *	String	Идентификатор Базы Знаний в системе
token *	String	Токен доступа к API
clientEmail	String?	Email клиента
clientName	String?	Имя клиента

* - обязательный параметр

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

Для использования готового пользовательского интерфейса воспользуйтесь UsedeskKnowledgeBaseFragment , например при помощи метода newInstance:

supportFragmentManager().beginTransaction()
    .replace(
        R.id.container, 
        UsedeskKnowledgeBaseFragment.newInstance(
            withSupportButton, 
            withArticleRating, 
            knowledgeBaseConfiguration
        )
    ).commit()

Для использования с Jetpack Navigation можно воспользоваться методом createBundle, например:

navController.navigate(
    R.id.action_configurationScreen_to_usedeskKnowledgeBaseScreen,
    UsedeskKnowledgeBaseScreen.createBundle(
        withSupportButton, 
        withArticleRating, 
        knowledgeBaseConfiguration
    )
)

Для полноценной работы фрагмента необходимо:

Передавать события onBackPressed, вызывая аналогичный метод у фрагмента, который вернёт true если событие было обработано, либо false если нет, например:

override fun onBackPressed() {
    val fragment = getCurrentFragment()
    if (fragment is UsedeskFragment && fragment.onBackPressed()) {
        return
    }
}

Реализовать интерфейс IUsedeskOnSupportClickListener родителем, переопределив метод onSupportClick(), например:

override fun onSupportClick() {
    supportFragmentManager().beginTransaction()
        .replace(R.id.container, UsedeskChatScreen().newInstance())
        .commit()
}

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

После установки конфигурации необходимо инициализировать Базу Знаний:

val usedeskKnowledgeBase = UsedeskSdk.initKnowledgeBase(context)

После этого можно получить объект класса в любом месте:

val usedeskKnowledgeBase = UsedeskKnowledgeBase.requireInstance()

Освободить объект:

UsedeskKnowledgeBaseSdk.release()

Попытка получить экземпляр без инициализации или после освобожения вызовет исключение.

Локализация GUI

SDK поддерживает следующие языки:

английский (по умолчанию),
русский,
испанский,
португальский.

Помимо этого можно изменить существующий язык или добавить новый. Для этого необходимо скопировать значения из файла strings_template.xml , который находится в корне проекта, и добавить во все файлы strings.xml вашего проекта. После чего можно подставить свои значения строковых ресурсов. Важно! В случае изменения ссылок на строковые ресурсы при кастомизации приложения изменение строковых ресурсов таким способом может не привеcти к желаемому результату.

Предыдущие версии

v3.9.0

anatoliyRodkin/Android_SDK

Android Usedesk SDK (v3.11.0)

!Важно! В версии 3.10.5 изменены методы работы с библиотекой. О всех особенностях обновления со старых версий читайте тут.

Подключение к проекту

Чат

Конфигурация

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

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

База знаний

Конфигурация

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

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

Локализация GUI

Предыдущие версии