Инструкции по миграции

Переход на версию 5.0.0

Подключение через CocoaPods

Название пода поменялось на ChatCenterUI, версия 5.0.0.

Конфигурация ChatCenterUI

В этой версии API SDK несовместим с версиями 4.x. Пример настройки — в демо-приложении.

Основные шаги остались прежними:

1. Настройка подключения к серверу:

   let chatTransportConfig = ChatTransportConfig(rest: "restURL",
                                                 webSocket: "webSocketURL",
                                                 dataStore: "dataStoreURL")

2. Настройка параметров сетевого подключения:

   var chatNetworkConfig = ChatNetworkConfig()
   chatNetworkConfig.sslPinning.allowUntrustedSSLCertificate = true

3. Настройка параметров работы чата:

   var chatConfig = ChatConfig(transportConfig: chatTransportConfig,
                               networkConfig: chatNetworkConfig)
   chatConfig.searchEnabled = true
   chatConfig.voiceRecordingEnabled = true
   chatConfig.linkPreviewEnabled = true
   chatConfig.keepSocketActive = true

4. Инициализация SDK:

   let chatCenterSDK = ChatCenterUISDK(providerUid: "YOUR_PROVIDER_UID",
                                       chatConfig: chatConfig,
                                       loggerConfig: ChatLoggerConfig(logLevel: .all))

5. Настройка тем оформления:

   chatCenterSDK.theme = makeLightTheme()
   chatCenterSDK.darkTheme = makeDarkTheme()

Настройка внешнего вида

Внешний вид настраивается через темы (светлая и тёмная). В SDK три уровня кастомизации:

1. Минимальный — настройка цветов, шрифтов и/или изображений (например, под корпоративные цвета).
2. Покомпонентный — настройка компонентов дизайн-системы SDK (переиспользуемые элементы, например кнопка).
3. Точечный — детальная настройка flow (экраны чата или поиска), когда настраивается внешний вид конкретного элемента на экране.

Уровни имеют вложенную структуру:

let components = ChatComponents(images: ChatImages(), colors: ChatColors(), typography: ChatTypography())
let theme = ChatTheme(components: components)
// theme.flows доступен для детальной настройки сценариев

Нижние уровни имеют более высокий приоритет: значение, заданное в ChatFlow, перекроет значение из ChatColors.

Переход на версию 5.3.0

В версии 5.3 типы и свойства дизайн-системы переименованы к единому стилю. После 5.3 в минорных релизах добавляются только обратно-совместимые изменения.

Что поменялось:

• 15 типов сохранены как @available(*, deprecated) typealias'ы — старый код собирается с предупреждением. Для 14 из 15 алиасов атрибут не содержит renamed:, поэтому Fix-It замену не предложит. Для SystemMessagesStyles → ChatSystemMessagesStyles Fix-It срабатывает.
• Часть свойств переименована для унификации (в имена добавлены Color, Style и т.п.). Xcode выдаст предупреждение, Fix-It не сработает.

Переименуйте старые имена вручную по таблице ниже.

Переименованные типы (deprecated алиасы)

Старые имена сохранены как алиасы и помечены @available(*, deprecated). Будут удалены в следующем мажорном релизе.

Старое имя (deprecated)	Актуальное имя
AudioMessageStyle	AudioChatMessageStyle
AudioPlayerChatStyle	AudioPlayerStyle
ButtonChatStyle	ButtonStyle
FileMessageStyle	FileChatMessageStyle
IconButtonChatStyle	IconButtonStyle
ImageMessageStyle	ImageChatMessageStyle
InputChatTextStyle	ChatInputTextStyle
InputChatVoiceStyle	ChatInputVoiceStyle
InputViewStyle	ChatInputStyle
PhotoPickerStyle	ChatMenuStyle (см. примечание ниже)
PlaceholderChatStyle	ChatPlaceholderStyle
SearchBarChatStyle	SearchBarStyle
SystemMessagesStyles	ChatSystemMessagesStyles
TextChatStyle	ChatTextStyle
TextMessageStyle	TextChatMessageStyle

См. также Известные ограничения.

