SDK móvel sem interface gráfica para Android: tópicos avançados, localização e fluxos pós-sessão

Este documento mostra como integrar e personalizar o SDK para dispositivos móveis sem interface no seu app Android. Ele aborda localização, fluxos pós-sessão e outros tópicos avançados.

Fluxos pós-sessão (VA pós-sessão, pesquisas e CSAT)

Quando uma conversa Live ou ligação termina, as centrais de atendimento geralmente querem coletar feedback ou oferecer acompanhamentos automatizados. A plataforma CCAI oferece três tipos de experiências pós-sessão:

  1. Agente virtual (AV) pós-sessão: um chatbot automatizado que continua a conversa depois que o agente humano se desconecta.

  2. Pesquisas: um formulário com várias perguntas adaptado à fila específica.

  3. CSAT (satisfação do cliente): uma classificação (por exemplo, de 1 a 5 estrelas) e um feedback de texto opcional.

Como aplicar a hierarquia

É comum que os administradores configurem regras sobrepostas no portal (por exemplo, ativar o CSAT globalmente, mas também ativar um VA pós-sessão para a fila de faturamento).

O que o SDK oferece: um mecanismo rigoroso de resolução de conflitos. O SDK avalia as regras do portal e garante que apenas um fluxo pós-sessão seja acionado por sessão, seguindo estritamente esta hierarquia:

  • A prioridade pós-sessão: VA pós-sessão > Pesquisas > CSAT

    • Exemplo: se o CSAT e o VA pós-sessão estiverem ativados para uma fila, o usuário verá APENAS o VA pós-sessão.

O que você vai criar: um listener que aguarda o fim da sessão, pergunta ao SDK qual fluxo venceu a avaliação de hierarquia e desenha a tela correspondente. Não é necessário escrever uma lógica complexa de "if-else" para descobrir qual experiência vence. O SDK faz esse cálculo para você.

Exemplo de implementação

Este snippet demonstra como o app deve detectar o fim de uma sessão e perguntar ao SDK o que fazer em seguida.

// 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)
    }
}

Transição para a fase pós-sessão

Independentemente de qual fluxo vencer a hierarquia, você precisa chamar dois métodos de ciclo de vida compartilhados no chatService para sinalizar à plataforma CCAI que a fase pós-sessão começou.

O que o SDK oferece: métodos de ciclo de vida para fazer a transição da sessão para a fase pós-sessão (startPostSession, readyPostSession).

O que você cria: a lógica de orquestração que chama esses métodos nos pontos corretos do fluxo UI pós-sessão.

Exemplo de implementação

Esse código faz a transição da sessão pelos dois estágios do ciclo de vida pós-sessão.

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

Depois que a plataforma reconhecer a transição, prossiga para esse fluxo específico.

Campos de estado pós-sessão em ChatResponse

Dois campos de orquestração pós-sessão em ChatResponse orientam a lógica de transição:

  • postSessionTransferStatus: String?: o estado atual da transferência pós-sessão (por exemplo, "in_progress", "ready", "completed"). A plataforma usa esse campo como chave para a máquina de estado de orquestração: startPostSession() move para "in_progress", readyPostSession() move para "ready", e você observa esse valor nas emissões subsequentes de ChatResponse (do fluxo de chat do serviço de chat) para confirmar a transição do lado da plataforma.

  • postSessionOptInRequired: Boolean?: se o usuário precisa ativar explicitamente o fluxo pós-sessão antes que ele seja executado. Quando true, mostre uma solicitação de ativação na UI e só chame startPostSession() depois que o usuário consentir. Quando false ou null, a verificação de ativação não é necessária, e você pode passar direto para o fluxo pós-sessão.

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.
}
  • postSessionRequired informa se algum fluxo pós-sessão está configurado para a sessão.

  • postSessionOptInRequired informa se o consentimento explícito do usuário é necessário antes da execução.

  • postSessionTransferStatus informa onde a plataforma está no ciclo de vida da transição.

Os três são independentes. Sempre verifique cada um deles.

Agente virtual pós-sessão (prioridade mais alta)

O que o SDK oferece: o estado de transição para transferir a sessão de um agente humano de volta para um bot automatizado e o roteamento das mensagens do bot.

O que você vai criar: nada de novo. Como o VA pós-sessão funciona como um chat, você mantém a UI personalizada aberta e deixa que ele lide com as mensagens automatizadas recebidas, assim como lidou com as mensagens do agente humano.

