Настройка SDK для Android

Android SDK имеет несколько зависимостей. Вы можете проверить уровни зависимостей прямо в Maven. Обратите внимание, что последний релиз появляется в Maven с задержкой.

Алгоритм установки библиотеки Chat2Desk в свой проект

1. Измените файл build.gradle в корне вашего проекта, чтобы добавить mavenCentral() в список репозиториев:
   
   allprojects {
    repositories {
        jcenter()
        mavenCentral() //add this line
    }
}

2. Добавьте Chat2Desk в раздел зависимостей build.gladle. Вставьте текущую версию из журнала изменений:
   
   dependencies {
    ...
    // Paste the actual version from the changelog
    implementation 'com.chat2desk:chat2desk_sdk:${Version}'
}

3. Добавите в ваш проект поддержку Java 8 в файле build.gradle:
   
   android {
    ... //other configs
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

4. Если вы ориентируетесь на устройства Android с API ниже 26, вам необходимо использовать подключаемый модуль Android Gradle версии 4.0 или новее и включить core library desugaring.

Инициализация SDK

Приложение для Android требует следующих разрешений:
<uses-permission android:name="android.permission.INTERNET"/>

Если вам нужно взаимодействовать с MediaStore или файлами мультимедиа в общем хранилище, вы должны использовать одно или несколько разрешений на хранение:

<uses-permission android:name="android.permission.READ_MEDIA_IMAGES"/>
<uses-permission android:name="android.permission.READ_MEDIA_VIDEO"/>
<uses-permission android:name="android.permission.READ_MEDIA_AUDIO"/>

Затем создайте экземпляр клиента Chat2Desk, типа IChat2Desk и инициализируйте его:

val settings = Settings(
    authToken = WIDGET_TOKEN,
    baseHost = BASE_HOST,
    wsHost = WS_HOST,
    storageHost = STORAGE_HOST
)
val chat2desk: IChat2Desk = Chat2Desk.create(settings, context)

WIDGET_TOKEN, BASE_HOST, WS_HOST, STORAGE_HOST необходимо взять со страницы Настройки > Виджет + Онлайн-чат для конкретного подключенного канала.

Удаление SDK

Используйте метод IChat2Desk.close перед удалением экземпляра IChat2Desk для предотвращения утечек памяти.

Подключение и отключение

Используйте метод IChat2Desk.start для подключения к сервису и IChat2Desk.stop для отключения от него.

Отслеживать статус подключения можно через свойство connectionStatus: Flow<ConnectionState>.

Обратитесь к этому примеру кода, чтобы понять, как это работает:

class SomeClass(private val chat2desk: IChat2Desk) {
    private val coroutineScope = CoroutineScope(Dispatchers.Main)
    
    init {
        coroutineScope.launch {
            chat2desk.connectionStatus.collect {
                println(it)
            }
        }
    }
    public suspend fun start() {
        chat2desk.start()
    }

    public suspend fun stop() {
        chat2desk.stop()
    }
}

Получение сообщений

Для работы с сообщениями необходимо, чтобы библиотека была подключена к сервису Chat2Desk.

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

Для получения списка сообщений необходимо использовать свойство messages: Flow<List<Message>>

chat2desk.messages.collect { messages ->
    println(messages)
}

Выгрузка сообщений с сервера

Для работы с сообщениями необходимо, чтобы библиотека была подключена к сервису Chat2Desk.

ВАЖНО: За раз СДК выгружает с сервера максимум 100 сообщений

1. chat2desk.fetchMessages() – получение списка последних сообщений. Выгружает 100 сообщений.
2. chat2desk.fetchNewMessages() позволяет получить список новых сообщений. При этом SDK загружает с сервера только те сообщения, которые были отправлены после последнего сообщения, полученного вашим устройством.
3. chat2desk.fetchMessage(loadMore = true) позволяет получить список старых сообщений. В этом случае SDK загружает с сервера сообщения, которые были отправлены раньше первого сообщения, уже имеющегося на устройстве, но не более 100 за один раз.

Поиск сообщений

Есть два способа поиска сообщений: полнотекстовый и поиск через операторов. Оба способа позволяют искать сообщения по свойству Message.text и возвращают список сообщений List[Message].

Полнотекстовый поиск

chat2desk.fullTextSearch(query: String): List<Message>

• Слова в запросе преобразуются в лексемы с помощью токенизатора по следующим правилам:
• Токены могут состоять только из символов ASCII и дополнения Latin-1 (западные языки). Все остальные символы считаются пробелами.
• Слова, разделенные дефисом (-), разделяются на два токена. Например, full-text разделяется на full и text.
• Токены не чувствительны к диакритическим знакам и регистру.

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

• Исключите результаты для слова, поставив перед ним символ «-». Например, fiction -science включает все результаты поиска по слову fiction и исключает те, которые содержат слово science.
• Вы можете указать префиксы, поставив символ * в конце слова. Например, fict* будет включать все результаты поиска для fiction и fictitious. Пока SDK не поддерживает поиск по суффиксам.

Поиск через операторы

chat2desk.searchByQuery(query: String, options: SearchOptions?): List<Message>

data class SearchOptions(
    /**
     * Оператор поиска
     */
    val operator: QueryStringOperator = QueryStringOperator.CONTAINS,
    /**
     * Чувствительность к регистру.
     * Только для символов ASCII и Latin-1 (западные языки)
     */
    val caseSensitivity: Boolean = false,
)

enum class QueryStringOperator {
    BEGINSWITH,
    CONTAINS,
    ENDSWITH,
    LIKE,
    EQUAL,
    NOTEQUAL
}

В настройках поиска можно указать оператор, с помощью которого будет осуществлен поиск сообщений.

Оператор	Описание
BEGINSWITH	Выражает true, если левое строковое выражение начинается с правого строкового выражения. Это похоже на contains, но совпадает только в том случае, если правое строковое выражение находится в начале левого строкового выражения.
CONTAINS	Выражает true, если правое строковое выражение встречается в любом месте левого строкового выражения.
ENDSWITH	Выражает true, если левое строковое выражение заканчивается правым строковым выражением. Это похоже на contains, но совпадает только в том случае, если левое строковое выражение находится в самом конце правого строкового выражения.
LIKE	Выражает true, если левое строковое выражение совпадает с правым строковым выражением wildcard. Строковое выражение с подстановочным знаком — это строка, в которой используются обычные символы с двумя специальными символами подстановочного знака: символ * соответствует нулю или более любых символов; подстановочный знак ? соответствует любому символу. Например, строка с подстановочным символом «d?g» соответствует словам «dog», «dig» и «dug», но не «ding», «dg» или «a dog».
EQUAL	Выражает true, если левая строка лексикографически равна правой.
NOTEQUAL	Выражает true, если левая строка не является лексикографически равной правой строке.

Отправка сообщений

Для работы с сообщениями нужно, чтобы библиотека была подключена к сервису Chat2Desk.

• Отправить сообщение: sendMessage(txt: String)

chat2desk.sendMessage(txt)
   

• Отправить сообщение с вложением: sendMessage(msg: String, attachedFile: AttachedFile) Для отправки вложения, необходимо создать экземпляр класса AttachedFile и передать его в метод.
  
  val attachedFile = AttachedFile.fromUri(
    context,
    uri,
    originalName,
    mimeType,
    fileSize
)
chat2desk.sendMessage(txt, attachedFile)

• Переотправить сообщение: resendMessage(msg: Message)

chat2desk.resendMessage(message)

Отправка информации о клиенте

Сервис позволяет отправить информацию о клиенте. По умолчанию доступны два поля name и phone.  

chat2desk.sendClientParams(name, phone)

Также сервис передает список кастомных полей, определенных в компании customFields: Flow<List<CustomField>>. 

val fields: List<CustomField>
chat2desk.customFields.collect {
  fields = it
}
chat2desk.sendClientParams(name, phone, mapOf(fields[0].id to "value"))

Остальные настройки

• Информация об операторе operator: Flow<Operator?>

chat2desk.operator.collect {operator ->
  println(operator)
}

• Получение ошибок error: Flow<Throwable?>

chat2desk.error.collect {error ->
  println(error.message)
}

Демо

Kotlin SDK Demo – демонстрирует базовый функционал SDK.