Структура отдельных стилей изменилась — например, у голосовых сообщений (ChatInputVoiceStyle). Сверьте свой код с актуальным API стиля.

Для создания стилей добавлен статический метод build — создаёт стиль и настраивает его через замыкание:

// Создание компонентов дизайн-системы
let components = ChatComponents.build { components in
    components.searchBarStyle.cancelButtonStyle.color.normal = .black
    components.loadingChatStyle.indicatorStyle.backgroundColor = .systemGray3
    components.loadingChatStyle.indicatorStyle.cornerRadius = 20.0
    components.audioPlayerStyle.playButtonStyle.image = ChatImage(system: "play.fill", tintColor: .red)
    components.audioPlayerStyle.pauseButtonStyle.image = ChatImage(system: "pause.fill", tintColor: .green)
    components.audioPlayerStyle.progressViewStyle.color = .black
    components.audioPlayerStyle.progressViewStyle.backgroundColor = .yellow
}

Метод apply меняет свойства существующего стиля через замыкание — без промежуточной переменной:

// Применение настроек для экрана поиска
theme.flows.searchFlow.apply {
    $0.navigationBarStyle = NavigationBarStyle.build(with: components, configure: {
        $0.hidden = false
    })
    $0.searchMessageStyle.apply {
        $0.matchTextStyle = .init(font: UIFont.systemFont(ofSize: 20), color: .systemGreen)
        $0.nextImage = ChatImage(system: "chevron.forward", tintColor: .systemGreen)
    }
    $0.navigationBarStyle.searchBarStyle.cancelButtonStyle.color.normal = .red
    $0.notFoundTextStyle = ChatTextStyle(font: typography.message, color: .red)
}

Ограничение apply для общих компонентов

Применение apply к компонентам из ChatComponents через flow меняет их глобально по всей теме. Чтобы изменить компонент только в одном flow, создайте отдельный экземпляр и присвойте его локально.

Переход на версию 5.4.0

Новые публичные API

• Добавлен стиль OpenGraphViewStyle для оформления превью OpenGraph-ссылок в сообщениях. Настраивается через theme.flows.chatFlow.outcomeMessages.textMessageStyle.openGraphStyle (для исходящих) и theme.flows.chatFlow.incomeMessages.textMessageStyle.openGraphStyle (для входящих).
• Добавлен метод chatCenterUI(chatCenter:didLog:) в ChatCenterUISDKDelegate. Если делегат назначен, SDK передаёт в него свои логи — пригодится для проброса в Sentry, Datadog или внешний логгер. Все методы делегата имеют пустые дефолтные реализации, поэтому реализация didLog опциональна.
• Добавлен параметр ChatConfig.shouldUseRemoteConfig (по умолчанию true). При false SDK использует только локальные значения keepSocketActive, keepSocketActiveDuringOperatorSession и других — серверный channelConfig игнорируется. Установите false, если хотите гарантированно использовать локальные настройки.

Совместимость

Внешних breaking changes нет — обновление с 5.3.x совместимо на уровне исходного кода.

---

Переход на версию 5.5.0

Новые публичные API

• Добавлено свойство QuoteStyle.backgroundCornerRadius: CGFloat — скругление углов фона цитаты.

Исправления

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

Совместимость

Внешних breaking changes нет — обновление с 5.4.x совместимо на уровне исходного кода.

---

Переход на версию 5.6.0

Новые методы

Предзаполнение поля ввода

Добавлен метод prefill(message:) для подстановки текста в поле ввода перед открытием чата:

chatCenterSDK.prefill(message: "Вопрос по заказу №12345")
do {
    let chatController = try chatCenterSDK.getChat()
    // текст будет в поле ввода
} catch {
    // см. getting-started/open_chat.md
}

Текст подставляется однократно при следующем вызове getChat(), после чего сбрасывается.

Изменения в дизайн-системе

Кнопка прокрутки вниз

У ScrollToMessageButtonStyle добавлено свойство alwaysShow: Bool (по умолчанию false). При true кнопка прокрутки вниз отображается всегда, в том числе без непрочитанных сообщений:

let chatFlow = theme.flows.chatFlow
chatFlow.scrollToBottomUnreadMessagesButtonStyle.alwaysShow = true

