iOS SDK

Требования#

• iOS 15.0+ (более точные детенты листа на iOS 16+, с системным запасным вариантом ниже).
• Swift 5.9+.
• Ноль сторонних зависимостей — только Foundation, Swift Concurrency, SwiftUI и UIKit.

Вы зависите от продукта RespondoSDK, который реэкспортирует кросс-платформенный RespondoCore.

Установка#

Добавьте пакет через Swift Package Manager. В Xcode: File → Add Package Dependencies… и введите https://github.com/respondo-app/sdk-ios, либо объявите его в своём Package.swift, затем зависьте от продукта RespondoSDK.

dependencies: [
    .package(url: "https://github.com/respondo-app/sdk-ios", from: "0.1.0")
],
targets: [
    .target(
        name: "MyApp",
        dependencies: [
            .product(name: "RespondoSDK", package: "sdk-ios")
        ]
    )
]

Затем импортируйте его в коде:

import RespondoSDK

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

Инициализируйте один раз при запуске, затем вызывайте Respondo.open() где угодно. Метод жизненного цикла — initialize (слово init зарезервировано языком).

import SwiftUI
import RespondoSDK

@main
struct MyApp: App {
    init() {
        Respondo.initialize(
            RespondoConfig(
                agentId: "<agent-uuid>",
                channelId: "<channel-uuid>"
                // baseUrl nil -> https://api.respondo.ai
            )
        )
    }

    var body: some Scene {
        WindowGroup {
            Button("Support") { Respondo.open() }
        }
    }
}

Фасад Respondoпотокобезопасен. Вызовы, сделанные сразу после initialize, ставятся в очередь и применяются, как только завершится асинхронная инициализация.

Идентификация пользователей#

По умолчанию каждый посетитель анонимен. При первом запуске SDK генерирует стабильный visitor_id и держит его в keychain, поэтому вернувшийся пользователь снова находит свой диалог. Никакого API-ключа встраивать не нужно — каждый диалог защищён session-токеном на диалог, который backend выпускает и сдвигает вперёд на каждом сообщении, так что анонимному посетителю никогда не приходится проходить аутентификацию заново.

Вызовите identify, как только пользователь вошёл. Это привязывает его настоящую личность, поэтому его история следует за ним между устройствами и переустановками, а имя и email показываются рядом с диалогом в вашем инбоксе вместо анонимного посетителя.

userHash — это подпись, которую ваш backend вычисляет из identity_secret агента — HMAC-SHA256(secret, userId) (или email, если userId нет), закодированная как hex в нижнем регистре. Секрет доказывает подлинность личности, поэтому он должен жить только на вашем backend и никогда не поставляться в приложении. Полную формулу и серверные примеры смотрите на странице Проверка личности.

// userHash приходит с вашего backend (HMAC-SHA256 по userId) —
// никогда не вычисляйте его в приложении.
Respondo.identify(
    RespondoIdentity(
        userId: session.userId,
        email: session.email,
        name: session.fullName,
        userHash: session.respondoUserHash
    )
)

// При выходе: отзовите сессию и начните нового анонимного посетителя.
Respondo.reset()

Если хеш отсутствует или неверен, ничего не падает: backend молча оставляет посетителя анонимным, чат продолжает работать, и вы просто теряете кросс-девайс-связь, пока не будет передан валидный хеш. Проверка запускается только тогда, когда у агента задан identity_secret — оставьте его пустым при разработке, и userId / email будут приняты как есть.

Наблюдаемые значения и делегат#

Читайте состояние как синхронные геттеры, реактивные AsyncStreamы или через RespondoDelegate. Стримы и коллбэки делегата приходят на главном акторе.

// Реактивный поток числа непрочитанных.
Task {
    for await count in Respondo.unreadCountStream {
        updateBadge(count)
    }
}

// Делегат для бейджей и запасных вариантов диплинков.
final class SupportCoordinator: RespondoDelegate {
    init() { Respondo.delegate = self }
    func respondoUnreadChanged(_ count: Int) {
        UIApplication.shared.applicationIconBadgeNumber = count
    }
}

Отслеживание экрана#

Сообщайте текущий экран при каждой навигации, чтобы проактивные тизеры и таргетинг уровня страницы могли по нему срабатывать (static func setCurrentScreen(_ name: String?)). Передайте nil, чтобы очистить его; при каждом изменении проактивный тизер пересчитывается для нового экрана.

Respondo.setCurrentScreen("pricing")

Дальнейшие шаги#

Подключите Пуш-уведомления и Проверку личности. UIKit-обёртка RespondoChatViewController, полная поверхность делегата и решение проблем разобраны в гайде по началу работы с iOS SDK; исходники SDK открыты на GitHub.