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.3.1")
],
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.

El mismo nombre se compara con las reglas de pantalla de las encuestas emergentes, así que usa identificadores estables como «Checkout» en lugar de títulos traducidos. Las reglas de dirección de página solo se aplican en sitios web.

Respondo.setCurrentScreen("pricing")

Abrir una encuesta desde el código#

Abre al instante una encuesta emergente activa, esté donde esté el usuario, sin tener en cuenta Show on, las reglas de pantalla, el tiempo en pantalla, el evento disparador ni la audiencia. Copia el id en el editor de la encuesta (Additional ways to share). Una encuesta que el usuario ya respondió no se vuelve a mostrar.

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

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.