iOS SDK

Wymagania#

• iOS 15.0+ (dokładniejsze zatrzymania arkusza na iOS 16+, z systemowym fallbackiem poniżej).
• Swift 5.9+.
• Zero zależności zewnętrznych — tylko Foundation, Swift Concurrency, SwiftUI i UIKit.

Zależysz od produktu RespondoSDK, który reeksportuje wieloplatformowy RespondoCore.

Instalacja#

Dodaj pakiet za pomocą Swift Package Manager. W Xcode: File → Add Package Dependencies… i wpisz https://github.com/respondo-app/sdk-ios, albo zadeklaruj go we własnym Package.swift, a następnie uzależnij się od produktu 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")
        ]
    )
]

Następnie zaimportuj go w kodzie:

import RespondoSDK

Inicjalizacja#

Zainicjalizuj raz przy starcie, a następnie wywołuj Respondo.open() gdziekolwiek. Metodą cyklu życia jest initialize (słowo init jest zarezerwowane przez język).

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

Fasada Respondo jest bezpieczna wątkowo. Wywołania wykonane tuż po initialize są kolejkowane i stosowane, gdy asynchroniczna inicjalizacja się zakończy.

Identyfikacja użytkowników#

Domyślnie każdy odwiedzający jest anonimowy. Przy pierwszym uruchomieniu SDK generuje stabilny visitor_id i przechowuje go w keychain, dzięki czemu powracający użytkownik odnajduje swoją rozmowę. Nie ma klucza API do osadzenia — każda rozmowa jest chroniona tokenem sesji przypisanym do rozmowy, który backend generuje i przesuwa do przodu przy każdej wiadomości, więc anonimowy odwiedzający nigdy nie musi się ponownie uwierzytelniać.

Wywołaj identify, gdy użytkownik się zaloguje. Powiązuje to jego prawdziwą tożsamość, dzięki czemu historia podąża za nim między urządzeniami i po ponownej instalacji, a jego imię i e-mail pojawiają się obok rozmowy w Twojej skrzynce zamiast anonimowego odwiedzającego.

userHash to podpis, który Twój backend oblicza z identity_secret agenta — HMAC-SHA256(secret, userId) (lub e-mail, gdy nie ma userId), zakodowany jako małe litery hex. Sekret dowodzi autentyczności tożsamości, więc musi żyć wyłącznie na Twoim backendzie i nigdy nie jest dostarczany w aplikacji. Pełny wzór i przykłady po stronie serwera znajdziesz na stronie Weryfikacja tożsamości.

// userHash pochodzi z Twojego backendu (HMAC-SHA256 z userId) —
// nigdy nie obliczaj go w aplikacji.
Respondo.identify(
    RespondoIdentity(
        userId: session.userId,
        email: session.email,
        name: session.fullName,
        userHash: session.respondoUserHash
    )
)

// Przy wylogowaniu: unieważnij sesję i rozpocznij świeżego anonimowego odwiedzającego.
Respondo.reset()

Jeśli hash jest brakujący lub błędny, nic nie zgłasza wyjątku: backend po cichu utrzymuje odwiedzającego jako anonimowego, czat nadal działa, a Ty po prostu tracisz powiązanie między urządzeniami do momentu dostarczenia poprawnego hasha. Weryfikacja działa tylko, gdy agent ma ustawiony identity_secret — pozostaw go pustym podczas developmentu, a userId / e-mail są akceptowane bez zmian.

Obserwowalne i delegat#

Odczytuj stan jako synchroniczne gettery, reaktywne AsyncStream lub przez RespondoDelegate. Strumienie i callbacki delegata docierają na main actor.

// Reaktywny strumień liczby nieprzeczytanych.
Task {
    for await count in Respondo.unreadCountStream {
        updateBadge(count)
    }
}

// Delegat dla plakietek i fallbacków deep-linków.
final class SupportCoordinator: RespondoDelegate {
    init() { Respondo.delegate = self }
    func respondoUnreadChanged(_ count: Int) {
        UIApplication.shared.applicationIconBadgeNumber = count
    }
}

Śledzenie ekranu#

Zgłaszaj bieżący ekran przy każdej nawigacji, aby proaktywne zajawki i targetowanie na poziomie strony mogły się do niego dopasować (static func setCurrentScreen(_ name: String?)). Przekaż nil, aby go wyczyścić; przy każdej zmianie proaktywna zajawka jest ponownie oceniana dla nowego ekranu.

Respondo.setCurrentScreen("pricing")

Następne kroki#

Skonfiguruj powiadomienia push i weryfikację tożsamości. Wrapper UIKit RespondoChatViewController, pełna powierzchnia delegata oraz rozwiązywanie problemów są opisane w przewodniku wprowadzającym iOS SDK; źródła SDK są publicznie dostępne na GitHub.