Android SDK

Requisitos#

• minSdk 24 (Android 7.0), compileSdk 35.
• Kotlin 2.x e Jetpack Compose (o SDK inclui UI em Compose).
• JVM target 17.

O SDK arrasta as suas próprias dependências transitivas (Coroutines, kotlinx.serialization, OkHttp, Coil, Compose) e declara a permissão INTERNET no seu manifest — nada a acrescentar à mão.

Instalação#

A biblioteca é publicada no Maven Central como ai.respondo:respondo-sdk. Certifique-se de que mavenCentral() está nos seus repositórios (já vem por padrão em um novo projeto Android) e depois adicione a dependência pela coordenada.

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
    }
}

dependencies {
    implementation("ai.respondo:respondo-sdk:0.1.0")
}

Inicializar#

Chame Respondo.init uma vez, monte RespondoChatHost() uma vez na sua árvore Compose, e abra o chat a partir do seu próprio botão.

import ai.respondo.sdk.Respondo
import ai.respondo.sdk.RespondoConfig
import ai.respondo.sdk.ui.RespondoChatHost

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        Respondo.init(
            context = this,
            config = RespondoConfig(
                agentId = "<agent-uuid>",   // do dashboard
                channelId = "<channel-uuid>", // opcional
                // baseUrl omitido -> https://api.respondo.ai
            ),
        )

        setContent {
            MaterialTheme {
                Box(modifier = Modifier.fillMaxSize()) {
                    Button(onClick = { Respondo.open() }) { Text("Support") }
                    RespondoChatHost() // o SDK mostra o sheet quando o estado do chat é OPEN
                }
            }
        }
    }
}

Todas as chamadas passam pelo singleton Respondo. São idempotentes, seguras a partir de qualquer thread, e as chamadas feitas antes de a init terminar são armazenadas em buffer e reproduzidas.

Identificar usuários#

Por padrão, todos os visitantes são anônimos. Na primeira execução o SDK gera um visitor_id estável e o salva no armazenamento local, para que um usuário que retorna encontre novamente a sua conversa. Não há nenhuma chave de API para embutir — cada conversa é protegida por um token de sessão por conversa que o backend emite e renova a cada mensagem, para que um visitante anônimo nunca precise se autenticar de novo.

Chame identify assim que o seu usuário estiver autenticado. Isso associa a identidade real, para que o histórico o acompanhe entre dispositivos e reinstalações, e o nome e o e-mail apareçam junto à conversa na sua caixa de entrada em vez de um visitante anônimo.

O userHash é uma assinatura que o seu backend calcula a partir do identity_secret do agente — HMAC-SHA256(secret, userId) (ou o e-mail quando não há userId), codificado em hexadecimal minúsculo. O segredo prova que a identidade é genuína, por isso deve viver apenas no seu backend e nunca é enviado na app. Consulte a página Verificação de identidade para a fórmula completa e exemplos do lado do servidor.

import ai.respondo.sdk.RespondoIdentity

// O userHash vem do seu backend (HMAC-SHA256 sobre o userId) —
// nunca o calcule no app.
Respondo.identify(
    RespondoIdentity(
        userId = session.userId,
        email = session.email,
        name = session.fullName,
        userHash = session.respondoUserHash,
    ),
)

// No logout: descarte o token de push, revogue a sessão, inicie um novo visitante anônimo.
Respondo.clearPushToken()
Respondo.reset()

Se o hash estiver ausente ou errado, nada é lançado: o backend mantém silenciosamente o visitante anônimo, o chat continua funcionando, e apenas perde o vínculo entre dispositivos até ser fornecido um hash válido. A verificação só roda quando o agente tem um identity_secret definido — deixe-o vazio durante o desenvolvimento e userId / e-mail são aceites tal como estão.

Observáveis & callbacks#

Leia o estado de forma reativa como StateFlow (ótimo para Compose) ou de forma imperativa via RespondoListener (ótimo para um badge no ícone do app).

// Reativo: contagem de não lidas como um StateFlow.
val unread by Respondo.unreadCount.collectAsState()

// Imperativo: listener para badges e analytics.
Respondo.setListener(object : RespondoListener {
    override fun onUnreadChanged(count: Int) { updateAppIconBadge(count) }
    override fun onUrlRequested(url: String): Boolean = tryOpenInternally(url)
})

Rastreamento de tela#

Informe a tela atual em cada navegação para que os teasers proativos e a segmentação no nível da página possam corresponder a ela. Passe null para limpá-la; a cada mudança, o teaser proativo é reavaliado para a nova tela.

Respondo.setCurrentScreen("pricing")

Próximos passos#

Configure as Notificações push para respostas de atendentes offline e a Verificação de identidade para usuários autenticados. A superfície completa da API, o wrapper Fragment para hosts XML e a resolução de problemas são abordados no guia de introdução do Android SDK; o código-fonte do SDK é público no GitHub.