SDK iOS

Prérequis#

• iOS 15.0+ (crans de feuille plus fins sur iOS 16+, avec un repli système en dessous).
• Swift 5.9+.
• Aucune dépendance tierce — uniquement Foundation, Swift Concurrency, SwiftUI et UIKit.

Vous dépendez du produit RespondoSDK, qui réexporte le module multiplateforme RespondoCore.

Installation#

Ajoutez le paquet avec Swift Package Manager. Dans Xcode : File → Add Package Dependencies… et saisissez https://github.com/respondo-app/sdk-ios, ou déclarez-le dans votre propre Package.swift, puis dépendez du produit 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")
        ]
    )
]

Importez-le ensuite dans le code :

import RespondoSDK

Initialiser#

Initialisez une fois au lancement, puis appelez Respondo.open() n’importe où. La méthode de cycle de vie est initialize (le mot init est réservé par le langage).

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 façade Respondo est thread-safe. Les appels effectués juste après initialize sont mis en file d’attente et appliqués une fois l’initialisation asynchrone terminée.

Identifier les utilisateurs#

Par défaut, chaque visiteur est anonyme. Au premier lancement, le SDK génère un visitor_id stable et le conserve dans le trousseau (keychain), si bien qu’un utilisateur de retour retrouve sa conversation. Aucune clé d’API à intégrer — chaque conversation est protégée par un jeton de session propre à la conversation, que le backend émet et fait glisser à chaque message, de sorte qu’un visiteur anonyme n’a jamais à se réauthentifier.

Appelez identify une fois votre utilisateur connecté. Cela rattache son identité réelle, de sorte que son historique le suit d’un appareil à l’autre et après réinstallation, et que son nom et son e-mail apparaissent à côté de la conversation dans votre boîte de réception au lieu d’un visiteur anonyme.

Le userHash est une signature que votre backend calcule à partir de l’ identity_secret de l’agent — HMAC-SHA256(secret, userId) (ou l’e-mail lorsqu’il n’y a pas de userId), encodée en hexadécimal minuscule. Le secret prouve que l’identité est authentique ; il doit donc résider uniquement sur votre backend et n’est jamais livré dans l’application. Consultez la page Vérification d’identité pour la formule complète et des exemples côté serveur.

// Le userHash provient de votre backend (HMAC-SHA256 sur le userId) —
// ne le calculez jamais dans l'application.
Respondo.identify(
    RespondoIdentity(
        userId: session.userId,
        email: session.email,
        name: session.fullName,
        userHash: session.respondoUserHash
    )
)

// À la déconnexion : révoquez la session et démarrez un nouveau visiteur anonyme.
Respondo.reset()

Si le hash est manquant ou incorrect, rien n’est levé : le backend garde silencieusement le visiteur anonyme, le chat continue de fonctionner, et vous perdez simplement le lien inter-appareils jusqu’à ce qu’un hash valide soit fourni. La vérification ne s’exécute que lorsque l’agent a un identity_secret défini — laissez-le vide pendant le développement et userId / e-mail sont acceptés tels quels.

Observables et delegate#

Lisez l’état via des getters synchrones, des AsyncStream réactifs, ou via un RespondoDelegate. Les streams et les callbacks du delegate arrivent sur le main actor.

// Flux réactif des nombres de messages non lus.
Task {
    for await count in Respondo.unreadCountStream {
        updateBadge(count)
    }
}

// Delegate pour les badges et les replis de liens profonds.
final class SupportCoordinator: RespondoDelegate {
    init() { Respondo.delegate = self }
    func respondoUnreadChanged(_ count: Int) {
        UIApplication.shared.applicationIconBadgeNumber = count
    }
}

Suivi d’écran#

Signalez l’écran courant à chaque navigation pour que les accroches proactives et le ciblage par page puissent s’y référer (static func setCurrentScreen(_ name: String?)). Passez nil pour l’effacer ; à chaque changement, l’accroche proactive est réévaluée pour le nouvel écran.

Respondo.setCurrentScreen("pricing")

Étapes suivantes#

Mettez en place les Notifications push et la Vérification d’identité. Le wrapper UIKit RespondoChatViewController, la surface complète du delegate et le dépannage sont couverts dans le guide de démarrage du SDK iOS ; les sources du SDK sont publiques sur GitHub.