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

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

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

Метод 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
)

Логирование

С помощью ChatLogger.handler можно дополнительно передавать сообщения SDK в собственную систему логирования или аналитики. Стандартный вывод в консоль при этом сохраняется. Параметр logs: true при инициализации включает подробные диагностические сообщения SDK.

ChatLogger.handler = { message in
    print(message)
}

Обработчик вызывается для каждого сообщения, которое SDK передаёт в ChatLogger. Чтобы удалить обработчик, установите ChatLogger.handler = nil.

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

Во время работы 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)
}

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

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)
    }
}

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

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 поддерживает сохранение и восстановление дополнительного состояния чата, которое не приходит с сервера при повторном подключении. К таким данным относятся, например:

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

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

if let savedData = await ChatHDE.shared.getSavedData() {
    // Сохраните savedData
}

ChatSavableData можно преобразовать в Data методом encoded() и сохранить, например, в UserDefaults:

if let savedData = await ChatHDE.shared.getSavedData(),
   let data = savedData.encoded() {
    UserDefaults.standard.set(data, forKey: "chatState")
}

Для восстановления используйте ChatSavableData.decode(from:). Восстановить состояние необходимо до подключения:

if let data = UserDefaults.standard.data(forKey: "chatState"),
   let savedData = ChatSavableData.decode(from: data) {
    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()
            }
        }
    }
}