Exemplo de implementação

Se o SDK sinalizar uma transição para um VA pós-sessão, atualize a UI do chat para refletir a mudança.

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

Pesquisas (prioridade média)

O que o SDK oferece: o rateService expõe métodos para recuperar perguntas da pesquisa e enviar respostas para uma sessão de comunicação. As perguntas da pesquisa são configuradas pelo administrador para cada fila e podem incluir vários tipos de perguntas (CSAT, classificação por estrelas, texto de formato livre, enumeração, escala numérica).

O que você vai criar: um formulário dinâmico que busca a pesquisa, percorre as perguntas, renderiza a UI adequada (como botões de opção, classificações por estrelas ou campos de texto) para cada uma, valida se os campos obrigatórios estão preenchidos e empacota as respostas para enviar de volta.

Tipos de chaves

// 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
)

Exemplo de implementação

Esse código busca perguntas da pesquisa no rateService, renderiza as perguntas em um fragmento personalizado e envia as respostas.

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: satisfação do cliente (prioridade mais baixa)

O que o SDK oferece: o rateService expõe um método rate() para enviar uma pontuação de CSAT e feedback opcional para uma sessão de comunicação. A classificação geralmente é um valor inteiro de 1 a 5.

O que você cria: a tela de classificação visual (como uma linha de estrelas tocáveis ou uma escala numérica de 1 a 5), um campo de texto se o feedback for permitido e um botão Enviar.

Tipos de chaves

// Request payload for rate()
data class RatingRequest(
    val rating: Int? = null,      // Typically 1-5
    val feedback: String? = null  // Optional qualitative feedback
)

Exemplo de implementação

Depois que o usuário tocar em uma classificação por estrelas e escrever o feedback, transmita esses valores para o 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
        }
    }
}

Como fazer o download de transcrições de chats

O que o SDK oferece: um método para baixar a transcrição da conversa como um arquivo PDF.

O que você cria: o botão de download na UI e a lógica de processamento de arquivos (salvar, compartilhar ou visualizar).

Exemplo de implementação

Este código demonstra a abordagem de download de transcrição do Android: recuperar o PDF como um arquivo e, em seguida, salvar, compartilhar ou visualizar no 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}")
    }
}

O método downloadChatTranscript() do Android não usa parâmetros e retorna um File? que aponta para o PDF baixado. O método downloadChatTranscriptData() (que retorna dados brutos de PDF diretamente na memória sem salvar no disco) está disponível apenas no iOS. Verifique se o app tem as permissões de armazenamento de arquivos adequadas se estiver salvando no armazenamento compartilhado.

Idiomas e localização

Como você está criando uma interface integrada personalizada usando o SDK para Dispositivos Móveis sem Cabeçalho, você é responsável pela tradução dos botões, menus e alertas personalizados do seu app.

Por que o SDK precisa saber o idioma do usuário?

  1. Roteamento de fila: a plataforma CCAI usa o código de idioma para encaminhar o usuário a um agente que fale esse idioma.

  2. Mensagens do sistema: as mensagens automáticas geradas pelo back-end da plataforma CCAI (por exemplo, "Um agente vai atender você em breve") são enviadas no idioma ativo.

APIs de serviço de linguagem

O que o SDK oferece: uma propriedade languageCode de leitura e gravação para a linguagem ativa do SDK.

O que você cria: uma UI de seletor de idioma (se você quiser que os usuários escolham manualmente) e a lógica para definir o idioma antes do início de uma sessão.

// Read the active language
val currentLanguage = CCAI.languageService?.languageCode

// Set the active language before the user starts a support session
CCAI.languageService?.languageCode = "es"

O SDK não expõe uma lista fixa de idiomas compatíveis. Se o app mostrar um seletor de idioma, mantenha a lista de exibição do app por conta própria ou use a configuração de instância ou empresarial retornada pelo SDK para determinar quais idiomas oferecer.

Definir o idioma do SDK (regra de pré-sessão)

O que o SDK oferece: um LanguageService que compara o idioma solicitado com os idiomas que os administradores realmente ativaram no portal da plataforma CCAI.

O que você cria: se quiser permitir que os usuários substituam manualmente o idioma (em vez de depender apenas das configurações padrão do dispositivo), crie a UI de seleção (como um menu suspenso) e garanta que ela só seja acessível antes de tocar em um canal de suporte.

Exemplo de implementação

