合从文档中心

Appearance

兼容性核对 ​

接之前先在这一页对一遍，确认和你的 APP 现有的兼容范围不冲突。

最低系统版本 ​

端要求低于这条线会怎样
AndroidAPI 21（Android 5.0）编译期就失败，清单合并时报 minSdk 冲突
iOSiOS 13添加依赖时失败，Swift Package Manager 报平台不满足

不会出现「装上了但用不了」 —— 版本不兼容在你构建阶段就暴露出来，不会带到用户手上。

部分功能的门槛比这条线高，见下面对系统版本另有要求的功能。

Android 侧要核对什么 ​

构建环境 ​

你的工程 compileSdk 30 及以上就能接入。

下面这套是合从自己的构建环境，列出来供你对照，不是对你的要求：

项合从的构建环境
compileSdk35
Android Gradle Plugin8.x
Gradle8.x
Java 兼容性1.8，不需要开启 desugaring

你的工程不需要用 Kotlin，纯 Java 工程可以直接接入。

三方依赖 ​

SDK 只依赖两个库，写的都是最低能用的版本：

依赖最低版本
org.jetbrains.kotlin:kotlin-stdlib1.9.23
androidx.core:core1.6.0

没有任何非 AndroidX 的三方库 —— 不带网络库、JSON 库、图片库，这些都用系统自带的能力实现。

androidx 依赖以 implementation 方式引入，不会进入你的编译期类路径。合从不设版本上限，你的工程里有更高版本时按 Gradle 常规规则取高的那个，不用为合从降级。

包体积 ​

AAR 本身 230 KB 以内（不含依赖）。

不含任何原生库（没有 .so），所以不影响你的 ABI 分包策略，也不会因为架构而成倍增加体积。

混淆 ​

不用加任何混淆规则。 SDK 自带的规则会随依赖自动合并进你的工程，保护跨语言调用的方法名不被混淆。

权限 ​

SDK 自身不声明任何权限。 麦克风、相机这些由你按用到的功能在自己的 AndroidManifest.xml 里声明并运行时申请：

权限什么时候需要
RECORD_AUDIO + MODIFY_AUDIO_SETTINGS要让客户发语音消息，两条成对声明
CAMERA要让客户直接拍照或拍视频发给客服

只让客户打字和发相册照片的话，一条都不用声明。

语音那两条缺一不可：只声明 RECORD_AUDIO 时，客户点了 允许 仍会看到麦克风被占用的提示，重试和重启都没用。MODIFY_AUDIO_SETTINGS 是普通权限，装上就有，不弹窗。

SDK 会往你的清单里合并什么 ​

组件说明
HecongChatActivity客服页面容器，exported="false"，已配好软键盘模式
HecongChatSheetActivity弹层档的承载页，同样 exported="false"
FileProvider拍照时用来接收照片，authority 按你的应用 ID 派生（<你的applicationId>.hecong.capture），不会和你自己的 FileProvider 冲突

这些都不用你在自己的清单里声明。

设备需要启用系统 WebView ​

客服界面依赖 Android 的系统 WebView 组件（「Android System WebView」）。极少数设备允许用户在应用管理里停用它，停用后客服功能无法使用。

这种情况非常少见，多数用户不会去动这个组件。遇到这种设备时 SDK 会显示一张提示页引导用户去启用，并通过 onLoadFailed 回调通知你的 APP，你可以据此隐藏客服入口。

键盘适配的降级开关 ​

Android 11 及以上，客服页用系统的新式适配处理键盘和状态栏：键盘弹出时输入框逐帧跟随，页面铺到状态栏下面。这是默认行为，不用配。

个别定制系统上这套机制表现异常时，把 modernInsets 配成 false 退回传统的整页顶起方式：

kotlin
HecongChatConfig("你的渠道ID").apply { modernInsets = false }

Android 10 及以下本来就走传统方式，这个开关对它们没有影响；嵌进自己页面的那一档也不受影响，那时键盘由你的容器负责。

开了新式返回手势也不影响 ​

Android 13 起系统有一套新的返回回调机制，工程在清单里开了 enableOnBackInvokedCallback 之后，传统的 onBackPressed 不再被调用。客服页两套都接了，开不开都能正常返回，预测式返回动画也保留着。

