En este documento, se muestra cómo integrar y personalizar el SDK de Headless para dispositivos móviles en tu aplicación para Android. Se abordan la localización, los flujos posteriores a la sesión y otros temas avanzados.
Flujos posteriores a la sesión (VA, encuestas y CSAT posteriores a la sesión)
Cuando finaliza un chat en vivo o una llamada de voz, los centros de contacto suelen querer recopilar comentarios o realizar seguimientos automatizados. La plataforma de CCAI admite tres tipos de experiencias posteriores a la sesión:
Agente virtual (AV) posterior a la sesión: Es un chatbot automatizado que continúa la conversación después de que se desconecta el agente humano.
Encuestas: Un formulario con varias preguntas adaptado a la fila específica.
CSAT (satisfacción del cliente): Es una calificación (por ejemplo, de 1 a 5 estrellas) y comentarios de texto opcionales.
Aplicación de la jerarquía
Es común que los administradores configuren reglas superpuestas en el portal (por ejemplo, activar la CSAT de forma global, pero también activar un VA posterior a la sesión para la cola de Facturación).
Qué proporciona el SDK: Un motor estricto de resolución de conflictos. El SDK evalúa las reglas del portal y garantiza que solo se active un flujo posterior a la sesión por sesión, respetando estrictamente la siguiente jerarquía:
La prioridad posterior a la sesión es la siguiente: VA posterior a la sesión > Encuestas > CSAT
- Ejemplo: Si se habilitan tanto la CSAT como el VA posterior a la sesión para una fila, el usuario SOLO verá el VA posterior a la sesión.
Qué compilarás: Un objeto de escucha que espera a que finalice la sesión, le pregunta al SDK qué flujo ganó la evaluación de jerarquía y dibuja la pantalla correspondiente. No necesitas escribir una lógica compleja de if-else para determinar qué experiencia gana; el SDK hace ese cálculo por ti.
Ejemplo de implementación
En este fragmento, se muestra cómo tu app debe escuchar el final de una sesión y preguntarle al SDK qué hacer a continuación.
// Called when the active chat or call ends
fun handleSessionEnded(postSessionFlow: PostSessionFlow?) {
// 1. Check if there is a required post-session flow.
// The SDK has already calculated the hierarchy (VA > Survey > CSAT).
val flow = postSessionFlow
if (flow == null) {
// No feedback required. Safely close the support UI.
closeSupportExperience()
return
}
// 2. Route to the winning flow returned by the SDK.
when (flow.type) {
PostSessionType.VIRTUAL_AGENT -> transitionToPostSessionVA()
PostSessionType.SURVEY -> showSurveyScreen(flow)
PostSessionType.CSAT -> showCSATScreen(flow)
}
}
Transición a la fase posterior a la sesión
Independientemente de qué flujo gane la jerarquía, debes llamar a dos métodos de ciclo de vida compartidos en chatService para indicarle a la plataforma de CCAI que comenzó la fase posterior a la sesión.
Qué proporciona el SDK: Métodos de ciclo de vida para realizar la transición de la sesión a la fase posterior a la sesión y a través de ella (startPostSession, readyPostSession).
Qué compilar: La lógica de organización que llama a estos métodos en los puntos correctos del flujo de IU posterior a la sesión.
Ejemplo de implementación
Este código hace que la sesión pase por las dos etapas del ciclo de vida posteriores a la sesión.
lifecycleScope.launch {
// Step 1: Start the post-session process (updates status to "in_progress")
try {
val postSessionResponse = CCAI.chatService?.startPostSession()
if (postSessionResponse != null) {
Log.d("CCAI", "Post-session started successfully: ${postSessionResponse.id}")
}
} catch (e: Exception) {
Log.e("CCAI", "Failed to start post-session: ${e.message}")
}
// Step 2: Signal that post-session is ready (updates status to "ready")
try {
val readyResponse = CCAI.chatService?.readyPostSession()
if (readyResponse != null) {
Log.d("CCAI", "Post-session ready: ${readyResponse.id}")
}
} catch (e: Exception) {
Log.e("CCAI", "Failed to prepare post-session: ${e.message}")
}
}
Después de que la plataforma confirme la transición, continúa con este flujo específico.
Campos de estado posteriores a la sesión en ChatResponse
Dos campos de organización posteriores a la sesión en ChatResponse controlan la lógica de transición:
postSessionTransferStatus: String?: Es el estado actual de la transferencia posterior a la sesión (por ejemplo,"in_progress","ready","completed"). La plataforma activa la máquina de estado de organización a partir de este campo:startPostSession()lo mueve a"in_progress",readyPostSession()lo mueve a"ready", y tú observas este valor en las emisiones deChatResponseposteriores (desde el flujo de chat del servicio de chat) para confirmar la transición del lado de la plataforma.postSessionOptInRequired: Boolean?: Indica si el usuario debe habilitar de forma explícita el flujo posterior a la sesión antes de que se ejecute. Cuandotrue, muestra un mensaje de aceptación en tu IU y llama astartPostSession()solo después de que el usuario dé su consentimiento. Cuandofalseonull, no se requiere la verificación de aceptación y puedes pasar directamente al flujo posterior a la sesión.
suspend fun orchestratePostSession(chat: ChatResponse) {
// 1. Honor opt-in gating if required
if (chat.postSessionOptInRequired == true) {
val consented = presentPostSessionOptIn()
if (!consented) {
closeSupportExperience()
return
}
}
// 2. Drive the state machine
CCAI.chatService?.startPostSession() // → "in_progress"
CCAI.chatService?.readyPostSession() // → "ready"
// 3. Observe postSessionTransferStatus on subsequent chat updates
// to confirm the transfer completed before rendering the winning flow.
}
postSessionRequiredte indica si se configuró algún flujo posterior a la sesión.postSessionOptInRequiredte indica si se requiere el consentimiento explícito del usuario antes de ejecutarlo.postSessionTransferStatuste indica en qué etapa del ciclo de vida de transición se encuentra la plataforma.
Los tres son independientes, por lo que siempre debes verificar cada uno.
Agente virtual posterior a la sesión (prioridad más alta)
Qué proporciona el SDK: El estado de transición para cambiar la sesión de un agente humano a un bot automatizado y el enrutamiento de los mensajes del bot.
Qué crearás: Nada completamente nuevo. Como el VA posterior a la sesión funciona como un chat, mantienes abierta la IU de chat personalizada existente y dejas que controle los mensajes automatizados entrantes, tal como lo hizo con los mensajes del agente humano.
Ejemplo de implementación
Si el SDK indica una transición a un VA posterior a la sesión, actualiza la IU de chat para reflejar el cambio.
fun transitionToPostSessionVA() {
// Keep your chat UI open, but update the visual context
myChatAdapter.addSystemMessage(
"You are now speaking with our Virtual Assistant"
)
agentNameTextView.text = "Virtual Assistant"
agentAvatarImageView.setImageResource(R.drawable.ic_bot_avatar)
// The SDK will automatically start piping the VA's messages into
// your standard chat message observer (messagesReceived).
}
Encuestas (prioridad media)
Qué proporciona el SDK: El rateService expone métodos para recuperar preguntas de encuestas y enviar respuestas para una sesión de comunicación. El administrador configura las preguntas de la encuesta para cada fila, y estas pueden incluir varios tipos de preguntas (CSAT, calificación por estrellas, texto de formato libre, enumeración y escala numérica).
Qué compilarás: Un formulario dinámico que recupera la encuesta, recorre las preguntas, renderiza la IU adecuada (como botones de selección, calificaciones por estrellas o campos de texto) para cada una, valida que se completen los campos obligatorios y empaqueta las respuestas para enviarlas de vuelta.
Tipos de claves
// Survey response from getSurvey()
data class Survey(
val id: Int?,
val lang: String?,
val questions: List<SurveyQuestion>?,
val signOffText: String? // "Thank you" message to show after submission
)
// Request payload for sendSurvey()
data class SurveyRequest(
val answers: Map<Int, String> // Maps question IDs to answer values
)
Ejemplo de implementación
Este código recupera las preguntas de la encuesta de rateService, las renderiza en un fragmento personalizado y envía las respuestas.
fun showSurveyScreen(communicationId: Long) {
val rateService = CCAI.rateService ?: return
lifecycleScope.launch {
try {
// 1. Fetch the survey questions for this session
val survey = rateService.getSurvey(
communicationId = communicationId,
communicationType = "chats"
).getOrThrow()
// 2. Present your custom survey UI
val surveyFragment = MyCustomSurveyFragment.newInstance(
survey.questions.orEmpty()
)
surveyFragment.onSubmit = { answersMap ->
lifecycleScope.launch {
try {
// 3. Submit the answers
val request = SurveyRequest(answers = answersMap)
rateService.sendSurvey(
communicationId = communicationId,
communicationType = "chats",
answers = request
).getOrThrow()
rateService.clear()
closeSupportExperience()
} catch (e: Exception) {
Log.e("CCAI", "Failed to submit survey: ${e.message}")
}
}
}
supportFragmentManager.beginTransaction()
.replace(R.id.container, surveyFragment)
.addToBackStack(null)
.commit()
} catch (e: Exception) {
Log.e("CCAI", "Failed to load survey: ${e.message}")
closeSupportExperience()
}
}
}
CSAT: satisfacción del cliente (prioridad más baja)
Qué proporciona el SDK: El rateService expone un método rate() para enviar una puntuación de CSAT y comentarios opcionales para una sesión de comunicación. La calificación suele ser un valor entero del 1 al 5.
Qué compilarás: La pantalla de calificación visual (como una fila de estrellas que se pueden presionar o una escala numérica del 1 al 5), un campo de texto si se permiten comentarios y un botón Enviar.
Tipos de claves
// Request payload for rate()
data class RatingRequest(
val rating: Int? = null, // Typically 1-5
val feedback: String? = null // Optional qualitative feedback
)
Ejemplo de implementación
Después de que el usuario presione una calificación por estrellas y escriba sus comentarios, pasa esos valores a rateService.
fun submitCSATFeedback(communicationId: Long, rating: Int, comment: String?) {
val rateService = CCAI.rateService ?: return
submitButton.isEnabled = false
progressBar.isVisible = true
lifecycleScope.launch {
try {
val request = RatingRequest(
rating = rating,
feedback = comment?.trim()?.takeIf { it.isNotEmpty() }
)
rateService.rate(
communicationId = communicationId,
communicationType = "chats",
request = request
).getOrThrow()
rateService.clear()
showThankYouScreen()
} catch (e: Exception) {
showErrorToast("Failed to submit feedback. Please try again.")
} finally {
submitButton.isEnabled = true
progressBar.isVisible = false
}
}
}
Cómo descargar transcripciones de chats
Qué proporciona el SDK: Un método para descargar la transcripción del chat como un archivo PDF.
Qué compilarás: El botón de descarga en tu IU y la lógica de manejo de archivos (guardar, compartir o vista previa)
Ejemplo de implementación
Este código demuestra el enfoque de descarga de transcripciones de Android: recuperar el PDF como un archivo y, luego, guardarlo, compartirlo o obtener una vista previa de él en tu app.
// Download to a file destination
val documentsDir = getExternalFilesDir(Environment.DIRECTORY_DOCUMENTS)
val transcriptFile = File(documentsDir, "chat_transcript.pdf")
lifecycleScope.launch {
try {
val transcriptFile = CCAI.chatService?.downloadChatTranscript()
if (transcriptFile != null) {
Log.d("CCAI", "Transcript downloaded to: ${transcriptFile.absolutePath}")
}
} catch (e: Exception) {
Log.e("CCAI", "Failed to download transcript: ${e.message}")
}
}
El método downloadChatTranscript() de Android no toma parámetros y devuelve un File? que apunta al PDF descargado. El método downloadChatTranscriptData() (que devuelve datos de PDF sin procesar directamente en la memoria sin guardarlos en el disco) solo está disponible en iOS. Asegúrate de que tu app tenga los permisos de almacenamiento de archivos adecuados si se guarda en el almacenamiento compartido.
Idiomas y localización
Como estás creando una IU integrada personalizada con el SDK de Headless para dispositivos móviles, eres responsable de la traducción de los botones, los menús y las alertas personalizadas de tu app.
Entonces, ¿por qué el SDK necesita conocer el idioma del usuario?
Enrutamiento de colas: CCAI Platform usa el código de idioma para enrutar al usuario a un agente que hable ese idioma.
Mensajes del sistema: Los mensajes automatizados que genera el backend de CCAI Platform (por ejemplo, "Un agente te atenderá en breve") se entregan en el idioma activo.
APIs de servicios de lenguaje
Qué proporciona el SDK: Una propiedad languageCode de lectura y escritura para el idioma activo del SDK.
Qué compilarás: Una IU de selector de idioma (si quieres que los usuarios elijan manualmente) y la lógica para establecer el idioma antes de que comience una sesión.
// Read the active language
val currentLanguage = CCAI.languageService?.languageCode
// Set the active language before the user starts a support session
CCAI.languageService?.languageCode = "es"
El SDK no expone una lista fija de idiomas compatibles con el SDK. Si tu app muestra un selector de idioma, mantén la lista de visualización de la app por tu cuenta o usa la configuración de instancia o de empresa que devuelve el SDK para determinar qué idiomas ofrecer.
Configura el idioma del SDK (la regla previa a la sesión)
Qué proporciona el SDK: Un LanguageService que compara el idioma que solicitas con los idiomas que tus administradores habilitaron en el portal de CCAI Platform.
Qué compilar: Si quieres permitir que los usuarios anulen manualmente el idioma (en lugar de depender solo de la configuración predeterminada de su dispositivo), debes compilar la IU de selección (como un menú desplegable) y asegurarte de que solo se pueda acceder a ella antes de que presionen un canal de asistencia.
Ejemplo de implementación
Este código demuestra cómo anular de forma explícita el idioma del SDK con los códigos de idioma ISO 639 estándar (por ejemplo, "es" para español, "fr" para francés). El idioma preferido se establece con el parámetro languageCode durante la inicialización del SDK en la clase de datos InitOptions. También puedes establecerlo cuando vuelvas a inicializar el SDK:
// Set language during initialization
val initOptions = InitOptions(
key = "YOUR_COMPANY_KEY",
urlHost = "your_subdomain.ccaiplatform.com",
languageCode = "es" // for example, "es" for Spanish, "fr" for French
)
try {
CCAI.initialize(context = this, options = initOptions)
} catch (e: Exception) {
Log.e("CCAI", "Failed to initialize CCAI: ${e.message}")
}
Inicialización del módulo de chat (Android)
Si inicializas el módulo de chat con la sobrecarga que acepta un código de idioma, también puedes proporcionar el idioma allí:
val chatOptions = ChatOptions(
webFormInterface = WebFormManager(),
downloadTranscriptVisibility = DownloadTranscriptVisibility.SHOW_ALL,
greeting = "Hello! How can I help you?"
)
CCAI.initializeChat(context = this, options = chatOptions)
También puedes pasar el idioma cuando recuperes los menús de la fila:
val menuResult = CCAI.queueMenuService?.get(key = null)
Anula por sesión con el ChatRequest:
val chatRequest = ChatRequest(
chat = Chat(
menuId = menuId,
languageCode = "fr" // This session will use French
)
)
Cómo CCAI Platform resuelve el idioma final
Si no estableces un idioma de forma explícita, el SDK igualmente necesitará un código de idioma para la ruta y los mensajes del sistema. Para que el comportamiento sea predecible, lo mejor es que lo configures antes de que el usuario inicie una sesión de asistencia.
Usa este orden de prioridad:
Idioma explícito (recomendado): Si configuras un idioma en
InitOptions.languageCode, el SDK usará ese idioma.Actualización del idioma antes de la sesión (todavía explícita): Si configuras
CCAI.languageService?.languageCode = "es"antes de que el usuario ingrese a una fila, el SDK usará ese idioma actualizado.Anulación por sesión (solo chat): Si proporcionas
ChatRequest(chat = Chat(..., languageCode = "fr")), esa sesión de chat usará el código de idioma solicitado.Si no estableces ningún valor, el comportamiento se revierte a lo que el SDK determine que es la mejor opción disponible en la configuración del dispositivo y de la instancia. Para obtener resultados coherentes, evita depender de esto y establece siempre un idioma de forma explícita (pasos 1 a 3).
Manejo de errores, resguardo y administración de sesiones
Incluso las apps más sólidas experimentan conexiones interrumpidas, dependencias faltantes o problemas de autenticación. El SDK de Headless Mobile está diseñado para detectar estos problemas subyacentes de la plataforma y mostrarlos en tu app, lo que te permite controlarlos de forma correcta dentro de tu IU personalizada o confiar en las alternativas automatizadas de CCAI Platform.
Cómo controlar los errores del SDK
Qué proporciona el SDK: Dos categorías de excepciones con tipo, junto con las excepciones estándar de Kotlin:
HttpExceptionWithCode: Se genera por cualquier método de servicio asíncrono cuando falla una solicitud HTTP a la plataforma de CCAI. Expone una propiedadInt codepara que puedas crear ramas en los códigos de estado (por ejemplo,401para la autenticación vencida,429para el límite de frecuencia y5xxpara los errores de servidor).CallCreationError.AfterHours: Es un error sellado que arroja la API de llamadas programadas (callService.createScheduledCall) cuando se produce un conflicto de horarios o se cierra el plazo para programar citas. Contiene undisplayMessagelocalizado en el servidor que se muestra directamente al usuario.Excepciones estándar de Kotlin o Java: Las fallas de red se muestran como
java.io.IOException, la cancelación de corrutinas comokotlinx.coroutines.CancellationExceptiony cualquier imprevisto como la clase baseException.
Qué compilarás: Un bloque try o catch en capas alrededor de cada llamada al servicio del SDK. Captura primero la excepción más específica (errores sellados específicos del dominio, como CallCreationError.AfterHours, cuando corresponda, y, luego, HttpExceptionWithCode para la ramificación de estado HTTP) y recurre a un controlador Exception genérico para fallas de red, del sistema y no anticipadas.
Ejemplo de implementación
Este código une una llamada al SDK en un patrón try o catch en capas, detectando primero HttpExceptionWithCode para ramificar el código de estado HTTP y, luego, recurriendo a un controlador genérico para todo lo demás.
import kotlinx.coroutines.launch
import androidx.lifecycle.lifecycleScope
lifecycleScope.launch {
try {
CCAI.chatService?.start(chatRequest)
// Handle success - observe chat state using chatReceived
} catch (e: HttpExceptionWithCode) {
// Handle HTTP-level failures from CCAI endpoints - inspect e.code for status code
Log.e("CCAI", "HTTP ${e.code}: ${e.message}")
showErrorToast("Something went wrong. Please try again.")
} catch (e: Exception) {
// Handle other errors (examples: network and system)
Log.e("CCAI", "Error: ${e.message}")
showErrorToast("An unexpected error occurred.")
}
}
Prácticas recomendadas
Une cada llamada de servicio del SDK en un try/catch en capas. Usa
HttpExceptionWithCodepara crear ramas en los códigos de estado HTTP; por ejemplo, vuelve a activarccaiShouldAuthenticate()en401(token de autenticación vencido), aplica una retirada en429(límite de frecuencia) o muestra un error genérico en las respuestas5xx.Para las APIs de llamadas programadas, detecta
CallCreationError.AfterHoursantes deHttpExceptionWithCodepara que los conflictos de horarios 409 se controlen con el mensaje localizado del servidor.Por último, captura el
Exceptiongenérico como una red de seguridad paraIOException,CancellationExceptiony cualquier falla imprevista. Registrar los detalles de la excepción durante el desarrollo ayuda a identificar las causas raíz con rapidez.
Verifica y borra las sesiones
Debido a que el ciclo de vida de tu app es independiente del ciclo de vida de asistencia de CCAI Platform, debes administrar el estado de la sesión, especialmente en lo que respecta a los cierres de sesión de los usuarios.
Qué proporciona el SDK: APIs de utilidad para verificar si una sesión de asistencia aún está en curso (incluso después de que se reinicie la app o se fuerce su salida) y métodos para borrar el estado de autenticación del SDK almacenado en caché vinculado a un usuario final específico, lo que evita que el próximo usuario que acceda herede la sesión del usuario anterior.
Qué compilarás: Verificaciones preliminares antes de intentar iniciar sesiones nuevas y rutinas de limpieza que se activan cuando un usuario sale de tu app principal.
Ejemplo de implementación (limpieza de salida)
Finaliza cualquier sesión activa, borra el token de autenticación almacenado en caché del SDK, borra los datos de app locales y navega a la pantalla de acceso, que es la limpieza mínima necesaria para evitar la herencia de sesiones cuando el usuario sale de la cuenta.
fun handleUserLogout() {
lifecycleScope.launch {
// 1. Check for an in-progress session and end it cleanly
try {
val activeChat = CCAI.chatService?.getLastChatInProgress()
if (activeChat != null) {
CCAI.chatService?.endChat()
Log.d("CCAI", "Ended active chat before logout.")
}
} catch (e: Exception) {
// Session may not exist - that's fine
Log.w("CCAI", "No active session to end: ${e.message}")
}
// 2. Clear the cached auth token
// (prevents the next user from inheriting the previous session)
CCAI.authService?.updateAuthToken(null)
// 3. Wipe your own app's user data
MyAuthManager.clearLocalData()
// 4. Navigate back to the login screen
navigateToLoginScreen()
}
}
Integración de corrutinas y Flow de Kotlin
El SDK de Headless para dispositivos móviles para Android está diseñado en torno a las corrutinas de Kotlin y Flow como sus patrones reactivos principales. Este es el equivalente en Android de la integración de Combine del SDK de iOS.
Qué proporciona el SDK: Flujos de Kotlin y funciones de suspensión que emiten eventos del SDK en tiempo real (mensajes entrantes, cambios de estado de uso compartido de pantalla) como flujos reactivos observables.
Qué compilarás: Integraciones basadas en corrutinas que recopilan estos flujos y actualizan la IU de Android según corresponda.
Funciones de suspensión
Muchos métodos de servicio del SDK son funciones de suspensión de Kotlin, lo que significa que se pueden llamar desde un permiso de corrutina y se suspenderán (no se bloquearán) mientras esperan un resultado.
import kotlinx.coroutines.launch
import androidx.lifecycle.lifecycleScope
// In an Activity or Fragment
lifecycleScope.launch {
try {
// These are suspend functions - they suspend, not block
val menuResult = CCAI.queueMenuService?.get()
CCAI.chatService?.start(chatRequest)
val company = CCAI.companyService?.get()
} catch (e: Exception) {
handleError(e)
}
}
Flujos del servicio de chat
chatService expone las propiedades SharedFlow de Kotlin para observar eventos de chat en tiempo real. Recopílalos dentro de un alcance de corrutina optimizado para ciclos de vida (lifecycleScope o viewModelScope).
| Flujo | Emite |
|---|---|
messagesReceived |
Son listas de mensajes de chat entrantes (de agentes, asistentes virtuales o el sistema). |
typingEvent |
Cuando un usuario o un agente está escribiendo. |
memberEvent |
Cuando un usuario o un agente se une al chat o lo abandona (incluidas las transferencias y desconexiones de agentes) |
stateChanged |
Cambios de estado del proveedor de chat (conectando, conectado, desconectado, error) |
chatReceived |
Datos de respuesta del chat cuando se recibe o actualiza un chat (incluidos los cambios de estado, la asignación de agentes y el estado posterior a la sesión) |
chatService expone flujos adicionales para eventos de transferencia (transferEventSubject), resultados de verificación de estado (checkStatusSubject) y resultados de envío de mensajes (messageSendResultSubject).
Ejemplo de implementación
import kotlinx.coroutines.flow.collect
import kotlinx.coroutines.flow.distinctUntilChanged
// 1. Incoming messages
lifecycleScope.launch {
CCAI.chatService?.messagesReceived?.collect { messages ->
for (message in messages) {
renderIncomingMessage(message)
}
}
}
// 2. Typing indicators
lifecycleScope.launch {
CCAI.chatService?.typingEvent?.collect { event ->
when (event) {
is ChatTypingEvent.Started -> showTypingIndicator()
is ChatTypingEvent.Ended -> hideTypingIndicator()
}
}
}
// 3. Member join/leave
lifecycleScope.launch {
CCAI.chatService?.memberEvent?.collect { event ->
when (event) {
is MemberEvent.Joined -> Log.d("Chat", "Member joined")
is MemberEvent.Left -> Log.d("Chat", "Member left")
}
// Refresh chat status after member changes
try { CCAI.chatService?.checkStatus() } catch (_: Exception) {}
}
}
// 4. Chat provider state changes
lifecycleScope.launch {
CCAI.chatService?.stateChanged?.distinctUntilChanged()?.collect { state ->
// Update UI based on connection state (examples: connecting, connected)
updateConnectionStatus(state)
}
}
// 5. Chat metadata updates (agent assignment, status changes)
lifecycleScope.launch {
CCAI.chatService?.chatReceived?.collect { chat ->
Log.d("Chat", "Received chat update: ${chat.id}")
updateAgentInfo(chat)
handlePostSessionIfNeeded(chat)
}
}
Estado de compartir pantalla
Qué proporciona el SDK: El estado de la sesión de compartir pantalla se entrega a través de la devolución de llamada onSessionStateChanged en ScreenShareCallbacks, que pasas a ScreenShareManager.startSession(). Consulta SDK de Headless para dispositivos móviles para Android: Voz, compartir pantalla, llamada programada y correo electrónico. La devolución de llamada se activa cada vez que la sesión cambia entre INACTIVE, PENDING y ACTIVE.
Qué compilar: Un controlador conectado a ScreenShareCallbacks.onSessionStateChanged que actualiza tu IU a medida que la sesión cambia de estado, además de una propiedad local (por ejemplo, currentScreenShareSessionState) si necesitas leer el estado actual fuera de la devolución de llamada.
Ejemplo de implementación
Además de la ruta de acceso ScreenShareCallbacks, ScreenShareManager también expone APIs independientes de addStateChangeListener/removeStateChangeListener y un descriptor de acceso síncrono de getSessionState(). Úsalos cuando necesites observar el estado de un componente que no sea el que llamó a startSession() o para realizar una lectura única no reactiva. A diferencia de la ruta de acceso ScreenShareCallbacks, en la que la devolución de llamada se libera automáticamente cuando finaliza la sesión, los objetos de escucha independientes no se liberan de forma automática. Llama a removeStateChangeListener(...) en el desmontaje del propietario del ciclo de vida para evitar fugas.
// Register a state change listener
val listener: (ScreenShareSessionState) -> Unit = { state ->
when (state) {
ScreenShareSessionState.INACTIVE -> Log.d("ScreenShare", "No active session")
ScreenShareSessionState.PENDING -> Log.d("ScreenShare", "Session pending")
ScreenShareSessionState.ACTIVE -> Log.d("ScreenShare", "Session active")
}
}
ScreenShareManager.addStateChangeListener(listener)
// Get the current state directly (not reactive)
val currentState = ScreenShareManager.getSessionState()
// Clean up when done
ScreenShareManager.removeStateChangeListener(listener)
Datos personalizados
Qué proporciona el SDK: Un mecanismo para adjuntar metadatos estructurados a las sesiones de chat, ya sea como JWT firmados (verificados por tu backend) o como cargas útiles no firmadas (establecidas directamente en el cliente).
Qué compilarás: La lógica de recopilación de datos en tu app y, para los datos firmados, el extremo de firma de JWT en tu servidor de backend (consulta SDK de Headless para dispositivos móviles para Android: Comienza a usarlo para ver el esquema completo de autenticación y carga útil de JWT).
Datos personalizados firmados
Los datos personalizados firmados usan un token JWT firmado con el secreto de tu empresa en tu servidor de backend. Este es el enfoque seguro para pasar datos sensibles o de confianza.
Ejemplo de implementación
Crea un objeto de datos personalizados firmado a partir de un JWT generado en tu backend.
// JWT signed with company secret (signing must happen on your backend)
val customData = CustomData(signed = "header.payload.signature")
Datos personalizados sin firma
Los datos personalizados sin firma se configuran directamente en el cliente con CustomDataPayload y CustomDataItem.
Ejemplo de implementación
Compila una carga útil sin firma con elementos de datos visibles y ocultos para el agente. CustomDataPayload toma un MutableMap<String, CustomDataItem?>, por lo que debes usar la asignación de subíndices (o mutableMapOf) para agregar cada elemento por clave. La clave que elijas (por ejemplo, "user_name" o "account_tier") se convierte en el nombre del campo que se muestra al agente y al enrutamiento o las estadísticas.
val items = mutableMapOf<String, CustomDataItem?>()
items["user_name"] = CustomDataItem(
label = "Name",
value = "John"
)
items["user_age"] = CustomDataItem(
label = "Age",
value = 30,
type = CustomDataType.NUMBER,
invisibleToAgent = true
)
val payload = CustomDataPayload(items = items)
val customData = CustomData(unsigned = payload)
Los elementos de datos personalizados admiten las siguientes propiedades:
label: Es la etiqueta que se muestra al agente.value: Es el valor de los datos (ejemplos:String,Int,Bool).type: Es el tipo de datos (STRING,NUMBER,DATE,URL,BOOLEAN).invisibleToAgent: Cuando se establece entrue, los datos se ocultan de los agentes, pero están disponibles para el enrutamiento y las estadísticas.
Usa datos personalizados en las solicitudes de chat
Adjunta datos personalizados cuando inicies una sesión de chat.
Ejemplo de implementación
val chatRequest = ChatRequest(
chat = Chat(
menuId = 123,
languageCode = "en",
customData = customData
)
)
lifecycleScope.launch {
try {
CCAI.chatService?.start(chatRequest)
// Chat started - observe chat state using chatReceived
} catch (e: Exception) {
Log.e("CCAI", "Failed to start chat: ${e.message}")
}
}
Transferencia de chat externo
Qué proporciona el SDK: Una estructura de datos (ExternalChatTransfer) para pasar el nombre de un agente anterior y la transcripción de la conversación a una nueva sesión de CCAI Platform.
Qué compilarás: El flujo de migración que extrae el contexto de tu sistema de chat externo y lo empaqueta para el SDK.
Ejemplo de implementación
Este código crea un objeto de transferencia de chat externo con el nombre del agente anterior y lo adjunta a los datos personalizados de la sesión.
// ExternalChatAgent also accepts an optional `avatar: String? = null` parameter
// for displaying the previous agent's avatar, for example:
// ExternalChatAgent(name = "John Smith", avatar = "https://cdn.example.com/avatars/jsmith.png")
val transfer = ExternalChatTransfer(
agent = ExternalChatAgent(name = "John Smith"),
transcript = emptyList()
)
// Attach to your custom data payload
val payload = CustomDataPayload()
payload.externalChatTransfer = transfer
val customData = CustomData(unsigned = payload)
Esto es útil cuando se migra a un usuario de un sistema de chat de terceros a una sesión con tecnología de CCAI Platform, ya que se conserva el contexto de la conversación para el agente receptor.
Consideraciones sobre los subprocesos
El SDK de Headless para dispositivos móviles Android está diseñado para funcionar con corrutinas de Kotlin y, en gran medida, es seguro para el subproceso principal. Sin embargo, hay consideraciones importantes sobre los subprocesos para las integraciones sin interfaz gráfica.
Seguridad del subproceso principal
Todos los métodos del SDK cuentan con protección de subprocesos y se pueden llamar desde cualquier subproceso. La mayoría de las llamadas de servicio del SDK (por ejemplo, chatService?.start() y queueMenuService?.get()) son funciones de suspensión que controlan sus propios subprocesos de forma interna, es decir, suspenden la corrutina que realiza la llamada sin bloquear el subproceso. Puedes llamarlas de forma segura desde el subproceso principal dentro del alcance de una corrutina:
// Safe to call from the main thread
lifecycleScope.launch {
val menu = CCAI.queueMenuService?.get() // Suspends, does not block
updateUi(menu) // Back on main thread
}
CCAIDelegate y subprocesos en segundo plano
El método ccaiShouldAuthenticate() de tu CCAIDelegate es una función de suspensión, por lo que puedes realizar llamadas de red de forma segura dentro de ella:
override suspend fun ccaiShouldAuthenticate(): String? {
// This runs in a coroutine context - safe to call suspend functions
return withContext(Dispatchers.IO) {
MyBackendApi.getSignedJwt() // Network call on IO dispatcher
}
}
Actualizaciones de la IU desde las devoluciones de llamada del SDK
Cuando observes eventos del SDK con Flow, asegúrate de que las actualizaciones de la IU se realicen en el subproceso principal. Si usas lifecycleScope, esto se controla automáticamente:
// lifecycleScope dispatches to Main by default
lifecycleScope.launch {
chatMessagesFlow.collect { messages ->
// Already on Main - safe to update UI
chatAdapter.submitList(messages)
}
}
Si recopilas datos de un despachador que no es el principal, vuelve a cambiar de forma explícita:
lifecycleScope.launch(Dispatchers.IO) {
// Processing on IO thread
val processed = heavyProcessing()
withContext(Dispatchers.Main) {
// Update UI on Main thread
updateChatUi(processed)
}
}
Subprocesos de inicialización
Se debe llamar a CCAI.initialize() y a las llamadas de inicialización de módulos relacionadas, como initializeChat(), initializeCall() y initializeScreenShare(), en el subproceso principal de tu Application.onCreate(). Estas son llamadas síncronas que configuran el estado interno del SDK.
class MainApplication : Application() {
override fun onCreate() {
super.onCreate() // Always on main thread
// All initialization must happen on main thread
CCAI.initialize(context = this, options = initOptions)
CCAI.initializeChat(context = this, options = ChatOptions())
CCAI.initializeCall(context = this)
}
}
Administración de la memoria
La administración adecuada de la memoria es esencial para evitar fugas y garantizar una eliminación limpia de los recursos del SDK.
Ciclo de vida de corrutinas y flujos
Cancela siempre las referencias de Job de corrutinas y los recopiladores de Flow en los métodos del ciclo de vida de Android (onDestroy() para Activities, onCleared() para ViewModels). De lo contrario, las referencias pueden permanecer activas más tiempo del previsto, lo que provoca fugas de memoria.
import kotlinx.coroutines.Job
class ChatViewModel : ViewModel() {
private var chatJob: Job? = null
fun observeChatMessages() {
chatJob = viewModelScope.launch {
CCAI.chatService?.messagesReceived?.collect { messages ->
// Handle new messages
}
}
}
override fun onCleared() {
super.onCleared()
chatJob?.cancel()
}
}
Referencias de objetos de escucha y devoluciones de llamada
Usa referencias débiles para los objetos de escucha y las devoluciones de llamada para evitar ciclos de retención. Borra las devoluciones de llamada registradas cuando se destruya tu Activity o ViewModel.
class ChatActivity : AppCompatActivity() {
private var chatJob: Job? = null
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
chatJob = lifecycleScope.launch {
CCAI.chatService?.messagesReceived?.collect { messages ->
updateChatUI(messages)
}
}
}
override fun onDestroy() {
super.onDestroy()
chatJob?.cancel()
}
}
Prácticas recomendadas
Almacena referencias de corrutinas
Job: Almacena siempre las referencias deJobque devuelvelaunch {}para evitar corrutinas descontroladas que sobrevivan a su alcance.Realiza limpiezas en los métodos del ciclo de vida: Cancela todos los trabajos y borra las devoluciones de llamada en
onDestroy()(actividades) oonCleared()(ViewModels).Usa referencias débiles para los objetos de escucha: Ten cuidado con las lambdas que capturan implícitamente
this(el contexto de la actividad o el fragmento que las contiene), ya que esto puede impedir la recolección de elementos no utilizados.Los servicios se administran con el SDK: No necesitas lanzar manualmente los servicios del SDK, ya que se administran con el objeto singleton
CCAI.
Soluciona problemas
En esta sección, se describen los problemas de integración comunes y sus soluciones.
Problemas de compilación y dependencias
En esta sección, se abordan los problemas comunes de compilación y dependencia.
Problema
Gradle no puede resolver com.ccaiplatform.android:CCAIKit.
Causa: Falta el repositorio de Maven de CCAI o usa la URL incorrecta.
Solución: Asegúrate de que tu
settings.gradle.ktsincluya lo siguiente:maven { url = uri("https://sdk.ujet.co/ccaip/android/") }Ten en cuenta el segmento de ruta de acceso
/ccaip/. La URL heredada (https://sdk.ujet.co/android/) no resolverá los artefactos.
Problema
Errores de compilación de Java 17 requerida
Causa: Este SDK requiere compatibilidad con Java 17.
Corrección: Actualiza tu
build.gradle.kts:compileOptions { sourceCompatibility = JavaVersion.VERSION_17 targetCompatibility = JavaVersion.VERSION_17 } kotlinOptions { jvmTarget = "17" }
Problema
chatLibraryNotFound (código de error 1100) en el entorno de ejecución.
Causa: Falta el módulo
CCAIChatReden las dependencias.Corrección: Se requieren
CCAIChatyCCAIChatRedpara el chat. Agrega lo siguiente:implementation("com.ccaiplatform.android:CCAIChat:ccaiVersion") implementation("com.ccaiplatform.android:CCAIChatRed:ccaiVersion")
Problemas de inicialización
En esta sección, se abordan los problemas de inicialización comunes.
Problema
NullPointerException cuando accedas a CCAI.chatService.
Causa: No se llamó a
CCAI.initializeChat()o se llamó antes deCCAI.initialize().Solución: Asegúrate de que el orden de inicialización en
Application.onCreate()sea el siguiente:CCAI.initialize(context, options = initOptions)CCAI.initializeChat(context, options = chatOptions)CCAI.initializeCall(context)(si se usan llamadas de voz o programadas)CCAI.initializeScreenShare(context, options)(si se usa la función de compartir pantalla)
Problema
Los servicios del SDK devuelven null después de la inicialización.
Causa: No se llamó a
CCAI.initialize()en el subproceso principal o la claseApplicationno está registrada en el manifiesto.Solución: Verifica que la línea
android:name=".MainApplication"esté presente en tu archivoAndroidManifest.xmly que todas las llamadas de inicialización estén enonCreate().
Problemas de autenticación
En esta sección, se abordan los problemas de autenticación comunes.
Problema
La autenticación falla de forma silenciosa o nunca se llama a ccaiShouldAuthenticate().
Causa: No se estableció
CCAIDelegateenInitOptions.Solución: Asegúrate de que
delegatese pase aInitOptions:val initOptions = InitOptions( key = "YOUR_KEY", urlHost = "your_subdomain.ccaiplatform.com", delegate = MyCCAIDelegate() // Must not be null )
Problema
Errores de validación de JWT (código de error 101)
Causa: El JWT venció, tiene un formato incorrecto o se firmó con el secreto equivocado.
Solución: Verifica que tu backend cumpla con lo siguiente:
Usa el código secreto de la empresa correcto.
Establece marcas de tiempo válidas de
iatyexp.Devuelve una cadena de JWT con el formato correcto.
Problemas con las notificaciones push
En esta sección, se abordan los problemas comunes relacionados con las notificaciones push.
Problema
No se reciben ni se controlan las notificaciones push.
Causa: El token de FCM no está registrado en el SDK, el servicio de mensajería de Firebase no está registrado o las cargas útiles de datos entrantes no se reenvían al SDK.
Solución:
Llama a
CCAI.pushNotificationService?.updatePushToken(token)enonNewToken()y durante el inicio.Reenvía
remoteMessage.dataaCCAI.pushNotificationService?.handlePushNotification(remoteMessage.data)desde tu servicio de mensajería de Firebase.Verifica que
google-services.jsonesté en el módulo de tu app.Verifica que la clave de la cuenta de servicio de Firebase esté configurada en el portal del administrador de CCAI Platform.
Renderiza cualquier notificación visible o IU de llamada entrante en el código de tu propia app.
Problema
El SDK no reacciona a las notificaciones push entrantes (se ignoran los mensajes).
Causa: Se pasa el tipo de datos incorrecto al método
handlePushNotification().Solución: Asegúrate de pasar
remoteMessage.data(que es unMap<String, String>), no todo el objetoRemoteMessage.
Problemas con la sesión de chat
En esta sección, se abordan los problemas comunes de las sesiones de chat.
Problema
chatService?.start() arroja una excepción o devuelve null.
Causa:
menuIdno válido, falla de autenticación o problema de red.Solución:
Verifica que el
menuIdcoincida con una cola válida en tu portal de administrador.Verifica que
ccaiShouldAuthenticate()intercambie un JWT firmado válido a través deCCAI.authService?.authenticate(jwt)y devuelva el token de autenticación resultante.Asegúrate de que el dispositivo tenga conectividad de red.
Une la llamada en un try o catch y, luego, registra los detalles de la excepción.
Problema
Los mensajes de chat no aparecen en tu IU.
Causa: No se observa el flujo de mensajes del servicio de chat.
Solución: Asegúrate de recopilar datos del flujo del servicio de chat en un alcance que tenga en cuenta el ciclo de vida (consulta la sección Flujos del servicio de chat más arriba).
Problemas para compartir pantalla
En esta sección, se abordan los problemas comunes relacionados con compartir pantalla.
Problema
La función de compartir pantalla no se inicia después de que el usuario otorga el consentimiento.
Causa: El módulo
CCAIScreenShareno se inicializó o no se inicióMediaProjectionde Android.Solución:
Asegúrate de que se llame a
CCAI.initializeScreenShare()con unScreenShareOptionsválido.Verifica que estés iniciando correctamente el
MediaProjectionManagery el servicio en primer plano de Android después de obtener el consentimiento.En Android 14 y versiones posteriores, asegúrate de que el tipo de servicio en primer plano incluya
mediaProjection.
Sugerencias generales para la depuración
Habilita el registro detallado durante el desarrollo para ver el estado interno del SDK.
Consulta el portal de administrador de CCAI Platform para verificar la configuración de la cola, la habilitación de canales y el horario de atención.
Supervisa el tráfico de red con herramientas como Charles Proxy o el Inspector de red de Android Studio para verificar las llamadas a la API a
*.ccaiplatform.com.Verifica que las versiones de los módulos coincidan: todos los módulos de
com.ccaiplatform.androiddeben usar el mismo número de versión para evitar problemas de compatibilidad.
Resumen de la serie
Felicitaciones: Completaste la serie de cinco partes del SDK de Headless para dispositivos móviles para Android. Ahora, tu integración abarca lo siguiente:
Configuración e inicialización (SDK de Headless Mobile para Android: Introducción)
Filas, canales y chat (SDK de Headless Mobile para Android: Filas, canales y chat)
Voz, compartir pantalla, llamada programada y correo electrónico (SDK de Headless Mobile para Android: Voz, compartir pantalla, llamada programada y correo electrónico)
Acciones inteligentes, archivos adjuntos y desvío (SDK de Headless para dispositivos móviles para Android: Acciones inteligentes, archivos adjuntos y desvío)
Flujos posteriores a la sesión, localización, manejo de errores y temas avanzados (este artículo)
Para consultarlo de forma continua, agrega a favoritos la referencia de la API de Android del SDK para dispositivos móviles sin interfaz gráfica y consulta las notas de la versión de CCAI Platform para conocer las actualizaciones del SDK.