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 - настройки тикета, (по умолчанию поля скрыты, при установке значений параметров, при загрузке чата с новым пользователем, перед ичпользованим чата будет отображена страница, где нужно будет заполнить данные). Доступные параметры:

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

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

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

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

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.configureVisitorMeta. При настроенных сценариях для указания URL можно указать параметры domain и path. Настраивать метаданные требуется перед подключением. Пример:

await ChatHDE.shared.configureVisitorMeta(domain: "example.com", path: "/test")
await ChatHDE.shared.connect()

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

Task { @MainActor in
    let stream = await ChatHDE.shared.messagingEventsStream()
    for await event in stream {
        if case .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.withComment("Item: 1234")
    await ChatHDE.shared.startVisitorChat(wrap)
}
  1. Передача дополнительных данных в комментарии при отправке первого сообщения пользователя. (Стоит использовать при отсутствии стартовой страницы указания данных пользователя и его запроса)
ChatHDE.shared.clickSendAction = {txt in
    Task {
        var message = VisitorMessage(text: txt)
        if await ChatHDE.shared.isUserMessageHistoryEmpty() {
            message = message.withComment("Item: 1234")
        }
        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.withComment("Item: 1234")
        }
        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()

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

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

await ChatHDE.shared.connect()

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

await ChatHDE.shared.clearSavedData()

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

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

Task {@MainActor in
    for await event in await ChatHDE.shared.messagingEventsStream() {
        if case .initWidget = event {
            if await ChatHDE.shared.hasPrependTickets() {
                await ChatHDE.shared.loadPrependTicket()
            }
        }
        if case .prependMessages = event {
            if await ChatHDE.shared.hasPrependTickets() {
                await ChatHDE.shared.loadPrependTicket()
            }
        }
    }
}