原生 Android 接入

原生 Android SDK 可在 App 内直接打开完整的访客聊天页。接入完整聊天页时使用交付包中的 visitor-uikit。

增值服务

原生 Android 接入属于单独付费的项目。如需获取 Android SDK 源码包或安排接入支持，请联系我们。

接入准备

• 支持 Android 6.0（API 23）及以上版本。
• 工程需使用 Android Gradle Plugin 8.x 和 JDK 17。
• 正式环境由业务服务端为当前登录用户签发访客令牌。API 密钥只能保存在服务端。

将交付的 Android SDK 源码编译到本地 Maven 仓库：

./gradlew publishReleaseRepository

然后在宿主工程加入该本地仓库，并引入完整聊天页模块：

repositories {
    maven { url = uri(file("../99agent-visitor-android-source/build/maven-repo")) }
    google()
    mavenCentral()
}

dependencies {
    implementation("com.agent99.visitor:visitor-uikit:1.0.0")
}

配置访客身份

在用户登录完成后配置。用户 ID 由业务服务端在访客令牌中确认；客户端配置昵称、头像，以及 attributes（即 visitor.attr 扩展信息）。fetchVisitorToken() 应调用您的业务服务端并返回当前用户的访客令牌；令牌的签发方式请参阅用户基础信息对接。

Visitor.configure(
    context = applicationContext,
    config = VisitorConfig(
        baseUrl = "https://live.99kf.com",
        language = "zh-CN"
    ),
    auth = VisitorAuth.tokenProvider {
        appApi.fetchVisitorToken()
    },
    visitor = VisitorProfile(
        nickname = "张三",
        avatar = "https://www.99kf.com/avatar/12.jpg",
        attributes = listOf(
            VisitorAttribute("phone", "电话", "13800138000"),
            VisitorAttribute("name", "姓名", "张三")
        )
    )
)

其中 phone、name 需与客服端的访客字段设置一致。配置不会立即建立会话。首次打开客服或令牌需要更新时，应用会请求业务服务端取得令牌。

打开聊天页

Visitor.openChat(
    context,
    VisitorChatOptions(
        groupId = 0,
        title = "在线客服"
    )
)

groupId 用于指定客服分组；对应分组中的客服负责接待该入口发起的咨询。

传递业务上下文

打开聊天页时可同时传递商品、订单或其他业务资料，客服无需再向访客重复确认。字段格式和完整示例请参阅商品和订单对接。

Visitor.openChat(
    context,
    VisitorChatOptions(
        groupId = 0,
        contexts = listOf(
            VisitorContext(
                key = "order:ORDER-1001",
                title = "最近订单",
                type = "order",
                fields = listOf(
                    VisitorContextField("status", "订单状态", "待发货")
                )
            )
        )
    )
)

未读计数

可用未读数更新 App 的 Tab 红点或数字：

private val unreadListener = object : VisitorUnreadListenerAdapter() {
    override fun onUnreadCountChanged(count: Int) {
        // 更新宿主 App 红点
    }
}

Visitor.addUnreadListener(unreadListener)
Visitor.unreadCount(object : VisitorCallback<Int> {
    override fun onSuccess(result: Int) {
        // 需要时立即使用当前未读数
    }

    override fun onError(error: VisitorError) = Unit
})

首次成功取得未读数和后续数值变化都会通知监听器。不再需要时调用 Visitor.removeUnreadListener(unreadListener)。

权限说明

网络权限为必需项。若启用拍照、图片/视频选择或语音功能，还需在 AndroidManifest.xml 声明相机、麦克风和媒体读取权限，并在运行时申请用户授权。