Appearance
接入问题排查
按现象找，每条给出成因和解决办法。
Gradle 报 Could not find com.aihecong:hecong-chat-sdk
这是什么：三种成因，看报错里 Searched in the following locations 列了哪些地址就能分辨。
| 列出的地址 | 成因 |
|---|---|
只有阿里云等国内镜像，没有 repo1.maven.org | 镜像还没同步到这个版本 |
| 只有公司内部的 Maven 代理 | 代理还没同步这个包 |
| 一个地址都没列，或没有任何 Maven 仓库 | 仓库列表里没有 mavenCentral() |
第一种最常见：国内工程多把镜像排在 mavenCentral() 前面，Gradle 命中镜像后就不再往后找，而镜像同步 Maven Central 有延迟，新版本发布后一段时间内镜像上还没有。
解决：
- 镜像延迟：等几十分钟后重新同步，或把
mavenCentral()临时排到镜像前面，也可以用--refresh-dependencies重新解析。 - 内部代理：让运维在代理上放行
com.aihecong这个 group。 - 仓库列表缺失：Android Gradle Plugin 7.0 及以上在
settings.gradle.kts的dependencyResolutionManagement里补mavenCentral()，更早的工程在根build.gradle的allprojects里。
想确认包本身发出来没有，直接拉这个地址，返回 200 就说明在：
https://repo1.maven.org/maven2/com/aihecong/hecong-chat-sdk/<版本号>/hecong-chat-sdk-<版本号>.pom不要用目录列表页判断 —— 那个页面本身也会缓存滞后，出现过文件已经能拉到、目录页却还没列出来的情况。
Xcode 添加 Package 一直停在 Resolving
这是什么：Swift Package Manager 从 GitHub 拉源码，受网络影响。
解决：等待，或换网络环境。已经失败的在 File > Packages > Reset Package Caches 后重试。
点开客服是一片空白
这是什么：多数是设备连不上合从的服务，或者 APP 里的网络拦截、代理组件挡住了 WebView 的请求。
解决：先确认设备网络正常。断网时 SDK 会显示一张带重试按钮的提示页，能看到那张页面说明 SDK 本身工作正常，问题在网络。检查 APP 里有没有对 WebView 请求做统一拦截。
如果看到的是下面这张「会话暂不可用」，说明渠道那一侧有问题 —— 去工作台确认渠道处于启用状态、没有被删除：
在浏览器里打开渠道地址，看到一张让我在 APP 内打开的提示页
这是什么：这是设计如此，不是故障。合从会确认会话是不是来自装了 SDK 的 APP，App 渠道在浏览器里打开会被拦下。
解决：把 APP 装到手机或模拟器上验证。App 渠道没有浏览器测试链接，原因见 APP 接入概述。
客户点发图片完全没反应
这是什么：把对话嵌进了自己的页面，但没有转发选择文件的结果回调。
解决：在宿主的 onActivityResult 里转发给 chatView，见把聊天嵌进自己的页面。用 SDK 提供的整页界面时不会遇到这个问题。
客户在权限弹窗上点了允许，录音还是用不了
这是什么：安卓上有两种可能。
一是清单里少声明了 MODIFY_AUDIO_SETTINGS。系统挑录音设备时会同时看它和 RECORD_AUDIO，少一条就当作没有可用的麦克风，界面提示麦克风被占用，重试、重启 APP 都没用——缺的是安装包里的声明，运行时补不回来。
二是自己嵌容器时没有转发权限申请结果。
解决：先照声明要用到的权限把语音那两条权限补齐，重新打包安装；自己嵌容器的还要转发 onRequestPermissionsResult，见把聊天嵌进自己的页面。
换个账号登录，客服对话里还是上一个人的记录
这是什么：退出登录时没有通知 SDK 解绑身份，SDK 仍认为坐在这台设备前的是上一位客户。
解决：在退出登录流程里调 resetUser()，见传客户资料与退出登录。
离线推送一条都收不到，工作台里客户一直显示在线
这是什么：合从判断客户已经离开，靠的是 APP 切到后台时主动断开连接。自己嵌容器又没有转发前后台事件的话，连接不会断，合从会一直认为客户在线，也就不会发出离线通知。
解决：转发宿主的 onStart 和 onStop，见前后台联动。注意要用 onStop 而不是 onPause。
配了离线消息通知地址，服务端一条请求都没收到
这是什么：三个条件缺一不可 —— 客户确实已离开、发消息的是人工客服、消息不是内部备注。机器人回复和自动回复不触发。
另一种可能是你的服务端连续失败了 5 次，这个渠道的通知进入了 5 分钟的暂停。
解决：按消息推送逐条对照触发条件。确认你的地址在公网可达、能在超时时间内返回，并且返回的不是 5xx。
未读数回调一直是 0
这是什么：未读跟踪有三个不活动的条件 —— 没调过 startUnreadTracking、这台设备从来没打开过客服、APP 不在前台。另外客服页面开着的时候轮询会暂停，那时未读数从实时连接来。
解决：确认调用了 startUnreadTracking，并且客户至少打开过一次客服。详见未读消息与红点。
断网时客户会看到什么
网络不可达时 SDK 会显示一张提示页并带重试按钮，同时通过 onLoadFailed 回调通知你的 APP，你可以据此隐藏客服入口或给出自己的提示：
个别客户反馈打不开客服，其他人都正常
这是什么：Android 上客服界面依赖系统的「Android System WebView」组件。极少数设备允许用户在应用管理里停用它，停用后客服功能无法使用。
解决：让客户在系统设置的应用列表里找到「Android System WebView」，确认它处于启用状态，并更新到较新版本。
很久以前的对话里，图片和视频打不开
这是什么：附件有保存期限，图片 365 天、语音 180 天、视频和文件 90 天，到期自动删除。文字消息一直保留，所以会出现文字在、附件打不开的情况。
解决：这不是故障，附件无法恢复。需要长期留存的资料，及时下载保存。
传了自定义字段，客服那边看不到
初始化时给 extraQuery 加一条 hcdebug=1 打开调试模式，面板会列出哪几个字段没被收下。
这是什么：字段名没有先在工作台里建好。没建过的字段名会被忽略。
解决：在工作台建好同名字段，见自定义字段。同时确认字段名不超过 64 个字符、值是字符串数字或布尔值，嵌套的对象和数组会被拒绝。
传了头像但不显示
这是什么：头像地址必须是 https:// 开头。http:// 的地址会被浏览器的混合内容策略拦掉。
解决：换成 https:// 的地址，长度控制在 500 字符以内。
客户正看着大图，点返回直接退出了整个客服页
这是什么：用了自己的返回按钮但没有先问 SDK 有没有可关闭的层。
解决：点击时先调 handleBackPressed()，返回 true 时不要再退出页面，见把聊天嵌进自己的页面。
分不清是集成问题还是渠道问题
这是什么：客服页面打不开、或者消息发不出去，但看不出是自己的集成写错了，还是渠道本身没配好。
解决：用示范 App 对照一次 —— 扫码装上，把同一个渠道 ID 填进去，在同一台设备上跑。
- 示范 App 正常、你的 APP 不正常 → 问题在你的工程配置，重点查依赖、清单合并、有没有网络拦截组件
- 两边都不正常 → 问题在渠道或账号那一侧，去工作台确认渠道处于启用状态、有客服在线
示范 App 底部 配置与诊断 里有一项 诊断信息，会显示当前连的是哪个渠道 ID 和访客标识。找人协助排查时，截这一页比口头描述有效。