Методы взаимодействия

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

Перед использованием СДК необходимо инициализировать один раз при старте приложения.

Обычно это делается в собственном классе Application в методе onCreate().

Метод ChatHDE.init(...) принимает следующие параметры:

• context - требуется передать контекст приложения
• serverOptions - данные сервера, такие как:
  • socketUrl - URL сокета
  • originUrl - исходный URL системы
  • uploadUrl - URL для загрузки файлов
  • В процессе работы приложения эти настройки можно изменить с помощью метода setServerOptions(options: ServerOptions), в качестве заглушки можно использовать любой домен

important

В большинстве стандартных установок эти параметры можно получить автоматически, вызвав: ServerOptions.fromDomain(domain: String)

Если же сервер был настроен индивидуально (нестандартные адреса для загрузки или сокета), используйте явное создание объекта ServerOptions с нужными значениями.

• chatOptions - настройки чата, такие как:

  • saveUserAfterConnection - сохранение данных пользователя после подключения и автоматическое их восстановление при подвторном открытии чата
  • maxUploadFileSizeMB - максимальный размер загружаемых файлов (в мегабайтах)
  • welcomeMessage текст приветственного сообщения (если есть)
  • botName - имя бота, оправившего приветственного сообщения (если есть)
  • maxRateCommentLength - максимальный размер комментария при оценке чата
  • rateSuccessTime - время показа сообщения об успешной оценке

• ticketOptions - настройки тикета, (по умолчанию все null, при установке значений параметров, при загрузке чата с новым пользователем, перед ичпользованим чата будет отображена страница, где нужно будет заполнить данные). Доступные параметры:

  • showNameField - показывать ли поле ввода имени
  • showEmailField - показывать ли поле ввода эл-почты
  • isEmailRequired - обязательно ли указание эл-почты
  • consentLink - ссылка на согласие на обработку персональных данных

• uiConfig - настройки UI (подробнее см. UI)

• logs - показывать ли логи (по тегу ChatSDK)

Пример использования:

ChatHDE.init(
    context = applicationContext,
    serverOptions = ServerOptions.fromDomain("example.com"),
    chatOptions = ChatOptions(
        saveUserAfterConnection = true,
        maxUploadFileSizeMB = 20
        welcomeMessage = "Здравствуйте, чем могу помочь?",
        botName = "Bot",
    ),
    ticketOptions = TicketOptions(
        showNameField = true,
        showEmailField = true,
        isEmailRequired = true,
        consentLink = "https://google.com"
    ),
    logs = true
)

Подключение к серверу

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

ChatHDE.connect()

Отключение от сервера

ChatHDE.disconnect()

Работа с пользователями

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

// Сначала указание пользователя
ChatHDE.setUser(
    UserData(
        id = "d4fa689d-ae1c-4402-800b-c234ec1078d7",
        name = "Client 123",
        email = ""
    )
)
...
// Потом подключение
ChatHDE.connect()

Присутствует возможность передавать метаданные с помощью метода ChatHDE.configureVisitorMeta. При настроенных сценариях для указания URL можно указать параметры domain и path. Настраивать метаданные требуется перед подключением. Пример:

ChatHDE.configureVisitorMeta(domain="example.com", path="/test")
ChatHDE.connect()

Данные нового пользоватея приходят от сервера в составе инициирующего сообщения. Для их получения требуется подписаться на ChatHDE.messagingEvents и отследить сообщение MessagingEvent.InitWidget (подробнее см. События)

ChatHDE.messagingEvents.collect { event ->
    if (event is MessagingEvent.InitWidget) {
        val userData = event.response.data.userData
    }
}

Чтобы открыть новый чат с новым пользователем, нужно очистить данные старого, если они были

// Сбросить данные пользователя
ChatHDE.clearUser()
...
// Подключиться заново
ChatHDE.connect()

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

Для отправки сообщения из кода, можно использовать метод sendMessage

ChatHDE.sendMessage(message = VisitorMessage("Hello!"))

