Kavchat by maxsave
Menú de guías

Android

La biblioteca de Android de Kavchat añade a tu aplicación un bot de atención al cliente basado en guiones, con componentes de Jetpack Compose y una Activity para aplicaciones creadas con Views. Las respuestas son predecibles y siguen funcionando sin conexión a partir de la última versión publicada. Requiere Android 6.0 (API 23) o posterior.

Hay dos componentes: kavchat-engine, una versión en Kotlin/JVM del motor de conversación, sin dependencias de Android ni de bibliotecas de terceros, y kavchat, que incluye la comunicación de red (HttpURLConnection), la caché del dispositivo (SharedPreferences), los componentes de Compose KavchatChat y KavchatLauncher, y KavchatActivity.

Instalación

Gradle (Kotlin DSL)
// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven("https://jitpack.io")
    }
}

// app/build.gradle.kts
dependencies {
    implementation("com.kavchat:kavchat-android:0.0.11")
}

La biblioteca se distribuye a través de JitPack, así que añade su repositorio una sola vez, junto a google() y mavenCentral(). El SDK es de código abierto, con licencia MIT: bitbucket.org/maxsave/kavchat-android.

La biblioteca declara el permiso INTERNET y KavchatActivity en su propio manifiesto. No tienes que añadir nada manualmente.

Configuración

Llama a configure una sola vez, en Application.onCreate:

Kotlin
class App : Application() {
    override fun onCreate() {
        super.onCreate()
        Kavchat.configure(this, publicKey = "pk_live_...")
        // Optional: Kavchat.configure(this, "pk_live_...", apiBase = "https://api.kavchat.com", locale = "he")
    }
}

Puedes incluir la clave pública en la aplicación. Nunca incluyas la clave secreta (sk_live_...).

Compose

Un botón flotante en la esquina elegida en el panel de control, que abre el chat a pantalla completa:

Compose
KavchatOverlay(Modifier.fillMaxSize()) {
    AppContent()
}

También puedes colocar el botón donde quieras o integrar el chat en una pantalla propia:

Compose
KavchatLauncher()                                    // com.kavchat.ui.KavchatLauncher
KavchatChat(Modifier.fillMaxSize())                  // full chat, no close button
KavchatChat(Modifier.fillMaxSize(), onClose = { navController.popBackStack() })

Abre y cierra el chat del botón flotante desde el código con Kavchat.controller.setPresented(true) y setPresented(false).

Views (sin Compose en tu aplicación)

Kotlin
Kavchat.open(context)                                // starts KavchatActivity

Desde Java: Kavchat.open(context);. La Activity usa Compose internamente, pero tu aplicación no necesita usarlo.

Token de identidad

Identifica al usuario que ha iniciado sesión con un JWT firmado por tu servidor con la clave secreta (consulta Identificación de usuarios). El token se envía en la cabecera Authorization: Bearer <token>. Un usuario identificado puede ver versiones disponibles solo para usuarios de prueba y enviar el formulario de contacto sin correo electrónico ni teléfono.

Kotlin
Kavchat.setUser(token = identityToken, name = "Dana")   // after login
Kavchat.setUser(token = null)                           // after logout

Al cambiar de usuario, se vuelve a cargar la versión y se inicia una conversación nueva, para que la conversación de un usuario no aparezca a otro.

Pantallas de la aplicación: onScreen

Un botón de tipo screen en el guion solicita a la aplicación que abra una de sus pantallas. Primero se cierra el chat (el diálogo de KavchatLauncher o KavchatActivity) para que la pantalla quede visible:

Kotlin
Kavchat.onScreen = { screen, targetId ->
    navController.navigate("$screen/${targetId.orEmpty()}")   // e.g. "orders", "42"
}

Sin un manejador, estos botones no hacen nada. Los botones link solo abren enlaces https (en el navegador) y tel (en el marcador telefónico). Para el análisis de datos, Kavchat.onEvent informa de los eventos Ready, Unavailable, Open, Close, Effect y Ticket.

Lista de pantallas en el editor

Declara una sola vez las pantallas que puede abrir tu aplicación en Kavchat.configure(..., screens = ...) (tipo KavchatAppScreen). El SDK envía la lista a Kavchat automáticamente y el editor de guiones ofrece esas pantallas en una lista desplegable con sus nombres, en lugar de un campo de texto libre. El editor también pide un identificador de elemento cuando la pantalla lo necesita y avisa si un botón lleva a una pantalla que no has declarado. No hace falta escribir la lista de pantallas manualmente en el panel de control.