自己摆容器的那一档要注意：你的返回按钮仍要先问一次 SDK，见把聊天嵌进自己的页面。

多进程 APP 要多做一步 ​

多进程架构不处理会直接崩溃

Android 不允许同一个 APP 的多个进程同时使用 WebView，触发时抛出：

Using WebView from more than one process at once with the same data directory is not supported

这是 Android 平台的限制。你的 APP 如果是多进程架构（电商、IM 类常见），要在任何 WebView 被创建之前——通常是 Application.onCreate 里——给非主进程设一个数据目录后缀：

kotlin
// Application.onCreate 中，按进程名判断
if (当前进程名 != 主进程名) {
    WebView.setDataDirectorySuffix(当前进程名)   // 需要 API 28 及以上
}

后缀取什么值由你的架构决定，合从不代做 —— SDK 替你定会和你自己的用法打架。

系统备份会把访客身份一起带走 ​

SDK 不声明 allowBackup，跟随你的 APP 设置。你的 APP 开着系统备份时，SDK 存在 SharedPreferences 里的访客标识会被备份并迁移到新设备，表现为用户换手机后聊天记录还在。

这通常是好事。不希望如此的话，在自己的备份规则里排除。

同一个 APP 接多个渠道 ​

技术上可以，同时打开两个不同渠道的客服页面也没问题。三件事要注意：

  • 访客身份默认共用。想让两个渠道各算各的客户，给它们配不同的 anonymousIdScope。
  • identify 和 resetUser 会作用于所有打开着的客服页面，不是只影响其中一个。
  • 未读跟踪只能跟一个渠道 —— 它按 configure 时登记的那份配置走。

构建配置 ​

开启 R8 全模式、资源压缩、App Bundle 分包都不需要额外处理：混淆规则随依赖自动生效，SDK 不带资源文件，也没有原生库参与分包。

访客标识在 Android 上卸载重装会丢失 ​

卸载 APP 会清掉应用数据，没登录过的客户重装后算新访客，看不到之前的对话。iOS 上标识存在钥匙串里，重装仍在。

已经调过 identify 绑定会员的客户不受影响，历史对话跟着会员 ID 走。

对系统版本另有要求的功能 ​

功能要求达不到时
语音消息（iOS）iOS 14.5 及以上录音入口不显示，其余功能正常
语音消息（Android）设备的 Android System WebView 版本较新录音入口不显示，其余功能正常

Android 的 System WebView 是可以独立更新的系统组件，和系统版本不是一回事。多数设备会自动更新它，长期不更新的低端机、没有应用商店的定制系统上可能偏旧。详见文件上传限制。

聊天本身不依赖新版内核。内核过旧的设备上，除语音之外的功能照常可用；如果客户反馈显示异常，引导他更新「Android System WebView」这个组件。

写应用市场文案时按功能分别限定

「支持 iOS 13 / Android 5.0」说的是聊天本身。语音消息的门槛更高，承诺时要单独写清楚，不要笼统写成整个客服功能的支持范围。

iOS 侧要核对什么 ​

通过 Swift Package Manager 引入，不引入任何三方库。Swift Package Manager 只在编译期工作，不会抬高你的 APP 的运行时最低版本要求。

需要 Xcode 13 及以上。你的工程不需要写 Swift，Objective-C 工程可以直接接入，写法见装进 iOS。

需要在 Info.plist 里补麦克风和相机的用途说明，见装进 iOS。

重复初始化不会有问题 ​

configure 可以重复调用，后一次覆盖前一次的配置。Application 被系统重建、或者你在多个入口各调了一次，都不会出问题。

升级 SDK 要做什么 ​

改依赖里的版本号，重新构建。接口有变动的版本会在版本说明里写明改什么，照着调整即可。

工作台里改配置不需要重新发版 —— 外观、欢迎语、自动回复、表单这些改完对新会话立即生效，客户也不用更新 APP。需要发版的只有一种情况：你要用 SDK 新增的接口。

新增的会话事件不需要升级 SDK 就能收到，前提是接了通用回调，见监听会话事件。

下一步 ​