合从文档中心

Appearance

装进 Android ​

加一行依赖、写两行代码，APP 里就有了客服入口。

开始之前 ​

  • 一个渠道 ID，工作台 App 渠道的 SDK 接入 页把它嵌在初始化代码里，也可以在 开发者 页的 接入参数 卡单独复制，见创建 App 渠道
  • APP 的 minSdk 不低于 21（Android 5.0）
  • 工程能从 Maven Central 拉依赖

动手之前可以先跑一遍示范 App：扫码装上，填进你的渠道 ID 就连到你的工作台。先确认渠道和账号这一侧是通的，之后自己集成再出问题，范围就缩小到你的工程配置。

操作步骤 ​

1. 确认仓库里有 Maven Central ​

合从的 SDK 发布在 Maven Central。用 Android Gradle Plugin 7.0 及以上的工程，仓库声明在 settings.gradle.kts 的 dependencyResolutionManagement 里；更早的工程在根 build.gradle 的 allprojects 里。两处都是同一件事：确保 mavenCentral() 在列表中。

新建的 Android 工程默认就有，多数情况下这一步不用改动。

2. 加依赖 ​

在 APP 模块的 build.gradle.kts 里加一行：

kotlin
dependencies {
    implementation("com.aihecong:hecong-chat-sdk:0.6.4")
}

用 Groovy DSL 的工程写成 implementation 'com.aihecong:hecong-chat-sdk:0.6.4'。

已发布的版本都列在 Maven Central 制品页。

同步 Gradle，依赖就位。

3. 登记渠道 ID ​

在 APP 启动流程里调一次 configure，把渠道 ID 交给 SDK：

kotlin
HecongChat.configure(this, HecongChatConfig("你的渠道ID"))

这一步只登记参数，不产生任何网络请求，也不收集任何信息。

放在用户同意隐私政策之后

虽然这一步本身零联网，仍建议放在用户同意隐私政策之后再调用。国内应用市场审核会检查 SDK 初始化的时机，把所有第三方 SDK 的初始化统一放在同意之后，是通过审核最省事的做法。

想让客户第一次点开客服更快，configure 之后可以再调一次 HecongChat.prewarm(this)，SDK 会提前把聊天页的首屏文件下到缓存。这一步会联网，必须放在用户同意隐私政策之后；不调也能正常用，只是第一次打开要多等一下。

4. 打开客服 ​

在「联系客服」的点击事件里：

kotlin
HecongChatActivity.start(this, HecongChatConfig("你的渠道ID"))

到这里就能用了。聊天页整页打开，顶部一条标题栏写着「在线客服」，左上角是返回 —— 标题可以改成你自己的，配置项见聊天页的四种形态。

你不需要在 AndroidManifest.xml 里声明这个页面，也不需要配 windowSoftInputMode，SDK 的 manifest 里已经声明好，合并到你的 APP 时自动生效。选文件、拍照、实体返回键、前后台切换这些系统回调，这一档全部内置，你不用转发。

打开客服还有另外三种方式：半屏弹层、嵌进自己的 Tab、整屏沉浸。调用方法各不相同，效果对比见聊天页的四种形态 —— 四档共用同一套配置，换档不影响你已经接好的东西。

5. 声明要用到的权限 ​

权限需要你在自己的 AndroidManifest.xml 里声明，SDK 自身不声明任何权限：

xml
<!-- 要让客户按住说话发语音，这两条必须一起声明 -->
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
<!-- 要让客户直接拍照或拍视频发给客服 -->
<uses-permission android:name="android.permission.CAMERA" />

按功能声明，用到哪个声明哪个。只让客户打字、发相册照片和文件的话，一条都不用声明：选照片走系统选择器，不需要存储权限。漏声明不会崩，症状是对应入口失效：没声明相机，拍摄入口点了没反应；没声明麦克风，发语音会提示权限未开启。

语音那两条要成对声明

