Android SDK
一个轻量的 Kotlin 与 Jetpack Compose 客户端，以底部弹出面板的形式在您的应用之上打开 Respondo 客服聊天。
环境要求#
minSdk24（Android 7.0），compileSdk 35。- Kotlin 2.x 和 Jetpack Compose（SDK 自带 Compose UI）。
- JVM target 17。
SDK 会自行拉取它的传递依赖（Coroutines、kotlinx.serialization、OkHttp、Coil、Compose）， 并在其清单中声明 INTERNET 权限——无需手动添加任何东西。
安装#
该库以 ai.respondo:respondo-sdk 的形式发布到 Maven Central。请确保您的仓库中包含 mavenCentral()（在新建的 Android 项目中默认已有），然后按坐标添加依赖即可。
dependencyResolutionManagement {
repositories {
google()
mavenCentral()
}
}dependencies {
implementation("ai.respondo:respondo-sdk:0.1.0")
}初始化#
调用一次 Respondo.init ，在您的 Compose 树中挂载一次 RespondoChatHost() ，然后从您自己的按钮打开聊天。
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>", // 来自控制台
channelId = "<channel-uuid>", // 可选
// 省略 baseUrl -> https://api.respondo.ai
),
)
setContent {
MaterialTheme {
Box(modifier = Modifier.fillMaxSize()) {
Button(onClick = { Respondo.open() }) { Text("Support") }
RespondoChatHost() // 当聊天状态为 OPEN 时，SDK 显示面板
}
}
}
}
}所有调用都通过 Respondo 单例进行。 它们是幂等的，可在任意线程安全调用；在 init 完成之前发起的调用会被缓冲并在之后重放。
识别用户#
默认情况下，每位访客都是匿名的。首次启动时，SDK 会生成一个稳定的 visitor_id 并保存在本地存储中，因此回访用户能再次找到自己的对话。 无需在应用中内嵌任何 API 密钥——每个对话都由后端签发的会话令牌（session token）保护， 该令牌按每个对话独立生成，并在每条消息时向前滑动，因此匿名访客永远无需重新认证。
在用户登录之后调用一次 identify。 这会附加上他们的真实身份，使其历史记录能跨设备、跨重装随之保留， 并让他们的姓名和邮箱显示在您收件箱里对话的旁边，而不再是一位匿名访客。
userHash 是 由您的后端根据 agent 的 identity_secret 计算出的签名—— HMAC-SHA256(secret, userId) （当没有 userId 时则用 email），编码为小写十六进制。 该密钥用于证明身份的真实性，因此必须只保存在您的后端，绝不能随应用一起分发。 完整公式和服务器端示例请参见身份校验页面。
import ai.respondo.sdk.RespondoIdentity
// userHash 来自您的后端（对 userId 做 HMAC-SHA256）——
// 切勿在应用中计算它。
Respondo.identify(
RespondoIdentity(
userId = session.userId,
email = session.email,
name = session.fullName,
userHash = session.respondoUserHash,
),
)
// 退出登录时：丢弃推送令牌、吊销会话、开启一个全新的匿名访客。
Respondo.clearPushToken()
Respondo.reset()如果哈希缺失或错误，不会抛出任何异常：后端会静默地让访客保持匿名，聊天照常工作， 您只是在提供有效哈希之前失去跨设备的关联。 仅当 agent 设置了 identity_secret 时才会执行校验—— 在开发阶段将其留空，则 userId / email 会被原样接受。
可观察对象与回调#
您可以以 StateFlow 的方式响应式读取状态（非常适合 Compose）， 或通过 RespondoListener 以命令式读取（非常适合应用图标角标）。
// 响应式：以 StateFlow 形式获取未读数。
val unread by Respondo.unreadCount.collectAsState()
// 命令式：用于角标和分析的监听器。
Respondo.setListener(object : RespondoListener {
override fun onUnreadChanged(count: Int) { updateAppIconBadge(count) }
override fun onUrlRequested(url: String): Boolean = tryOpenInternally(url)
})屏幕跟踪#
在每次导航时上报当前屏幕，以便主动式提示和页面级定向能与之匹配。传入 null 可清除它；每次变化时，主动式提示都会针对新屏幕重新评估。
同一名称会与弹出式调查的界面规则匹配，因此请使用「Checkout」这类稳定标识，而不是翻译后的标题。页面地址规则仅适用于网站。
Respondo.setCurrentScreen("pricing")从代码打开调查#
无论用户在哪个界面，立即打开一个已上线的弹出式调查，忽略 Show on、界面规则、界面停留时间、触发事件和受众。ID 请在调查编辑器（Additional ways to share）中复制。用户已回答过的调查不会再次显示。
Respondo.startSurvey("<survey-id>")