常见问题 FAQ

本文整理了接入过程中最常遇到的问题及解决方案。 若问题未在此列，可通过文末技术支持渠道联系我们。

SDK 初始化失败

现象：isInitialized 为 false，或控制台报 SDK_INIT_FAILED。

排查步骤：

1. 检查 App ID、AppKey 是否与控制台「凭证管理」中一致（注意沙箱/生产环境匹配）
2. 确认网络连接正常，SDK 初始化需访问 api.xiaobaotop.com
3. 检查 Manifest 中是否声明了 INTERNET 权限
4. 查看 Logcat 过滤 XiaobaoSDK 标签获取详细错误信息

签名错误 401

现象：S2S 接口返回 HTTP 401，提示签名校验失败。

排查步骤：

1. 确认签名算法：md5(app_key + timestamp + app_secret + request_body)，拼接顺序不可错
2. 检查 request_body：GET 请求传空字符串 ""，POST 传原始 JSON 字符串（保持与发送内容一致）
3. 检查时间戳：X-Timestamp 必须是 Unix 秒级整数，且服务器时钟与 NTP 同步偏差 < 5 分钟
4. 确认 AppKey / AppSecret 使用的是正确环境（沙箱 vs 生产）的凭证

位置权限被拒

现象：「附近健康站」功能无法使用，地图显示空白。

解决：

• 用户永久拒绝位置权限后，SDK 会引导跳转系统设置页手动开启
• 可在首次进入「附近健康站」页面前展示权限说明弹窗，提升授权率
• 若不需要精确位置，可在初始化时配置 locationAccuracy = COARSE 降级使用模糊位置

报告 AI 解读长时间 pending

现象：检测完成后，报告 ai_status 长时间停留在 pending 或 processing。

原因：

• AI 解读队列可能由于平台负载较高而排队
• 通常在 30 秒内完成；高峰期最长不超过 5 分钟

处理建议：前端展示「AI 解读中」加载动画，5 分钟后仍未完成可提示用户稍后查看，不阻断主流程。

主题配置未生效

现象：调用 setTheme() 后界面颜色未变化。

解决：

• 主题必须在 SDK 初始化完成后、打开任何 SDK UI 组件之前设置
• 云端配置的优先级低于代码设置，若云端配置了主题色，需先清除云端配置
• 颜色值格式必须为 6 位十六进制（如 #2DD4BF），不支持 rgb() 格式

Android 混淆配置

若启用了代码混淆（ProGuard / R8），在 proguard-rules.pro 中添加：

-keep class com.xiaobaotop.** { *; }
-keepclassmembers class com.xiaobaotop.** { *; }

技术支持

• 开发者论坛：community.xiaobaotop.com
• 提交工单：控制台右上角「帮助 → 提交工单」
• 紧急联系：企业认证用户可使用控制台专属在线客服

提交技术问题时，请提供：SDK 版本、平台（Android/iOS/uniapp）、 错误日志（logcat / Xcode console 输出）和可复现步骤，以便快速定位。