MODIFY_AUDIO_SETTINGS 不能省。系统挑录音设备时会同时看这两条，少一条就当作没有可用的麦克风，而表现很容易看岔：客户点了 允许，界面仍然提示麦克风被占用，重试、重启 APP 都没用。缺的是安装包里的声明，运行时怎么操作都补不回来。

它是安卓的普通权限，装上就有，不弹窗、也不采集任何东西。

国内应用市场对权限审核得很严，这一块 SDK 已经按审核要求做好，你不用写代码：

  • 申请前先弹用途说明：审核要求申请敏感权限时同步告知用途，SDK 在系统弹窗之前先弹一层说明，写清这次要什么权限、用来做什么
  • 只在客户点了功能时申请：不在启动时弹，被拒后也不自动重试
  • SDK 自身清单里零权限声明：不会往你的 APP 里带进任何多余权限

审核如果要求说明弹窗用你自己的文案或样式，可以改，见权限说明与应用市场审核。

多进程 APP 要先做一步

你的 APP 如果是多进程架构，需要在任何 WebView 创建之前给非主进程设数据目录后缀，否则会直接崩溃。做法见兼容性核对。

验证接入成功 ​

把 APP 装到手机或模拟器上，点开客服，你应该看到一个带欢迎语的对话界面。发一条消息，在客服工作台的对话列表里能看到它。

App 渠道的会话不能在浏览器里验证，原因见 APP 接入概述。

用 Java 写 ​

SDK 的公共接口都可以从 Java 直接调用：

java
import com.hecong.chatsdk.HecongChat;
import com.hecong.chatsdk.HecongChatActivity;
import com.hecong.chatsdk.HecongChatConfig;

// APP 启动时
HecongChatConfig config = new HecongChatConfig("你的渠道ID");
HecongChat.configure(this, config);

// 打开客服
HecongChatActivity.start(this, config);

常见问题 ​

编译时找不到 com.aihecong:hecong-chat-sdk ​

症状：Gradle 同步报 Could not find com.aihecong:hecong-chat-sdk:0.6.4。

成因：仓库列表里没有 mavenCentral()，或者用了国内镜像、公司内部代理而对方还没同步到这个版本。

解决：先按步骤 1 确认 mavenCentral() 在列表里。用镜像或内部代理的工程，按报错里 Searched in the following locations 列的地址分辨具体是哪一种，见接入问题排查。

点开客服是一片空白 ​

症状：客服页面打开了，但里面什么都没有。

成因：多数是网络问题，设备连不上合从的服务，或者被 APP 里的网络拦截库挡住了。

解决：确认设备网络正常，检查 APP 里有没有对 WebView 请求做拦截或代理。断网时 SDK 会显示一张带重试的提示页，看到那张页面说明 SDK 本身正常。

客户在 APP 里退出登录后，下一个人看到了上一个人的记录 ​

症状：同一台设备上换个账号登录，客服对话里还是上一位的历史消息。

成因：退出登录时没有通知 SDK 解绑身份。

解决：在退出登录的流程里调 HecongChat.resetUser()，见传客户资料与退出登录。

上线前对照一遍 ​

装通了只是第一步，下面这些漏掉的症状都比较隐蔽，上线前逐条确认：

  • [ ] 退出登录时调了 resetUser()。不调的话，下一个在同一台设备登录的人会看到上一位的聊天记录（做法）
  • [ ] 多进程 APP 设了 WebView 数据目录后缀，不设会直接崩溃（做法）
  • [ ] 真机切到后台，工作台里这位客户变成离线。不变说明前后台事件没接，离线推送一条都不会发（做法）
  • [ ] 配了离线消息通知的话，服务端真收到过一次回调（怎么自测）
  • [ ] 要做未读红点的话，调了 startUnreadTracking()（做法）
  • [ ] 用到语音或拍照的话，AndroidManifest.xml 里声明了对应权限（做法）
  • [ ] 提交应用市场前，按隐私合规与信息公示把 SDK 公示信息填进你的隐私政策 —— 漏了会被打回

下一步 ​