Kotlin
Kavchat.configure(
    this, publicKey = "pk_live_...",
    screens = listOf(
        KavchatAppScreen("orders", "My orders"),
        KavchatAppScreen("product", "Product page", needsTarget = true),   // needs a targetId
    ),
)
// or later: Kavchat.registerScreens(listOf(...))
  • id es el valor que recibe onScreen: letras latinas, dígitos, _, . y -, hasta 40 caracteres. label es el nombre que ve el administrador, hasta 60 caracteres. Se admiten hasta 100 pantallas. Se omiten las entradas no válidas y los identificadores duplicados.
  • needsTarget: el botón incluye también un identificador de elemento (por ejemplo, de un producto), que llega a onScreen como targetId.
  • La lista se envía en segundo plano después de cargar la versión, solo si ha cambiado o una vez por semana. Si el envío falla, no se muestra ningún aviso y se vuelve a intentar la próxima vez que se inicia la aplicación. El usuario no ve nada.
  • Las pantallas registradas aparecen en el panel de control, en Bot, Configuración, "Pantallas de la aplicación", junto con las plataformas que han informado de cada pantalla. Si eliminas una pantalla de la aplicación, puedes borrarla también ahí.

Colores

Los colores se toman del panel de control (primaryColor). El texto sobre el color de marca es blanco o casi negro según el contraste WCAG. Si un color es demasiado claro para texto sobre fondo blanco, se sustituye por uno casi negro en enlaces y botones. El nombre del bot, el subtítulo, la imagen y el lado del botón flotante (start o end) también se toman del panel de control, por lo que cambian sin actualizar la aplicación. Las superficies y la tipografía usan tu MaterialTheme.

El distintivo "Con tecnología de Kavchat by maxsave" aparece en todos los planes, con un enlace a kavchat.com. En Premium puedes ocultarlo en la configuración del bot.

Idiomas y RTL

  • El idioma de la interfaz es el locale que se pasa a configure. Si no se especifica, se usa el idioma del dispositivo si hay traducción disponible (he, en, ar, ru, es, fr, de, pt, it, tr); después, el idioma del guion y, por último, el inglés.
  • La búsqueda de coincidencias siempre se realiza en el idioma del guion (palabras comunes que se omiten y prefijos en hebreo y árabe).
  • En hebreo y árabe, el LocalLayoutDirection de todo el chat es RTL. Nada se invierte manualmente: si envuelves los componentes, usa start y end. Mantén android:supportsRtl="true" en el manifiesto de la aplicación.

Respuestas de IA (Premium)

No tienes que configurar nada en la aplicación. Cuando activas las respuestas de IA en el panel de administración (con tu propia clave de un proveedor de IA), las preguntas que ningún guion responde se envían a Kavchat. Durante la espera, de hasta 20 segundos, el chat muestra que el bot está escribiendo. La respuesta aparece como texto sin formato con una pequeña etiqueta "Respuesta de IA" en el idioma de la interfaz. Debajo aparece un botón de un tema relacionado, si lo hay, y un botón "Contactar con el equipo".

Si no hay respuesta, o si la solicitud falla, tarda demasiado o supera el límite (10 respuestas por conversación cada 15 minutos), el chat muestra el mensaje habitual "No encontré una respuesta". La pregunta sigue apareciendo en el informe de preguntas sin respuesta, y las respuestas de IA se guardan en la conversación como cualquier otro mensaje.

Chat con un agente

