Skip to main content

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ChatHDE.shared.configure(
    serverOptions: ServerOptions.fromDomain("example.com"),
    chatOptions: ChatOptions(
        welcomeMessage: "hello",
        botName: "bot",
        saveUserAfterConnection: true,
        maxUploadFileSizeMB: 20
    ),
    ticketOptions: TicketOptions(
        showNameField: true,
        showEmailField: true,
        isEmailRequired: true,
        consentLink: "https://google.com"
    ),
    logs: true
)

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

Во время работы SDK можно задать параметры сервера

await ChatHDE.shared.setServerOptions(ServerOptions.fromDomain("example.com"))

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

await ChatHDE.shared.connect()

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

await ChatHDE.shared.disconnect()

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

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

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

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

Task { @MainActor in
    let stream = await ChatHDE.shared.messagingEventsStream()
    for await event in stream {
        if case .server(.initWidget(response: let resp)) = event {
            let userData = resp.data.userData
        }
    }
}

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

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

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

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

await ChatHDE.shared.sendMessage(VisitorMessage(text: "Hello"))

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

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

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

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

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

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

  • старта нового чата setStartVisitorChatAction
  • отправки сообщений clickSendAction
  • нажатия на текстовую кнопку clickChatButtonAction.on
  1. Передача дополнительных данных при старте чата после ввода данных пользователя.
ChatHDE.shared.setStartVisitorChatAction {data in
    let wrap = data.withAdditionalData([
        "comment": "System comment"
    ])
    await ChatHDE.shared.startVisitorChat(wrap)
}
  1. Передача дополнительных данных при отправке первого сообщения пользователя. (Стоит использовать при отсутствии стартовой страницы указания данных пользователя и его запроса)
ChatHDE.shared.clickSendAction = {txt in
    Task {
        var message = VisitorMessage(text: txt)
        if await ChatHDE.shared.isUserMessageHistoryEmpty() {
            message = message.withAdditionalData(["comment": "System comment"])
        }
        await ChatHDE.shared.sendMessage(message)
    }
}
  1. Передача дополнительных данных при нажатии на текстовую кнопку в сообщении
ChatHDE.shared.clickChatButtonAction.on(ButtonTypes.text) {btn in
    Task {
        var message = VisitorMessage(text: btn.text)
        if await ChatHDE.shared.isUserMessageHistoryEmpty() {
            message = message.withAdditionalData(["comment": "System comment"])
        }
        await ChatHDE.shared.sendMessage(message)
    }
}

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

await ChatHDE.shared.isUserMessageHistoryEmpty()

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

ChatHDE.shared.clickSendAction = {txt in
    Task {
        var message = VisitorMessage(text: txt)
        if await ChatHDE.shared.isUserMessageHistoryEmpty() {
            message.text = "Prepend message\n" + message.text
        }
        await ChatHDE.shared.sendMessage(message)
    }
}

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

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

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

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

let savedData = await ChatHDE.shared.getSavedData()

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

await ChatHDE.shared.setSavedData(savedData)
...

await ChatHDE.shared.connect()
caution

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

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

await ChatHDE.shared.clearSavedData()