Este código demonstra como substituir explicitamente o idioma do SDK usando códigos de idioma ISO 639 padrão (por exemplo, "es" para espanhol, "fr" para francês). O idioma preferencial é definido usando o parâmetro languageCode durante a inicialização do SDK na classe de dados InitOptions. Também é possível defini-lo ao reinicializar o 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}")
}

Inicialização do módulo de chat (Android)

Se você estiver inicializando o módulo de chat usando a sobrecarga que aceita um código de idioma, também poderá fornecer o idioma lá:

val chatOptions = ChatOptions(
    webFormInterface = WebFormManager(),
    downloadTranscriptVisibility = DownloadTranscriptVisibility.SHOW_ALL,
    greeting = "Hello! How can I help you?"
)
CCAI.initializeChat(context = this, options = chatOptions)

Também é possível transmitir o idioma ao buscar menus de fila:

val menuResult = CCAI.queueMenuService?.get(key = null)

Substitua por sessão usando o ChatRequest:

val chatRequest = ChatRequest(
    chat = Chat(
        menuId = menuId,
        languageCode = "fr"  // This session will use French
    )
)

Como a plataforma CCAI resolve o idioma final

Se você não definir um idioma explicitamente, o SDK ainda vai precisar de um código de idioma para rotas e mensagens do sistema. Para manter o comportamento previsível, é melhor definir o idioma antes que o usuário inicie uma sessão de suporte.

Use esta ordem de prioridade:

  1. Idioma explícito (recomendado): se você definir um idioma em InitOptions.languageCode, o SDK vai usar esse idioma.

  2. Atualização de idioma antes da sessão (ainda explícita): se você definir CCAI.languageService?.languageCode = "es" antes de o usuário entrar em uma fila, o SDK vai usar esse idioma atualizado.

  3. Substituição por sessão (somente chat): se você fornecer ChatRequest(chat = Chat(..., languageCode = "fr")), essa sessão de chat vai usar o código de idioma solicitado.

  4. Se você não definir nada: o comportamento vai voltar para o que o SDK determinar como a melhor opção disponível no dispositivo e na configuração da instância. Para resultados consistentes, evite depender disso e sempre defina um idioma explicitamente (etapas 1 a 3).

Tratamento de erros, substituição e gerenciamento de sessões

Até mesmo os apps mais robustos enfrentam conexões perdidas, dependências ausentes ou problemas de autenticação. O SDK para dispositivos móveis headless foi projetado para detectar esses problemas de plataforma e mostrá-los no app, permitindo que você os resolva de maneira adequada na UI personalizada ou use os fallbacks automatizados da CCAI Platform.

Tratar erros do SDK

O que o SDK oferece: duas categorias de exceções tipadas, além das exceções padrão do Kotlin:

  • HttpExceptionWithCode: gerado por qualquer método de serviço assíncrono quando uma solicitação HTTP para a plataforma CCAI falha. Expõe uma propriedade Int code para que você possa ramificar em códigos de status (por exemplo, 401 para autenticação expirada, 429 para limitação de taxa, 5xx para erros de servidor).

  • CallCreationError.AfterHours: um erro selado gerado pela API de chamada agendada (callService.createScheduledCall) quando ocorre um conflito de horário ou o período de agendamento de horários é encerrado. Contém uma displayMessage localizada no servidor destinada à exibição direta ao usuário.

  • Exceções padrão do Kotlin ou do Java: as falhas de rede aparecem como java.io.IOException, o cancelamento de corrotinas como kotlinx.coroutines.CancellationException e qualquer imprevisto como a classe de base Exception.

O que você cria: um try ou catch em camadas em cada chamada de serviço do SDK. Capture primeiro a exceção mais específica (erros selados específicos do domínio, como CallCreationError.AfterHours, quando aplicável, e depois HttpExceptionWithCode para ramificação de status HTTP) e use um gerenciador genérico Exception para falhas de rede, sistema e imprevistas.

Exemplo de implementação

