帮你快速理解、总结文档立即下载
文档中心>即时通信 IM>智能客服（Desk）>工作台接入>SDK 集成>Android 集成

Android 集成

最近更新时间：2026-07-28 12:14:03

我的收藏

本页目录：

说明：
本文档介绍如何在 Android 工程中集成智能客服工作台 SDK。

环境要求

项
要求
Android Studio
Hedgehog (2023.1.1) 及以上
minSdk
≥ 24（Android 7.0）
compileSdk / targetSdk
34
JDK / Kotlin JVM target
17
AGP
推荐 8.5.2
Gradle
8.4+
Kotlin
2.0.x

引入依赖

配置 Maven 仓库

需在工程的 settings.gradle.kts 中声明：
// settings.gradle.kts
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        // Desk Customer SDK 自身
        maven { url = uri("https://customer.qcloudclass.com/workstation/maven/") }
        // 腾讯云 IM SDK（imsdk-plus）
        maven { url = uri("https://mirrors.tencent.com/repository/maven/liteavsdk/") }
        // 坐席工作台底层 SDK（com.tencent.cloud.ccc.workstation:sdk）
        maven { url = uri("https://www.tencentclass.net/resources/workstation/android/maven") }
    }
}

添加 SDK 依赖

在 App 模块的 build.gradle.kts 中添加：
android {
    defaultConfig {
        minSdk = 24
    }
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
    kotlinOptions { jvmTarget = "17" }
}

dependencies {
    implementation("com.desk.customer:deskcustomer-ui:0.1.3")
}
说明：
网络权限（INTERNET / ACCESS_NETWORK_STATE / ACCESS_WIFI_STATE）已在 SDK 内部声明，接入方无需重复添加。

初始化

在 Application.onCreate 中调用一次。

Kotlin

import android.app.Application
import com.desk.customer.DeskCustomer
import com.desk.customer.DeskInitConfig

class App : Application() {
    override fun onCreate() {
        super.onCreate()
        val config = DeskInitConfig.Builder(/* sdkAppId = */ 1_400_000_000).build()
        DeskCustomer.init(this, config)
    }
}

Java

import android.app.Application;
import com.desk.customer.DeskCustomer;
import com.desk.customer.DeskInitConfig;

public class App extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        DeskInitConfig config = new DeskInitConfig.Builder(1_400_000_000).build();
        DeskCustomer.init(this, config);
    }
}

登录

调用 DeskCustomer.login 完成登录。token 由您的业务后端调用 token 签发接口 签发。

Kotlin

import com.desk.customer.DeskCustomer
import com.desk.customer.DeskLoginParams
import com.desk.customer.core.DeskCallback
import com.desk.customer.core.DeskError

val params = DeskLoginParams.Builder()
    .userId("agent_001")
    .token(token)
    .origin("https://tccc.qcloud.com")
    .build()

DeskCustomer.login(params, object : DeskCallback {
    override fun onSuccess() {
        runOnUiThread {
            startActivity(DeskCustomer.openWorkbench(this@MainActivity))
        }
    }
    override fun onError(error: DeskError) {
        // 见 §7 错误处理
    }
})

Java

import com.desk.customer.DeskCustomer;
import com.desk.customer.DeskLoginParams;
import com.desk.customer.core.DeskCallback;
import com.desk.customer.core.DeskError;
import androidx.annotation.NonNull;

DeskLoginParams params = new DeskLoginParams.Builder()
        .userId("agent_001")
        .token(token)
        .origin("https://tccc.qcloud.com")
        .build();

DeskCustomer.login(params, new DeskCallback() {
    @Override public void onSuccess() {
        startActivity(DeskCustomer.openWorkbench(MainActivity.this));
    }
    @Override public void onError(@NonNull DeskError error) {
        // 见 §7 错误处理
    }
});
注意：
DeskCallback 回调可能在非主线程触发，UI 操作请自行切回主线程。

拉起坐席工作台

登录成功后，使用返回的 Intent 拉起工作台 Activity：

Java

startActivity(DeskCustomer.openWorkbench(this))

Kotlin

startActivity(DeskCustomer.openWorkbench(this));
如需从登录页跳转并清空登录页栈：

import android.content.Intent
val intent = Intent(this, TargetActivity::class.java)
    intent.flags = Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TASK
startActivity(intent)
startActivity(intent)

登出

DeskCustomer.logout(object : DeskCallback {
    override fun onSuccess() { /* 已退出 */ }
    override fun onError(error: DeskError) { /* ... */ }
})
DeskCustomer.logout(new DeskCallback() {
    @Override public void onSuccess() { /* 已退出 */ }
    @Override public void onError(@NonNull DeskError error) { /* ... */ }
});
如不关心结果，Kotlin 可使用默认参数省略回调：DeskCustomer.logout()；Java 传 null 即可。

