Android SDK

Requisitos#

• minSdk 24 (Android 7.0), compileSdk 35.
• Kotlin 2.x y Jetpack Compose (el SDK incluye la interfaz de Compose).
• Destino de JVM 17.

El SDK arrastra sus propias dependencias transitivas (Coroutines, kotlinx.serialization, OkHttp, Coil, Compose) y declara el permiso INTERNET en su manifiesto: no hay que añadir nada a mano.

Instalación#

La biblioteca se publica en Maven Central como ai.respondo:respondo-sdk. Asegúrate de que mavenCentral() esté en tus repositorios (lo está por defecto en un proyecto de Android nuevo) y luego añade la dependencia por coordenada.

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
    }
}

dependencies {
    implementation("ai.respondo:respondo-sdk:0.1.0")
}

Inicializar#

Llama a Respondo.init una vez, monta RespondoChatHost() una vez en tu árbol de Compose y abre el chat desde tu propio botón.

import ai.respondo.sdk.Respondo
import ai.respondo.sdk.RespondoConfig
import ai.respondo.sdk.ui.RespondoChatHost

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        Respondo.init(
            context = this,
            config = RespondoConfig(
                agentId = "<agent-uuid>",   // desde el panel de control
                channelId = "<channel-uuid>", // opcional
                // baseUrl omitido -> https://api.respondo.ai
            ),
        )

        setContent {
            MaterialTheme {
                Box(modifier = Modifier.fillMaxSize()) {
                    Button(onClick = { Respondo.open() }) { Text("Support") }
                    RespondoChatHost() // el SDK muestra la hoja cuando el estado del chat es OPEN
                }
            }
        }
    }
}

Todas las llamadas pasan por el singleton Respondo. Son idempotentes, seguras desde cualquier hilo, y las llamadas realizadas antes de que termine la inicialización se almacenan en búfer y se reproducen después.

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 almacenamiento local, 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.

import ai.respondo.sdk.RespondoIdentity

// 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: elimina el token push, revoca la sesión, inicia un nuevo visitante anónimo.
Respondo.clearPushToken()
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 callbacks#

Lee el estado de forma reactiva como StateFlow (ideal para Compose) o de forma imperativa mediante RespondoListener (ideal para un distintivo en el icono de la aplicación).

// Reactivo: recuento de no leídos como un StateFlow.
val unread by Respondo.unreadCount.collectAsState()

// Imperativo: listener para distintivos y analítica.
Respondo.setListener(object : RespondoListener {
    override fun onUnreadChanged(count: Int) { updateAppIconBadge(count) }
    override fun onUrlRequested(url: String): Boolean = tryOpenInternally(url)
})

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. Pasa null 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 para las respuestas de operadores sin conexión y la Verificación de identidad para los usuarios autenticados. La superficie completa de la API, el envoltorio de Fragment para hosts XML y la resolución de problemas se tratan en la guía de introducción del Android SDK; las fuentes del SDK son públicas en GitHub.