Esse código encapsula uma chamada do SDK em um padrão de try ou catch em camadas, capturando primeiro HttpExceptionWithCode para ramificar no código de status HTTP e, em seguida, voltando para um gerenciador genérico para todo o resto.

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áticas recomendadas

  • Encapsule cada chamada de serviço do SDK em um try/catch em camadas. Use HttpExceptionWithCode para ramificar em códigos de status HTTP. Por exemplo, acione novamente ccaiShouldAuthenticate() em 401 (token de autenticação expirado), aplique uma espera em 429 (limitação de taxa) ou mostre um erro genérico em respostas 5xx.

  • Para APIs de chamada agendada, capture CallCreationError.AfterHours antes de HttpExceptionWithCode para que os conflitos de slot 409 sejam processados com a mensagem localizada no servidor.

  • Por fim, capture o Exception genérico como uma rede de segurança para IOException, CancellationException e quaisquer falhas imprevistas. Registrar os detalhes da exceção durante o desenvolvimento ajuda a identificar as causas raiz rapidamente.

Verificar e limpar sessões

Como o ciclo de vida do seu app é separado do ciclo de vida de suporte da plataforma CCAI, você precisa gerenciar o estado da sessão, especialmente em relação às saídas de usuários.

O que o SDK oferece: APIs utilitárias para verificar se uma sessão de suporte ainda está em andamento (inclusive após reinicializações ou encerramentos forçados do app) e métodos para limpar o estado de autenticação do SDK armazenado em cache vinculado a um usuário final específico, impedindo que o próximo usuário conectado herde a sessão do usuário anterior.

O que você vai criar: verificações prévias antes de tentar iniciar novas sessões e rotinas de limpeza que são acionadas quando um usuário sai do app principal.

Exemplo de implementação (limpeza de logout)

Encerra qualquer sessão ativa, limpa o token de autenticação em cache do SDK, apaga os dados locais do app e navega até a tela de login. Essa é a limpeza mínima necessária para evitar a herança de sessão ao sair do usuário.

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()
    }
}

Integração de corrotinas e fluxo do Kotlin

O SDK para dispositivos móveis sem interface para Android foi projetado com base em corrotinas do Kotlin e Flow como os principais padrões reativos. Esse é o equivalente para Android da integração do Combine do SDK para iOS.

O que o SDK oferece: fluxos do Kotlin Flow e funções de suspensão que emitem eventos do SDK em tempo real (mensagens recebidas, mudanças no estado de compartilhamento de tela) como fluxos reativos observáveis.

O que você vai criar: integrações baseadas em corrotinas que coletam esses fluxos e atualizam a interface do Android de acordo com eles.

Funções de suspensão

Muitos métodos de serviço do SDK são funções de suspensão do Kotlin, o que significa que podem ser chamados de dentro de um escopo de corrotina e serão suspensos (não bloqueados) enquanto aguardam um 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)
    }
}

Fluxos de serviço de chat

O chatService expõe as propriedades SharedFlow do Kotlin para observar eventos de chat em tempo real. Colete-os em um escopo de corrotina que reconhece o ciclo de vida (lifecycleScope ou viewModelScope).

Flow Emite
messagesReceived Listas de mensagens de chat recebendo chat (de agentes, assistentes virtuais ou do sistema).
typingEvent Quando um usuário ou agente está digitando.
memberEvent Quando um usuário ou agente entra ou sai do chat (incluindo transferências e desconexões de agentes).
stateChanged Mudanças de estado do provedor de chat (conectando, conectado, desconectado, erro).
chatReceived Dados de resposta do chat quando um chat é recebido ou atualizado (incluindo mudanças de status, atribuição de agente e estado pós-sessão).

O chatService expõe outros fluxos para eventos de transferência (transferEventSubject), resultados de verificação de status (checkStatusSubject) e resultados de envio de mensagens (messageSendResultSubject).

Exemplo de implementação

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 do compartilhamento de tela

O que o SDK oferece: o estado da sessão de compartilhamento de tela é entregue pelo callback onSessionStateChanged em ScreenShareCallbacks, que você transmite para ScreenShareManager.startSession(). Consulte SDK para dispositivos móveis headless para Android: voz, compartilhamento de tela, chamada agendada e e-mail. O callback é acionado sempre que a sessão faz a transição entre INACTIVE, PENDING e ACTIVE.

O que você cria: um gerenciador conectado ao ScreenShareCallbacks.onSessionStateChanged que atualiza a UI conforme a sessão transita entre estados, além de uma propriedade local (por exemplo, currentScreenShareSessionState) se você precisar ler o estado atual fora do callback.

Exemplo de implementação

