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

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.

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