Стиль кнопок опросов

Свойство questionBackgroundColor в SurveyChatMessageStyle помечено как устаревшее. Вместо него используйте questionButtonColor, поддерживающее состояния normal/highlighted/disabled:

let surveyStyle = theme.flows.chatFlow.systemMessages.surveyMessageStyle
surveyStyle.questionButtonColor.normal = .systemGreen
surveyStyle.questionButtonColor.highlighted = .systemGreen.withAlphaComponent(0.7)
surveyStyle.questionButtonColor.disabled = .systemGray

Обновлённые опросы

Интерфейс опросов переработан. Со стороны интегратора настройка не требуется — изменения применяются автоматически:

• Поле ввода блокируется на время активного опроса.
• Кнопки в опросах теперь подсвечиваются при нажатии.
• Поведение, управляемое сервером: поле для комментария (порог через payload clientCommentThreshold), автоматическое скрытие опроса (hideAfter), отправка ответов одним сообщением на .api21+. В публичном API SDK этих параметров нет — настройка через edna.

Ограничение длины сообщения

Поле ввода теперь ограничивает длину сообщения до 4000 символов на уровне UI (ранее ограничение применялось только при отправке). Вставка текста, превышающего лимит, автоматически обрезается.

Переход на версию 5.7.0

Обновление данных пользователя после авторизации

У ChatUser появился метод updateData(data:) — обновляет данные пользователя без повторного вызова authorize:

var chatUser = ChatUser(identifier: "user_uuid", name: "Иван Иванов")
chatCenterSDK.authorize(user: chatUser)

// Позднее — когда дополнительные данные готовы
chatUser.updateData(data: ["email": "ivan@example.ru", "segment": "vip"])

Обновление уйдёт на сервер при следующем viewDidAppear экрана чата.

Используйте ту же переменную, что передали в authorize

Метод mutating — переменная ChatUser должна быть var. Вызывайте updateData на той же chatUser, которую передали в authorize(user:). Если переприсвоить chatUser = ChatUser(...) и вызвать updateData на новом значении, SDK обновления не увидит.

Исправления

• Исправлена очистка быстрых ответов при смене режима отображения (inline/toolbar)
• Исправлена видимость кнопки поиска в навигационной панели при одновременном включении кнопки клавиатуры и поиска

---

Переход на версии 5.8.0 / 5.8.1 / 5.8.2

Внешних breaking changes нет. Обновление с 5.7.x совместимо на уровне исходного кода. Подробности — в списке изменений:

• 5.8.0 — публичный API не изменился, внутренние улучшения.
• 5.8.1 — фикс гонки при обновлении данных пользователя до установки WebSocket-соединения.
• 5.8.2 — фикс отключения WebSocket при открытии чата по push-уведомлению; уточнения в документации.

---

Замечания, актуальные для всех версий 5.x

ChatLogLevel — OptionSet, не enum

ChatLogLevel — это public struct ChatLogLevel: OptionSet. Следствия:

• Корректные значения: .off, .info, .rest, .webSocket, .userInterface, .error, .network, .all.
• Можно комбинировать через массивный литерал: [.info, .error] → только info и error.
• switch logLevel { case .all: ... } не работает — для проверок используйте logLevel.contains(.error).

// Корректно
let logger = ChatLoggerConfig(logLevel: [.info, .error])
if logger.logLevel.contains(.network) {
    // ...
}

Если в старом коде ChatLogLevel использовался как enum (switch/case .all), перепишите на contains(...).

ChatConfig — устаревшие свойства

Свойства searchEnabled, voiceRecordingEnabled, linkPreviewEnabled, keepSocketActive, keepSocketActiveDuringOperatorSession, scrollToLatest, historyLoadingCount, showAttachButton, surveyCompletionDelay дублируются серверным channelConfig. По умолчанию (shouldUseRemoteConfig = true) серверные значения переопределяют локальные. Подробности — в Настройках SDK.

Xcode не покажет предупреждение

Эти свойства помечены устаревшими только в doc-комментариях, без атрибута @available. Xcode не покажет strikethrough и Fix-It — ориентируйтесь на список выше и таблицу в chat_config.md.