Além do caminho ScreenShareCallbacks, o ScreenShareManager também expõe APIs addStateChangeListener / removeStateChangeListener independentes e um acessador getSessionState() síncrono. Use-os quando precisar observar o estado de um componente diferente daquele que chamou startSession() ou para fazer uma leitura única não reativa. Ao contrário do caminho ScreenShareCallbacks, em que o callback é liberado automaticamente quando a sessão termina, os listeners independentes não são liberados de forma automática. Chame removeStateChangeListener(...) na desmontagem do proprietário do ciclo de vida para evitar vazamentos.

// 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)

Dados personalizados

O que o SDK oferece: um mecanismo para anexar metadados estruturados a sessões de chat, seja como JWTs assinados (verificados pelo seu back-end) ou como payloads não assinados (definidos diretamente no cliente).

O que você cria: a lógica de coleta de dados no seu app e, para dados assinados, o endpoint de assinatura de JWT no seu servidor de back-end (consulte SDK para dispositivos móveis headless para Android: primeiros passos para ver o esquema completo de autenticação e payload de JWT).

Dados personalizados assinados

Os dados personalizados assinados usam um token JWT assinado com o secret da sua empresa no servidor de back-end. Essa é a abordagem segura para transmitir dados sensíveis ou confiáveis.

Exemplo de implementação

Crie um objeto de dados personalizados assinado com base em um JWT gerado no seu back-end.

// JWT signed with company secret (signing must happen on your backend)
val customData = CustomData(signed = "header.payload.signature")

Dados personalizados não assinados

Os dados personalizados não assinados são definidos diretamente no cliente usando CustomDataPayload e CustomDataItem.

Exemplo de implementação

Crie um payload não assinado com itens de dados visíveis e ocultos do agente. CustomDataPayload usa um MutableMap<String, CustomDataItem?>. Portanto, use a atribuição de subscrito (ou mutableMapOf) para adicionar cada item por chave. A chave escolhida (por exemplo, "user_name" ou "account_tier") se torna o nome do campo exibido para o agente e para o roteamento/análise.

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)

Os itens de dados personalizados são compatíveis com as seguintes propriedades:

  • label: rótulo de exibição mostrado ao agente.

  • value: o valor dos dados (exemplos: String, Int, Bool).

  • type: tipo de dados (STRING, NUMBER, DATE, URL, BOOLEAN).

  • invisibleToAgent: quando true, os dados ficam ocultos para os agentes, mas disponíveis para roteamento e análise.

Como usar dados personalizados em solicitações de chat

Anexe dados personalizados ao iniciar uma sessão de chat.

Exemplo de implementação

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

Transferência de chat externo

O que o SDK oferece: uma estrutura de dados (ExternalChatTransfer) para transmitir o nome de um agente anterior e a transcrição da conversa para uma nova sessão da plataforma CCAI.

O que você vai criar: o fluxo de migração que extrai o contexto do seu sistema de chat externo e o empacota para o SDK.

Exemplo de implementação

Esse código cria um objeto de transferência de chat externo com o nome do agente anterior e o anexa aos dados personalizados da sessão.

// 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)

Isso é útil ao migrar um usuário de um sistema de chat de terceiros para uma sessão com tecnologia da plataforma CCAI, preservando o contexto da conversa para o agente receptor.

Considerações sobre linhas de execução

O SDK para dispositivos móveis sem interface para Android foi projetado para funcionar com corrotinas do Kotlin e é, em grande parte, seguro para a linha de execução principal. No entanto, há considerações importantes sobre as linhas de execução para integrações headless.

Concorrência segura da linha de execução principal

Todos os métodos do SDK são thread-safe e podem ser chamados de qualquer thread. A maioria das chamadas de serviço do SDK (por exemplo, chatService?.start(), queueMenuService?.get()) são funções de suspensão que processam as próprias linhas de execução internamente, suspendendo a corrotina de chamada sem bloquear a linha de execução. Você pode chamá-las com segurança na linha de execução principal em um escopo de corrotina:

// 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 e linhas de execução em segundo plano

O método ccaiShouldAuthenticate() no CCAIDelegate é uma função de suspensão. Portanto, é possível realizar chamadas de rede com segurança:

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

Atualizações da interface de callbacks do SDK

Ao observar eventos do SDK usando o Flow, verifique se as atualizações da UI acontecem na linha de execução principal. Se você usar lifecycleScope, isso será feito automaticamente:

// lifecycleScope dispatches to Main by default
lifecycleScope.launch {
    chatMessagesFlow.collect { messages ->
        // Already on Main - safe to update UI
        chatAdapter.submitList(messages)
    }
}

