原生 Android 接入

原生 Android SDK 可在 App 内直接打开完整的访客聊天页。普通接入使用 agentvisitor-uikit；需要自行开发聊天界面时使用 agentvisitor-core。

接入准备

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

在项目仓库和依赖中加入 SDK：

repositories {
    google()
    mavenCentral()
    maven { url = uri("https://sdk.99agent.com/maven") }
}

dependencies {
    implementation("com.agent99.visitor:agentvisitor-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", "订单状态", "待发货")
                )
            )
        )
    )
)

权限说明

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

增值服务

原生 Android 接入属于增值服务。如需获取 Android SDK 源码包或安排接入支持，请联系我们。