iOS

El paquete Swift de Kavchat añade a tu app iOS un bot de atención basado en guiones, con componentes SwiftUI y UIKit. Las respuestas son predecibles y siguen funcionando sin conexión con la última versión publicada. Requiere iOS 15 o posterior.

El paquete incluye dos productos: KavchatEngine, la versión Swift del motor de conversación, sin UIKit, y Kavchat, con la comunicación de red, la caché en el dispositivo y la interfaz: KavchatChatView (SwiftUI), KavchatLauncher y KavchatViewController (UIKit).

Instalación

Con Swift Package Manager en Xcode: selecciona File > Add Package Dependencies e introduce la URL del repositorio:

https://bitbucket.org/maxsave/kavchat-ios.git

O en el archivo Package.swift:

.package(url: "https://bitbucket.org/maxsave/kavchat-ios.git", from: "0.0.11"),
// ...
.product(name: "Kavchat", package: "kavchat-ios"),

El SDK es de código abierto, bajo la licencia MIT: bitbucket.org/maxsave/kavchat-ios.

Configuración

Llama a configure una sola vez, lo antes posible, por ejemplo en el init de App o en application(_:didFinishLaunchingWithOptions:):

import Kavchat

Kavchat.configure(publicKey: "pk_live_...")            // the public key from the dashboard
// Optional:
// Kavchat.configure(publicKey: "pk_live_...", apiBase: "https://api.kavchat.com", locale: "he")

Puedes incluir la clave pública en la app. Nunca incluyas la clave secreta (sk_live_...).

SwiftUI

Un botón flotante en la esquina elegida en el panel de control, que abre el chat en una ventana modal (sheet):

ContentView()
    .kavchatLauncher()

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

KavchatLauncher()
KavchatChatView()                                      // full chat, no close button
KavchatChatView(onClose: { showChat = false })         // with a close button

Abre y cierra la ventana del botón flotante desde el código con Kavchat.open() y Kavchat.close().

UIKit

Kavchat.present(from: self)                            // modal, with a close button
// or
let chat = KavchatViewController(showsCloseButton: false)
navigationController?.pushViewController(chat, animated: true)

Token de identidad

Identifica al usuario que ha iniciado sesión con un JWT firmado por tu servidor con la clave secreta (consulta Identificar usuarios). El token se envía en el encabezado 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.

Kavchat.setUser(token: identityToken, name: "Dana")    // after login
Kavchat.setUser(token: nil)                            // 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 se muestre a otro.

Pantallas de la app: onScreen

Un botón de tipo screen en el guion solicita a la app que abra una de sus pantallas. La ventana del chat se cierra primero para que la pantalla quede visible:

Kavchat.onScreen = { screen, targetId in
    router.open(screen, id: targetId)                  // e.g. "orders", "42"
}

Sin un manejador, estos botones no hacen nada. Los botones link solo abren enlaces https y tel. 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 tu app puede abrir en Kavchat.configure(..., screens:). 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 solicita un identificador de elemento cuando la pantalla lo necesita y avisa si un botón lleva a una pantalla que no se ha declarado. No hay que introducir la lista de pantallas a mano en el panel de control.

Kavchat.configure(publicKey: "pk_live_...", screens: [
    KavchatScreen(id: "orders", label: "My orders"),
    KavchatScreen(id: "product", label: "Product page", needsTarget: true),  // needs a targetId
])
// or later: Kavchat.registerScreens([...])

• 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 también incluye 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 cuando 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 app. El usuario no ve nada.
• Las pantallas registradas aparecen en el panel de control, en Bot, Configuración, "Pantallas de la app", junto con las plataformas que han informado de cada pantalla. Si has eliminado una pantalla de la app, puedes borrarla allí.

Colores

Los colores se configuran en el 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 usarlo como 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 configuran en el panel de control, por lo que pueden cambiar sin actualizar la app.

La etiqueta "Con tecnología de Kavchat by maxsave" se muestra en todos los planes, con un enlace a kavchat.com. En Premium puedes ocultarla 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 (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 usa el idioma del guion (palabras comunes que se omiten y prefijos en hebreo y árabe).
• En hebreo y árabe, el layoutDirection de todo el chat va de derecha a izquierda. Nada se invierte manualmente: si envuelves los componentes en otros contenedores, usa leading y trailing.

Respuestas de IA (Premium)

No tienes que configurar nada en la app. Al activar 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 puede responder 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 se muestran un botón para un tema relacionado, si lo hay, y el botón "Contactar al equipo".

Si no hay respuesta, la solicitud falla, tarda demasiado o supera el límite (10 respuestas por conversación cada 15 minutos), el chat muestra su mensaje habitual de "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 necesitas configurar nada en la app. Al activar el chat con agentes en el panel de administración, el chat de la app 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 al equipo", el SDK comprueba si hay un agente disponible. El resultado se guarda durante 30 segundos. Si hay un agente disponible, aparece antes el 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 (con 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 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 ya completados.
• Durante la espera se muestran el tiempo restante hasta que la conversación se convierta en un ticket y el 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 de forma predeterminada. 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 tras una transferencia a otro agente), un indicador cuando está escribiendo y un botón para finalizar la conversación. Los mensajes solo admiten texto sin formato, hasta 2.000 caracteres, sin enlaces. Los mensajes que aún no han llegado al servidor aparecen como "Enviando...". Si el envío falla varias veces, se puede tocar el mensaje para volver a intentarlo. Reintentar no crea mensajes duplicados.
• Después de cada desconexión, el SDK espera un poco, recupera lo que falta y vuelve a conectarse. El tiempo de espera aumenta gradualmente. Los mensajes siempre se muestran 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 app pasa a segundo plano, la conexión se cierra. Al volver a la app, el SDK recupera lo que falta y vuelve a conectarse. Una conversación abierta continúa incluso después de cerrar y volver a abrir la app, siempre que no hayan pasado 12 horas.
• Esta versión no incluye notificaciones push. Los mensajes solo llegan cuando la app está abierta. Una respuesta enviada mientras la app está en segundo plano aparece en cuanto se vuelve a ella.
• Las credenciales de acceso a la conversación se guardan solo en la memoria y en el Keychain del dispositivo. No se guardan en UserDefaults, en la URL ni en los registros. Se eliminan cuando la conversación termina, se convierte en un ticket o caduca, y también al cambiar de usuario con setUser.

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

Preguntas, condiciones y leads

No necesitas configurar nada en la app. Un guion puede pedir datos (nombre, teléfono, correo electrónico, un número o texto libre), decidir 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. En las preguntas de nombre, el teclado activa la mayúscula 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 opcionales muestran un botón "Omitir". Escribir "Cancelar" en cualquier idioma compatible 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 a la red o el servidor no está disponible, se reintenta el envío, también al volver a iniciar la app y después de reload(). El servidor ignora los duplicados.
• Datos precompletados: 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 la conexión.
• 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.shared.livePage (por ejemplo, "checkout").

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

Uso sin conexión y caché

La última versión se guarda en UserDefaults con su ETag y se vuelve a validar con If-None-Match (304) cada vez que se inicia la app. Sin 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 la 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 app 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 app pasa a segundo plano.