iOS SDK

Requisiti#

• iOS 15.0+ (detent dello sheet più fini su iOS 16+, con un fallback di sistema sotto).
• Swift 5.9+.
• Zero dipendenze di terze parti — solo Foundation, Swift Concurrency, SwiftUI e UIKit.

Dipendi dal prodotto RespondoSDK, che ri-esporta il modulo multipiattaforma RespondoCore.

Installazione#

Aggiungi il package con Swift Package Manager. In Xcode: File → Add Package Dependencies… e inserisci https://github.com/respondo-app/sdk-ios, oppure dichiaralo nel tuo Package.swift, poi dipendi dal prodotto 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")
        ]
    )
]

Poi importalo nel codice:

import RespondoSDK

Inizializzazione#

Inizializza una volta all’avvio, poi chiama Respondo.open() ovunque. Il metodo del ciclo di vita è initialize (la parola init è riservata dal linguaggio).

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

La facade Respondo è thread-safe. Le chiamate fatte subito dopo initialize vengono accodate e applicate una volta completata l’init asincrona.

Identificare gli utenti#

Per impostazione predefinita ogni visitatore è anonimo. Al primo avvio l’SDK genera un visitor_id stabile e lo conserva nel keychain, così un utente che torna ritrova la sua conversazione. Non c’è alcuna chiave API da incorporare — ogni conversazione è protetta da un token di sessione per conversazione che il backend emette e fa avanzare a ogni messaggio, così un visitatore anonimo non deve mai autenticarsi di nuovo.

Chiama identify non appena l’utente è autenticato. Questo collega la sua identità reale, così la sua cronologia lo segue tra dispositivi e reinstallazioni, e il suo nome ed email compaiono accanto alla conversazione nella tua inbox invece di un visitatore anonimo.

Lo userHash è una firma che il tuo backend calcola a partire dall’ identity_secret dell’agente — HMAC-SHA256(secret, userId) (o l’email quando non c’è userId), codificata in esadecimale minuscolo. Il secret dimostra che l’identità è autentica, quindi deve risiedere solo sul tuo backend e non va mai incluso nell’app. Consulta la pagina Verifica dell’identità per la formula completa e gli esempi lato server.

// Lo userHash proviene dal tuo backend (HMAC-SHA256 sullo userId) —
// non calcolarlo mai nell'app.
Respondo.identify(
    RespondoIdentity(
        userId: session.userId,
        email: session.email,
        name: session.fullName,
        userHash: session.respondoUserHash
    )
)

// Al logout: revoca la sessione e avvia un nuovo visitatore anonimo.
Respondo.reset()

Se l’hash manca o è errato, non viene sollevata alcuna eccezione: il backend mantiene silenziosamente il visitatore anonimo, la chat continua a funzionare e si perde semplicemente il collegamento tra dispositivi finché non viene fornito un hash valido. La verifica viene eseguita solo quando l’agente ha un identity_secret impostato — lascialo vuoto durante lo sviluppo e userId / email vengono accettati così come sono.

Observable & delegate#

Leggi lo stato tramite getter sincroni, reattivi AsyncStream, o attraverso un RespondoDelegate. Gli stream e le callback del delegate arrivano sul main actor.

// Stream reattivo dei conteggi dei non letti.
Task {
    for await count in Respondo.unreadCountStream {
        updateBadge(count)
    }
}

// Delegate per badge e fallback dei deep link.
final class SupportCoordinator: RespondoDelegate {
    init() { Respondo.delegate = self }
    func respondoUnreadChanged(_ count: Int) {
        UIApplication.shared.applicationIconBadgeNumber = count
    }
}

Tracciamento delle schermate#

Segnala la schermata corrente a ogni navigazione, così i teaser proattivi e il targeting a livello di pagina possono farvi riferimento (static func setCurrentScreen(_ name: String?)). Passa nil per cancellarla; a ogni cambio il teaser proattivo viene rivalutato per la nuova schermata.

Respondo.setCurrentScreen("pricing")

Prossimi passi#

Collega le Notifiche push e la Verifica dell’identità. Il wrapper UIKit RespondoChatViewController, l’intera superficie del delegate e la risoluzione dei problemi sono trattati nella guida introduttiva dell’iOS SDK; i sorgenti dell’SDK sono pubblici su GitHub.