收集 SDK 诊断信息

当客户反馈“登录失败”“消息一直发送中”或“列表不刷新”时，可以读取 SDK 诊断快照。这个操作不会联网，也不会改变登录状态，适合放在应用的“帮助与反馈”页面。

页面上应该显示什么

信息	用途
SDK 状态	判断尚未连接、已经就绪、需要重新登录或已经关闭
当前请求数	判断是否有大量请求长期没有结束
事件等待数	判断页面是否处理事件过慢
拒绝或丢弃计数	判断应用是否持续制造超过处理能力的请求
采集时间、SDK 版本、App 版本	对照问题发生时间与发布版本

这些数值是排障线索，不建议直接向普通用户展示内部名称。应用可以把它们转换为 “连接正常”“需要重新登录”“事件处理较慢”等易懂提示。

不要收集什么

诊断信息中不要加入：

Token、Cookie、签名、数据库密钥；
用户 ID、群 ID、会话 ID、消息 ID；
消息正文、业务通知正文、扩展字段；
请求地址、本地文件路径、数据库路径；
异常堆栈、完整请求或响应内容。

SDK 本身不会自动上传诊断信息。是否上传、上传到哪里以及保留多久，都由你的应用和隐私政策决定。

SDK 返回的诊断快照不包含账号、用户资料、会话内容或消息正文；应用也不应在整理支持包时自行补入这些信息。

生成支持包

仓库提供离线工具，将诊断快照、稳定错误码日志和非敏感版本信息打成 ZIP。工具不会读取应用数据库或系统日志，也不会联网。

bash

python3 scripts/support/collect_support_bundle.py \
  --diagnostics /absolute/path/diagnostics.json \
  --logs /absolute/path/xhim-stable-code.jsonl \
  --metadata /absolute/path/metadata.json \
  --sdk-source-commit 0123456789abcdef0123456789abcdef01234567 \
  --output /absolute/path/xhim-support.zip

python3 scripts/support/verify_support_bundle.py \
  /absolute/path/xhim-support.zip \
  --expected-sdk-source-commit \
  0123456789abcdef0123456789abcdef01234567

sdk-source-commit 应从 SDK 交付包的清单中复制，不要填写 App 仓库的 Commit。如果工具发现敏感字段、未知字段、重复 JSON Key、非法 UTF-8 或超限文件，会直接拒绝生成，而不是把不确定的数据打进支持包。

C/C++ 适配层

只有自行维护 C/C++ 适配层时，才需要调用原生入口 xhim_v1_client_get_diagnostics。普通 App 请继续使用上方各平台的 diagnostics 方法；平台 SDK 已负责结构版本检查和数据复制，不需要业务代码直接处理 C 结构体。

常见问题处理

现象	建议
状态显示需要凭据	清除过期自动登录信息，让用户重新登录
请求数一直增长	检查网络、超时设置和页面退出时是否取消请求
事件持续积压	事件回调只做数据复制，把页面计算放到业务线程
SDK 已关闭	创建新的账号会话，不要继续复用旧 Client
支持包校验失败	按工具提示删除不允许的字段后重新生成

收集 SDK 诊断信息 ​

推荐接入流程 ​

页面上应该显示什么 ​

不要收集什么 ​

生成支持包 ​

C/C++ 适配层 ​