合从文档中心

Appearance

兼容性核对 ​

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

最低系统版本 ​

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

系统版本不满足会在构建阶段就报出来。语音消息的门槛比这条线高，见下面对系统版本另有要求的功能。

Android 侧要核对什么 ​

构建环境 ​

工程 compileSdk 30 及以上就能接入，不需要开启 desugaring。纯 Java 工程也可以直接接入，不需要用 Kotlin。

三方依赖 ​

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

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

不带网络库、JSON 库、图片库这类三方库。androidx 依赖以 implementation 方式引入，不设版本上限，你的工程里有更高版本时按 Gradle 常规规则取高的那个，不用降级。

包体积 ​

AAR 本身 230 KB 以内（不含依赖），不含原生库（没有 .so），不影响 ABI 分包。

混淆 ​

不用加混淆规则，SDK 自带的规则会随依赖自动合并进你的工程。开启 R8 全模式、资源压缩、App Bundle 分包也都不需要额外处理。

权限 ​

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 System WebView」组件。少数设备允许用户在应用管理里停用它，停用后客服功能无法使用：SDK 会显示一张提示页引导用户去启用，并通过 onLoadFailed 回调通知你的 APP，你可以据此隐藏客服入口。

键盘适配的降级开关 ​

Android 11 及以上，客服页默认用系统的新式方式处理键盘和状态栏，不用配。

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

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

这个开关对 Android 10 及以下没有影响。

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

工程在清单里开了 enableOnBackInvokedCallback（Android 13 起的新返回机制），客服页照常能返回，预测式返回动画也保留。

直接使用 HecongChatView 时，你的返回按钮仍要先问一次 SDK，见把聊天嵌进自己的页面。

多进程 APP 要多做一步 ​

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

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

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

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

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

后缀取什么值由你的架构决定。

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

SDK 跟随你的 APP 的 allowBackup 设置。开着系统备份时，SDK 存在 SharedPreferences 里的访客标识会随备份迁移到新设备，用户换手机后聊天记录还在。不希望如此的话，在自己的备份规则里排除。

同一个 APP 接多个渠道 ​

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

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

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

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

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

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

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

System WebView 可以独立于系统更新，长期不更新的低端机、没有应用商店的定制系统上可能偏旧。写应用市场文案时的注意事项见文件上传限制。

客户反馈显示异常时，引导他更新「Android System WebView」这个组件。

iOS 侧要核对什么 ​

通过 Swift Package Manager 引入，不带任何三方库。

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

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

重复初始化不会有问题 ​

configure 可以重复调用，后一次覆盖前一次的配置。

升级 SDK 要做什么 ​

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

工作台里改外观、欢迎语、自动回复、表单这些配置，对新会话立即生效，你的 APP 不用重新发版。要用 SDK 新增的接口时才需要升级发版。

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

下一步 ​