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

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

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

Обычно это делается в собственном классе 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 - имя бота, оправившего приветственного сообщения (если есть)

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

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

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

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

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

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.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.withAdditionalData(mapOf(
            "comment" to "System comment"
        ))
        ChatHDE.startVisitorChat(wrap)
    }
)

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

ChatView(
    ...
    onClickSendMessage = { txt ->
        var message = VisitorMessage(text = txt)
        if (ChatHDE.isUserMessageHistoryEmpty()) {
            message = message.withAdditionalData(mapOf("comment" to "System comment"))
        }
        ChatHDE.sendMessage(message)
    }
)

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

val chatButtonsAction = remember {  ChatButtonActions() }
chatButtonsAction.on(ButtonTypes.TEXT) {btn ->
    var message = VisitorMessage(text = btn.text)
    if (ChatHDE.isUserMessageHistoryEmpty()) {
        message = message.withAdditionalData(mapOf("comment" to "System comment"))
    }
    ChatHDE.sendMessage(message)
}

ChatView(
    ...
    chatButtonsActions = chatButtonsActions
)

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

ChatHDE.isUserMessageHistoryEmpty()

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

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

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

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

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

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

val savedData = ChatHDE.getSavedData()

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

ChatHDE.setSavedData(savedData)
...

ChatHDE.connect()

caution

Данные функции корректно работают только при saveUserAfterConnection = true, задаваемом в ChatHDE.init(...)

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

ChatHDE.clearSavedData()