Локальные сообщения

SDK поддерживает отображение виртуальных сообщений — они создаются приложением и видны только пользователю. Такие сообщения исчезают при появлении новых реальных сообщений от сервера или пользователя.

Можно добавить кастомную обработку нажатия на кнопки, см. Обработчики

ChatHDE.sendVirtualMessage(
    name = "Shop",
    text = "Выберите категорию товаров",
    chatButtons = listOf(
        ChatButton(text = "Телефоны", type = "custom"),
        ChatButton(text = "Наушники"),
        ChatButton(text = "Планшеты"),
    )
)

Передача дополнительных данных

В SDK присутствует возможность передавать дополнительные данные при отправке данных на сервер. Для этого можно передать функции в ChatView:

• старта нового чата onStartVisitorChat
• отправки сообщений onClickSendMessage
• нажатия на текстовую кнопку chatButtonsActions

1. Передача дополнительных данных при старте чата после ввода данных пользователя

ChatView(
    ...
    onStartVisitorChat = { data ->
        val wrap = data.withComment("Item: 1234")
        ChatHDE.startVisitorChat(wrap)
    }
)

2. Передача дополнительных данных в комментарии при отправке первого сообщения пользователя. (Стоит использовать при отсутствии стартовой страницы указания данных пользователя и его запроса)

ChatView(
    ...
    onClickSendMessage = { txt ->
        var message = VisitorMessage(text = txt)
        if (ChatHDE.isUserMessageHistoryEmpty()) {
            message = message.withComment("Item: 1234")
        }
        ChatHDE.sendMessage(message)
    }
)

3. Передача дополнительных данных в комментарии при нажатии на текстовую кнопку в сообщении

val chatButtonsAction = remember {  ChatButtonActions() }
chatButtonsAction.on(ButtonTypes.TEXT) {btn ->
    var message = VisitorMessage(text = btn.text)
    if (ChatHDE.isUserMessageHistoryEmpty()) {
        message = message.withComment("Item: 1234")
    }
    ChatHDE.sendMessage(message)
}

ChatView(
    ...
    chatButtonsActions = chatButtonsAction
)

Метод isUserMessageHistoryEmpty возвращает true если в чате еще не было сообщений от пользователя и при этом чат активный. Если заявка была закрыта (следующее сообщение пользователя запустит новый чат), функиця также вернет true.

ChatHDE.isUserMessageHistoryEmpty()

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

ChatView(
    ...
    onClickSendMessage = { txt ->
        val message = if (ChatHDE.isUserMessageHistoryEmpty()) {
            VisitorMessage("Prepend message\n$txt")
        } else {
            VisitorMessage(txt)
        }
        ChatHDE.sendMessage(message)
    }
)

Сохранение состояния чата

SDK поддерживает сохранение и восстановление дополнительного состояния чата, которое не приходит с сервера при повторном подключении. К таким данным относятся, например:

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

Чтобы получить текущее состояние, используйте метод:

val savedData = ChatHDE.getSavedData()

Полученное значение можно сохранить, например в Shared Preferences, затем восстановить состояние чата перед подключением.

ChatHDE.setSavedData(savedData)
...

ChatHDE.connect()

Чтобы удалить из памяти SDK данные чата, можно использовать

ChatHDE.clearSavedData()

Программная загрузка предыдущих сообщений

Для программной загрузки предыдущих сообщений можно использовать метод loadPrependTicket(). Для получения информации о наличии предыдущих тикетов можно использовать метод hasPrependTickets() Пример загрузки всей истории тикетов при открытии чата:

ChatHDE.messagingEvents.collect {event ->
    when (event) {
        is MessagingEvent.InitWidget -> {
            if (ChatHDE.hasPrependTickets()) {
                ChatHDE.loadPrependTicket()
            }
        }
        is MessagingEvent.PrependMessages -> {
            if (ChatHDE.hasPrependTickets()) {
                ChatHDE.loadPrependTicket()
            }
        }
        else -> {}
    }
}