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