Se você coletar de um dispatcher que não seja o principal, volte explicitamente:

lifecycleScope.launch(Dispatchers.IO) {
    // Processing on IO thread
    val processed = heavyProcessing()
    withContext(Dispatchers.Main) {
        // Update UI on Main thread
        updateChatUi(processed)
    }
}

Conversas de inicialização

CCAI.initialize() e as chamadas de inicialização de módulos relacionados, como initializeChat(), initializeCall() e initializeScreenShare(), precisam ser chamadas na linha de execução principal no Application.onCreate(). Essas são chamadas síncronas que configuram o estado interno do 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)
    }
}

Gerenciamento de memória

O gerenciamento de memória adequado é essencial para evitar vazamentos e garantir a remoção limpa dos recursos do SDK.

Ciclo de vida de corrotinas e fluxos

Sempre cancele as referências de corrotina Job e os coletores de fluxo nos métodos de ciclo de vida do Android (onDestroy() para atividades, onCleared() para ViewModels). Caso contrário, as referências podem permanecer ativas por mais tempo do que o esperado, causando vazamentos de memória.

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()
    }
}

Referências de listener e callback

Use referências fracas para listeners e callbacks para evitar ciclos de retenção. Limpe todos os callbacks registrados quando a atividade ou o ViewModel for destruído.

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áticas recomendadas

  • Armazenar referências de corrotina Job: sempre armazene as referências de Job retornadas por launch {} para evitar corrotinas descontroladas que ultrapassem o escopo.

  • Limpar nos métodos de ciclo de vida: cancele todos os jobs e limpe os callbacks em onDestroy() (atividades) ou onCleared() (ViewModels).

  • Use referências fracas para listeners: tenha cuidado com lambdas que capturam implicitamente this (o contexto da atividade ou do fragmento que os envolve), já que isso pode impedir a coleta de lixo.

  • Os serviços são gerenciados pelo SDK: não é necessário liberar manualmente os serviços do SDK, porque eles são gerenciados pelo objeto singleton CCAI.

Solução de problemas

Esta seção aborda problemas comuns de integração e as soluções para eles.

Problemas de build e dependência

Esta seção aborda problemas comuns de build e dependência.

Problema

