SDK 接入文档

Appearance

排查 & 检查清单 ​

接入检查清单 ​

在排查问题前，先逐项确认以下清单：

服务端 ​

  • [ ] 定时任务已启动，每 10 分钟调用一次 GET https://api.dc-server.cc/sdk/getAvailableDomainList（测试环境替换为 https://dcapi.dc-dev.cc）
  • [ ] 拉取成功时，将 data 字段（密文字符串）存入缓存
  • [ ] 拉取失败时，保留上次缓存，不清空
  • [ ] 对外接口返回的是缓存中的密文字符串，未做任何解密或修改
  • [ ] 无缓存时，接口返回明确的错误状态（如 code: -1），而不是空字符串

客户端（Flutter / Web） ​

  • [ ] App 启动 / 页面加载时调用了业务服务端接口
  • [ ] 将返回的 data 字段原样传入 SDK，未做任何处理
  • [ ] 获取失败时，有本地缓存兜底逻辑
  • [ ] 无任何配置时，跳过 SDK 初始化，而不是传入空字符串

SDK 初始化 ​

  • [ ] encryptedConfig 参数传入的是完整密文字符串（未截断）
  • [ ] appId 参数已正确填写
  • [ ] 初始化为异步调用，未阻塞主线程

常见问题排查 ​

问题：SDK 初始化失败 / 解密错误 ​

可能原因：

  1. 密文在传输过程中被修改（服务端解密后重新传，或客户端做了字符串处理）
  2. 密文被截断（接口响应体过大，被中间件截断）
  3. encryptedConfig 传入了空字符串或 null

排查步骤：

  1. 在业务服务端日志中查看缓存的密文字符串，记录其长度
  2. 在客户端打印收到的 data 字段，比对长度是否一致
  3. 确认传入 SDK 的字符串与收到的字符串完全一致（可打印前 20 个字符比对）
javascript
// Web 排查示例
console.log('[Debug] encryptedData length:', encryptedData.length);
console.log('[Debug] encryptedData prefix:', encryptedData.substring(0, 20));

问题：事件没有被上报 ​

可能原因：

  1. SDK 初始化未完成（密文获取失败，初始化被跳过）
  2. 事件名不在 eventList 白名单中
  3. 上报域名全部不可达（测速失败）

排查步骤：

  1. 确认 SDK 初始化是否成功（查看初始化日志）
  2. 确认事件名拼写是否正确，是否在白名单中（联系配置管理员确认）
  3. 检查网络环境，确认上报域名是否可访问

问题：业务服务端接口返回 config not available ​

可能原因：

  1. 定时任务从未成功执行过（如任务未启动、首次拉取失败）
  2. Redis 缓存过期（TTL 设置过短）
  3. 定时任务执行失败但无报警，导致缓存一直未更新

排查步骤：

  1. 检查定时任务日志，确认是否成功执行
  2. 手动执行一次拉取脚本，确认接口可访问
  3. 检查 Redis 中是否存在 sdk:encrypted_config 键：
bash
redis-cli get sdk:encrypted_config
  1. 手动调用底层配置接口，确认响应正常：
bash
# 正式环境
curl https://api.dc-server.cc/sdk/getAvailableDomainList

# 测试环境
curl https://dcapi.dc-dev.cc/sdk/getAvailableDomainList

问题：Flutter SDK 初始化 API 不确定 ​

当前 Flutter SDK 已切换为 encryptedConfig 方案，请确认使用的是以下真实接口：

dart
await AnalyticsSdk.instance.init(
  appId: 'your_app_id',
  encryptedConfig: encryptedConfig,
  device: DeviceEnum.Android,
  deviceId: 'device_123',
  deviceBrand: 'Xiaomi',
  deviceModel: 'Mi 10',
  systemName: 'Android',
  systemVersion: '14',
);

如启动时拿不到配置，可先传 null，稍后调用：

dart
await AnalyticsSdk.instance.refreshDomainConfig(
  encryptedConfig: encryptedConfig,
);

不要再使用旧的 SdkInitConfig.configure(baseDomain: ...) 写法。

问题：Web 页面本地存储读不到缓存 ​

排查步骤：

  1. 确认写入时使用的 key 与读取时一致（如 sdk_encrypted_config）
  2. 确认页面运行在同一个域名下（localStorage 受同源策略限制）
  3. 检查浏览器是否开启了隐私模式（无痕模式下 localStorage 可能受限）

获取更多帮助 ​