iOS SDK

Requisitos#

• iOS 15.0+ (detentes de hoja más finos en iOS 16+, con un respaldo del sistema por debajo).
• Swift 5.9+.
• Cero dependencias de terceros: solo Foundation, Swift Concurrency, SwiftUI y UIKit.

Dependes del producto RespondoSDK, que reexporta el RespondoCore multiplataforma.

Instalación#

Añade el paquete con Swift Package Manager. En Xcode: File → Add Package Dependencies… e introduce https://github.com/respondo-app/sdk-ios, o decláralo en tu propio Package.swift y luego depende del producto 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")
        ]
    )
]

Luego impórtalo en el código:

import RespondoSDK

Inicializar#

Inicializa una vez en el arranque y luego llama a Respondo.open() en cualquier lugar. El método del ciclo de vida es initialize (la palabra init está reservada por el lenguaje).

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 fachada Respondo es segura para hilos. Las llamadas realizadas justo después de initialize se ponen en cola y se aplican una vez que se completa la inicialización asíncrona.

Identificar usuarios#

Por defecto, todos los visitantes son anónimos. En el primer arranque, el SDK genera un visitor_id estable y lo conserva en el llavero (keychain), de modo que un usuario que regresa vuelve a encontrar su conversación. No hay ninguna clave de API que incrustar: cada conversación está protegida por un token de sesión por conversación que el backend acuña y desplaza hacia adelante en cada mensaje, así que un visitante anónimo nunca tiene que volver a autenticarse.

Llama a identify una vez que tu usuario haya iniciado sesión. Esto adjunta su identidad real para que su historial lo siga entre dispositivos y reinstalaciones, y su nombre y email aparezcan junto a la conversación en tu bandeja de entrada en lugar de un visitante anónimo.

El userHash es una firma que tu backend calcula a partir del identity_secret del agente — HMAC-SHA256(secret, userId) (o el email cuando no hay userId), codificada como hexadecimal en minúsculas. El secreto demuestra que la identidad es genuina, por lo que debe residir únicamente en tu backend y nunca se incluye en la aplicación. Consulta la página de Verificación de identidad para ver la fórmula completa y ejemplos del lado del servidor.

// El userHash proviene de tu backend (HMAC-SHA256 sobre el userId):
// nunca lo calcules en la aplicación.
Respondo.identify(
    RespondoIdentity(
        userId: session.userId,
        email: session.email,
        name: session.fullName,
        userHash: session.respondoUserHash
    )
)

// Al cerrar sesión: revoca la sesión e inicia un nuevo visitante anónimo.
Respondo.reset()

Si el hash falta o es incorrecto, no se lanza ninguna excepción: el backend mantiene al visitante como anónimo de forma silenciosa, el chat sigue funcionando y simplemente pierdes el vínculo entre dispositivos hasta que se proporcione un hash válido. La verificación solo se ejecuta cuando el agente tiene configurado un identity_secret: déjalo vacío durante el desarrollo y el userId / email se aceptan tal cual.

Observables y delegado#

Lee el estado como getters síncronos, AsyncStream reactivos, o a través de un RespondoDelegate. Los streams y los callbacks del delegado llegan en el actor principal (main actor).

// Stream reactivo de recuentos de no leídos.
Task {
    for await count in Respondo.unreadCountStream {
        updateBadge(count)
    }
}

// Delegado para distintivos y respaldos de enlaces profundos.
final class SupportCoordinator: RespondoDelegate {
    init() { Respondo.delegate = self }
    func respondoUnreadChanged(_ count: Int) {
        UIApplication.shared.applicationIconBadgeNumber = count
    }
}

Seguimiento de pantalla#

Informa de la pantalla actual en cada navegación para que los teasers proactivos y la segmentación a nivel de página puedan compararse con ella (static func setCurrentScreen(_ name: String?)). Pasa nil para borrarla; en cada cambio, el teaser proactivo se reevalúa para la nueva pantalla.

Respondo.setCurrentScreen("pricing")

Próximos pasos#

Configura las Notificaciones push y la Verificación de identidad. El envoltorio de UIKit RespondoChatViewController, la superficie completa del delegado y la resolución de problemas se tratan en la guía de introducción del iOS SDK; las fuentes del SDK son públicas en GitHub.