O Gradle não consegue resolver com.ccaiplatform.android:CCAIKit.

  • Causa: o repositório Maven da CCAI está ausente ou usa o URL errado.

  • Correção: verifique se o settings.gradle.kts inclui:

    maven { url = uri("https://sdk.ujet.co/ccaip/android/") }
    

    Observe o segmento de caminho /ccaip/. O URL legado (https://sdk.ujet.co/android/) não vai resolver artefatos.

Problema

Erros de compilação necessários do Java 17.

  • Causa: esse SDK requer compatibilidade com o Java 17.

  • Correção: atualize o build.gradle.kts:

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
    kotlinOptions {
        jvmTarget = "17"
    }
    

Problema

chatLibraryNotFound (código do erro 1100) no momento da execução.

  • Causa: o módulo CCAIChatRed está ausente das dependências.

  • Correção: CCAIChat e CCAIChatRed são obrigatórios para o chat. Adicionar:

    implementation("com.ccaiplatform.android:CCAIChat:ccaiVersion")
    implementation("com.ccaiplatform.android:CCAIChatRed:ccaiVersion")
    

Problemas de inicialização

Esta seção aborda problemas comuns de inicialização.

Problema

NullPointerException ao acessar CCAI.chatService.

  • Causa: CCAI.initializeChat() não foi chamado ou foi chamado antes de CCAI.initialize().

  • Correção: garanta a ordem de inicialização em Application.onCreate():

    1. CCAI.initialize(context, options = initOptions)

    2. CCAI.initializeChat(context, options = chatOptions)

    3. CCAI.initializeCall(context) (se estiver usando chamadas de voz ou agendadas)

    4. CCAI.initializeScreenShare(context, options) (se estiver usando o compartilhamento de tela)

Problema

Os serviços do SDK retornam null após a inicialização.

  • Causa: CCAI.initialize() não foi chamado na linha de execução principal ou a classe Application não está registrada no manifesto.

  • Correção: verifique se a linha android:name=".MainApplication" está presente no arquivo AndroidManifest.xml e se todas as chamadas de inicialização estão em onCreate().

Problemas de autenticação

Esta seção aborda problemas comuns de autenticação.

Problema

A autenticação falha silenciosamente ou ccaiShouldAuthenticate() nunca é chamado.

  • Causa: CCAIDelegate não foi definido em InitOptions.

  • Correção: verifique se delegate foi transmitido para InitOptions:

    val initOptions = InitOptions(
        key = "YOUR_KEY",
        urlHost = "your_subdomain.ccaiplatform.com",
        delegate = MyCCAIDelegate()  // Must not be null
    )
    

Problema

Erros de validação de JWT (código do erro 101).

  • Causa: o JWT expirou, está malformado ou foi assinado com o secret errado.

  • Correção: verifique se o back-end:

    • Usa o código secreto correto da empresa.

    • Define carimbos de data/hora válidos de iat e exp.

    • Retorna uma string JWT formatada corretamente.

Problemas com notificações push

Esta seção aborda problemas comuns com notificações push.

Problema

As notificações push não estão sendo recebidas ou processadas.

  • Causa: o token do FCM não está registrado no SDK, o serviço de mensagens do Firebase não está registrado ou os payloads de dados recebidos não estão sendo encaminhados para o SDK.

  • Correção:

    • Chame CCAI.pushNotificationService?.updatePushToken(token) em onNewToken() e na inicialização.

    • Encaminhe remoteMessage.data para CCAI.pushNotificationService?.handlePushNotification(remoteMessage.data) do seu serviço de mensagens do Firebase.

    • Verifique se google-services.json está no módulo do app.

    • Verifique se a chave da conta de serviço do Firebase está configurada no portal de administração da plataforma CCAI.

    • Renderize qualquer notificação visível ou UI de chamada recebida no código do seu app.

Problema

O SDK não reage às notificações push recebidas (as mensagens são ignoradas).

  • Causa: transmissão do tipo de dados errado para o método handlePushNotification().

  • Correção: transmita remoteMessage.data (que é um Map<String, String>), não o objeto RemoteMessage inteiro.

Problemas com a sessão de chat

Esta seção aborda problemas comuns de sessões de chat.

Problema

chatService?.start() gera uma exceção ou retorna null.

  • Causa: menuId inválido, falha de autenticação ou problema de rede.

  • Correção:

    • Verifique se o menuId corresponde a uma fila válida no portal do administrador.

    • Verifique se ccaiShouldAuthenticate() troca um JWT assinado válido por CCAI.authService?.authenticate(jwt) e retorna o token de autenticação resultante.

    • Verifique se o dispositivo tem conectividade de rede.

    • Envolva a chamada em um try ou catch e registre os detalhes da exceção.

Problema

As mensagens de chat não aparecem na UI.

  • Causa: o fluxo de mensagens do serviço de chat não está sendo observado.

  • Correção: verifique se você está coletando do fluxo do serviço de chat em um escopo que reconhece o ciclo de vida (consulte a seção Fluxos do serviço de chat acima).

Problemas com o compartilhamento de tela

Esta seção aborda problemas comuns de compartilhamento de tela.

Problema

O compartilhamento de tela não começa depois que o usuário dá o consentimento.

  • Causa: o módulo CCAIScreenShare não foi inicializado ou o MediaProjection do Android não foi iniciado.

  • Correção:

    • Verifique se CCAI.initializeScreenShare() é chamado com um ScreenShareOptions válido.

    • Verifique se você está iniciando corretamente o MediaProjectionManager e o serviço em primeiro plano do Android após o consentimento.

    • No Android 14 ou versões mais recentes, verifique se o tipo de serviço em primeiro plano inclui mediaProjection.

Dicas gerais de depuração

  • Ative o registro detalhado durante o desenvolvimento para ver o estado interno do SDK.

  • Verifique o portal do administrador da plataforma CCAI para conferir a configuração da fila, a ativação do canal e o horário de funcionamento.

  • Monitore o tráfego de rede com ferramentas como o Charles Proxy ou o Network Inspector do Android Studio para verificar as chamadas de API para *.ccaiplatform.com.

  • Verifique se as versões dos módulos são iguais: todos os módulos com.ccaiplatform.android precisam usar o mesmo número de versão para evitar problemas de compatibilidade.

Finalização da série

Parabéns! Você concluiu a série de cinco partes sobre o SDK para Dispositivos Móveis sem Interface para Android. Sua integração agora abrange:

Para referência contínua, adicione aos favoritos a Referência da API Android do SDK para dispositivos móveis sem interface e fique de olho nas notas da versão da plataforma CCAI para atualizações do SDK.