Documentazione

iOS SDK

Un client nativo in Swift e SwiftUI per la chat di assistenza Respondo, con zero dipendenze di terze parti.

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.

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

Poi importalo nel codice:

Swift
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).

MyApp.swiftswift
import SwiftUI
import RespondoSDK

@main
struct MyApp: App {
    init() {
        Respondo.initialize(
            RespondoConfig(
                agentId: "<agent-uuid>",
                channelId: "<channel-uuid>" // Settings › Channels › Mobile SDK
                // 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.

Swift
// 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,
        signedUpAt: session.signedUpAt
    )
)

// 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.

Swift
// 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.

Lo stesso nome viene confrontato con le regole di schermata dei sondaggi pop-up: usa identificatori stabili come «Checkout» invece di titoli tradotti. Le regole sull’indirizzo della pagina valgono solo sui siti web.

Swift
Respondo.setCurrentScreen("pricing")

Aprire un sondaggio dal codice

Apre subito un sondaggio pop-up attivo, ovunque si trovi l’utente, ignorando Show on, le regole di schermata, il tempo sulla schermata, l’evento di attivazione e il pubblico. Copia l’id dall’editor del sondaggio (Additional ways to share). Un sondaggio a cui l’utente ha già risposto non viene mostrato di nuovo.

Swift
Respondo.startSurvey("<survey-id>")

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.