SDK 接入文档

Appearance

常见问题 FAQ ​

通用问题 ​

Q1：服务端需要解密 data 字段吗？ ​

不需要。 业务服务端的职责是"拉取 → 缓存 → 转发"，全程不解密。解密只发生在 SDK 内部。对 data 字段做任何修改（包括解密再传）都会导致 SDK 初始化失败。

Q2：客户端需要解密 data 字段吗？ ​

不需要。 客户端从业务服务端获取密文后，直接原样传入 SDK 即可。SDK 内部持有解密密钥并完成解密。

Q3：配置接口拉取失败了怎么办？ ​

业务服务端应保留上次成功的缓存，不清空。客户端下次请求时仍能获取到（略旧的）配置，SDK 可正常工作。

只有在从未成功拉取过（无历史缓存）的情况下，才需要返回错误状态，由客户端决策降级处理。

Q4：建议多久拉取一次配置接口？ ​

建议每 10 分钟拉取一次。如需更高实时性可适当缩短，但过于频繁会给底层服务带来压力。

Q5：eventList 是什么？不在列表里的事件会怎样？ ​

eventList 是事件上报白名单，由底层配置服务下发。SDK 解密后会用此列表过滤事件：只有在 eventList 中的事件名才会被上报，不在列表中的事件会被 SDK 静默丢弃。

如果某个事件没有被上报，请先确认该事件名是否在 eventList 中。

Q6：domainList 是什么？ ​

domainList 是上报域名候选列表。SDK 初始化后会对列表中所有域名进行测速（并发 ping），选择响应最快的作为实际上报地址。业务方无需关心具体用哪个域名。

Q7：落地页SDK也需要走这套密文注入流程吗？ ​

不需要。 落地页SDK保持独立接入方案，通过 LandingSDK.init({ appId, domain, prod }) 或 tracker(payload) 直接上报，不需要从业务服务端获取密文。

服务端问题 ​

Q8：Redis 缓存的 TTL 应该设多少？ ​

建议设置为拉取间隔的 3 倍，即 30 分钟。这样即使定时任务连续失败几次，缓存也不会过期导致客户端拿不到配置。

Q9：服务端没有 Redis，可以用其他存储吗？ ​

可以。密文是普通字符串，可存储在：

  • 数据库（MySQL、PostgreSQL 等）：需要维护一张单行配置表
  • 应用内存：单节点简单场景可用，但重启后丢失，需要重新拉取
  • 文件系统：PHP 等场景可用文件缓存，见 PHP 示例

选择存储时，确保读写是线程安全的（多线程/多进程环境下注意并发写入）。

Q10：定时任务需要加重试逻辑吗？ ​

建议加，但不强制。如果拉取失败，有上次缓存兜底，下次定时任务（10 分钟后）还会重试。如果对实时性要求较高，可在拉取失败后等待 30 秒再重试 1 次。

客户端问题 ​

Q11：客户端要不要做本地密文缓存？ ​

Web 侧强烈建议做，将上次成功获取的密文存入 localStorage，在业务服务端暂时不可用时作为兜底。

Flutter SDK 则已经内置了域名列表和事件配置缓存。即使 encryptedConfig 未传入或解密失败，SDK 也会优先尝试加载本地缓存；若缓存不存在，则先缓存事件，等待后续 refreshDomainConfig()。

Q12：SDK 初始化失败了，业务逻辑要阻塞等待吗？ ​

不要阻塞。 建议将 SDK 初始化设计为异步、非阻塞的。初始化失败时，业务流程继续运行，只是本次不上报埋点数据。不要因为 SDK 初始化失败而影响用户体验。

Q13：encryptedConfig 传空字符串会发生什么？ ​

SDK 内部会尝试解密空字符串，失败后初始化不完成，事件不会上报，控制台会输出错误日志。不要传空字符串，无密文时应直接跳过初始化。

Q14：Web SDK 在初始化完成前调用 track()，事件会丢失吗？ ​

不会丢失。Web SDK 内部维护一个事件队列，初始化完成前的事件会暂存队列，初始化后统一处理。

更多帮助 ​