错误处理

错误对象 DeskError：
data class DeskError(
    val code: Int,
    val message: String,
    val imCode: Int? = null,
    val imDesc: String? = null,
    val cause: Throwable? = null,
)
错误码（com.desk.customer.core.DeskCustomerErrorCode）：
常量
值
触发场景
NOT_INITIALIZED
-1
未调用 init(...) 就 login
INVALID_PARAMETER
-2
userId / token / origin 任一为空，或 sdkAppId <= 0
IM_LOGIN_FAILED
-3
腾讯云 IM 登录失败；imCode / imDesc 透传 IM 原始信息
WORKSTATION_LOGIN_FAILED
-4
业务侧登录失败（token 过期 / 网络错误等）
错误判断示例：
override fun onError(error: DeskError) {
    when (error.code) {
        DeskCustomerErrorCode.TOKEN_EXPIRED ->
            showDialog("登录失败，请检查 token 是否过期")
        
            showDialog("IM 登录失败：${error.imCode} ${error.imDesc}")
        else ->
            showDialog(error.message)
    }
}

权限与配置（零配置）

聊天页涉及麦克风 / 相机 / 相册 / 文件选择四类系统能力，SDK 已把所需的 <uses-permission> / <uses-feature> / <queries> / FileProvider 全部声明在自己的 AndroidManifest.xml 中，通过 manifest merge 自动继承到您的 App，接入方无需任何额外配置。

SDK 已声明的清单

清单项
用途
说明
android.permission.RECORD_AUDIO
聊天页语音消息按住说话录音
运行时权限申请由 SDK 内部触发；用户拒绝仅弹提示，不影响其它能力
android.permission.CAMERA + <uses-feature android:name="android.hardware.camera" android:required="false"/>
聊天页更多面板拍照发送图片
required="false" 保证无相机的设备也能上架；运行时权限申请由 SDK 内部触发
<queries> × 5（IMAGE_CAPTURE / VIDEO_CAPTURE / GET_CONTENT / OPEN_DOCUMENT / PICK）
Android 11 (API 30) 起的包可见性声明
缺失会导致 Intent.resolveActivity() 返回 null，拍照 / 相册 / 文件选择器全部拉不起来
androidx.core.content.FileProvider，authority = ${applicationId}.desk.customer.fileprovider
拍照高清方案 EXTRA_OUTPUT + 媒体消息本地拷贝目录
authority 带 desk.customer 命名空间隔离，不会与您工程内其它 FileProvider 冲突

本地通知（IM 呼入）

当坐席收到新会话呼入（imCallin）时，SDK 会自动发出一条本地通知，通知内容包含客户昵称与渠道信息。

申请通知权限

Android 13（API 33）起，发送通知需要运行时权限 POST_NOTIFICATIONS。SDK 不主动申请（避免污染接入方工程），接入方需完成以下两步：
步骤1：在 AndroidManifest.xml 中声明权限：
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
步骤2：在合适时机动态申请，例如在 MainActivity.onCreate 中：
import android.Manifest
import android.os.Build
import androidx.activity.result.contract.ActivityResultContracts

// 在 Activity 中申请通知权限（Android 13+）
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
    val launcher = registerForActivityResult(
        ActivityResultContracts.RequestPermission()
    ) { granted ->
        // granted = true 时 SDK 才能发出通知
    }
    launcher.launch(Manifest.permission.POST_NOTIFICATIONS)
}
import android.Manifest;
import android.os.Build;
import androidx.activity.result.ActivityResultLauncher;
import androidx.activity.result.contract.ActivityResultContracts;

// Java 示例
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
    ActivityResultLauncher<String> launcher = registerForActivityResult(
        new ActivityResultContracts.RequestPermission(),
        granted -> {
            // granted = true 时 SDK 才能发出通知
        }
    );
    launcher.launch(Manifest.permission.POST_NOTIFICATIONS);
}
说明：
Android 12 及以下无需申请，系统默认允许发送通知。

通知行为说明

行为
说明
触发时机
收到 imCallin 事件时立即发出。
通知渠道
desk_im_callin，重要性 IMPORTANCE_HIGH（抬头通知 + 铃声）。
自动撤销
接听、会话结束、超时、登出时自动撤销对应通知。
前台 / 后台
前台与后台均发出通知。
无权限时
仅打印日志，不触发崩溃，不影响其他功能运行。
中国站