No tienes que configurar nada en la aplicación. Cuando activas el chat con agentes en el panel de administración, el chat de la aplicación funciona exactamente igual que el widget del sitio web.

  • La opción solo aparece cuando el chat con agentes está activado en la versión publicada. Cuando el bot muestra "Contactar con el equipo", el SDK comprueba si hay un agente disponible. El resultado se guarda durante 30 segundos. Si hay un agente disponible, aparece antes un botón "Hablar con un agente". Si no, solo se muestra el formulario de contacto. Encima aparece una breve explicación del motivo: fuera del horario de atención (incluida la hora de regreso) o todos los agentes están ocupados.
  • Antes de la conversación se completa un formulario breve: nombre, correo electrónico o teléfono, departamento (solo si hay más de uno abierto) y un primer mensaje opcional. Los invitados deben dejar un correo electrónico o un teléfono. Los usuarios identificados mediante un token de identidad no necesitan dejar ninguno de los dos. Si al enviar el formulario ya no hay agentes disponibles, se abre el formulario de contacto con los datos que ya se habían completado.
  • Durante la espera se muestran el tiempo restante hasta que la conversación se convierta en un ticket y un botón "Dejar un mensaje en su lugar". El tiempo de espera se configura en el panel de administración y es de 2 minutos por defecto. También se puede escribir durante la espera, y el agente verá los mensajes. Si ningún agente queda disponible a tiempo, la conversación se guarda como un ticket normal y se muestra su número.
  • Durante la conversación se muestran el nombre del agente, un aviso cuando un agente se une (también después de una transferencia a otro agente), un indicador cuando escribe y un botón para finalizar la conversación. Los mensajes solo admiten texto sin formato, hasta 2.000 caracteres, sin enlaces. Un mensaje que aún no ha llegado al servidor aparece como "Enviando...". Si el envío falla varias veces, se puede tocar el mensaje para volver a intentarlo. Los reintentos no crean mensajes duplicados.
  • Tras cada desconexión, el SDK espera un poco, recupera lo que se haya perdido y vuelve a conectarse. El tiempo de espera aumenta gradualmente. Los mensajes siempre aparecen en orden y sin duplicados. Si la conexión continua no funciona (por ejemplo, detrás de un proxy corporativo), el SDK pasa temporalmente a consultar el servidor de forma periódica.
  • Cuando la aplicación pasa a segundo plano, la conexión se cierra. Al volver a la aplicación, el SDK recupera lo que se haya perdido y vuelve a conectarse. Una conversación abierta continúa incluso después de cerrar y volver a iniciar la aplicación, siempre que no hayan pasado 12 horas.
  • En esta versión no hay notificaciones push. Los mensajes solo llegan mientras la aplicación está abierta. Una respuesta enviada mientras la aplicación está en segundo plano aparece en cuanto vuelves a ella.
  • Las credenciales de acceso a la conversación se guardan en memoria. En el dispositivo solo se guardan cifradas con una clave de Android Keystore. No se escriben en la URL ni en los registros. Se eliminan cuando la conversación termina, se convierte en un ticket o caduca, y también cuando se cambia de usuario con setUser.

Puedes usar Kavchat.controller.livePage para indicar al agente desde qué pantalla llegó el usuario.

Preguntas, condiciones y leads

No hace falta configurar nada en la aplicación. Un guion puede pedir datos (nombre, teléfono, correo electrónico, un número o texto libre), elegir cómo continuar según la información disponible y enviar un lead.

  • Teclado adecuado: Cuando el bot espera una respuesta, el campo de texto muestra un teclado de teléfono, correo electrónico o números. Al pedir un nombre, el teclado activa las mayúsculas al principio de cada palabra. Si la respuesta no es válida, el bot responde con un mensaje breve en el idioma del chat y se resalta el campo. Las preguntas que se pueden omitir muestran un botón "Omitir". Escribir "Cancelar" en cualquiera de los idiomas compatibles permite salir de la pregunta.
  • Teléfono: A los números sin + se les asigna el país predeterminado del espacio de trabajo (definido en la configuración del panel de administración).
  • Lead: Un paso de lead muestra el texto de consentimiento con los botones "Enviar" y "No, gracias", seguido del mensaje de confirmación. El lead se añade a una cola en el dispositivo y se envía al servidor. Si no hay conexión o el servidor no está disponible, se vuelve a intentar el envío (también al iniciar la aplicación de nuevo y después de reload()). El servidor ignora los duplicados.
  • Datos precargados: El formulario de contacto y el formulario para solicitar un agente se completan con el nombre, el correo electrónico y el teléfono recopilados. Todos los valores recopilados se adjuntan al ticket o a la solicitud de un agente. Las preguntas previas al chat con un agente (Premium) se hacen antes de conectar.
  • Token de identidad: Al usar setUser, los campos name, email y phone del token completan las respuestas a las preguntas correspondientes, y el bot las omite.
  • Pantalla actual: Las condiciones pueden comprobar la pantalla actual. Configura Kavchat.controller.livePage (por ejemplo, "checkout").

Los valores recopilados son datos personales. Permanecen en la conversación guardada en el dispositivo y solo se envían con los leads, los tickets y las conversaciones con agentes, nunca a los informes.

Uso sin conexión y caché

La última versión se guarda en SharedPreferences con su ETag y se vuelve a validar con If-None-Match (304) cada vez que se inicia la aplicación. Si no hay conexión, se usa la copia guardada y se muestra un aviso. Si el bot está desactivado, disponible solo para usuarios de prueba o ha agotado su cuota, no se muestra nada. Una conversación abierta se conserva hasta 30 minutos sin actividad, por lo que salir del chat o de la aplicación no la reinicia. El recorrido de la conversación se envía dos segundos después de la última acción e inmediatamente cuando la aplicación pasa a segundo plano.