启动初始化流程

本页说明客户端在启动时如何决策 SDK 初始化，覆盖成功、失败和降级三种场景。

决策流程图

flowchart TD
    A([App 启动 / 页面加载]) --> B[调用业务服务端接口\n获取密文 data]
    B --> C{获取成功?}

    C -->|成功| D[将密文 data 原样传入 SDK]
    D --> E[SDK 内部解密\n获取 domainList / eventList]
    E --> F[SDK 初始化完成\n可正常上报事件]

    C -->|失败| G{是否有本地缓存?}
    G -->|有缓存| H[使用本地缓存的密文\n传入 SDK]
    H --> E
    G -->|无缓存| I[跳过 SDK 初始化\n或使用降级配置]
    I --> J[业务流程继续\n但本次不上报数据]

---

场景说明

场景一：正常获取密文

1. App 启动，调用业务服务端接口
2. 获取密文 data 成功
3. 将 data 原样传入 SDK
4. SDK 内部完成解密、域名测速、初始化
5. 业务正常运行，埋点事件正常上报

场景二：获取失败，有本地缓存

如果客户端实现了本地密文持久化（推荐）：

1. 调用业务服务端接口失败（网络异常、服务端无缓存等）
2. 读取本地存储的上次成功密文
3. 将本地缓存的密文传入 SDK
4. SDK 正常初始化（使用可能略旧的配置，通常可接受）

Flutter 示例（本地持久化）：

// 伪代码 —— 请替换为实际存储实现
String? encryptedData;

try {
  final response = await yourApi.getSdkConfig();
  encryptedData = response.data;
  // 成功时，更新本地缓存
  await localCache.save('sdk_config', encryptedData);
} catch (e) {
  // 失败时，尝试读取本地缓存
  encryptedData = await localCache.get('sdk_config');
}

if (encryptedData != null) {
  // 初始化 SDK（请替换为实际 API）
  SdkInitConfig.configure(encryptedConfig: encryptedData);
  await AnalyticsSdk.instance.init(appId: 'your_app_id');
} else {
  // 无任何可用配置，跳过初始化
  print('SDK 初始化跳过：无可用配置');
}

Web 示例（本地持久化）：

let encryptedData = null;

try {
  const response = await fetch('/your-api/sdk-config');
  const json = await response.json();
  if (json.code === 0 && json.data) {
    encryptedData = json.data;
    localStorage.setItem('sdk_encrypted_config', encryptedData);
  }
} catch (e) {
  encryptedData = localStorage.getItem('sdk_encrypted_config');
}

if (encryptedData) {
  WebSDK.init({
    appId: 'your_app_id',
    uid: '',
    channel: 'organic',
    encryptedConfig: encryptedData,
  });
} else {
  console.warn('SDK 初始化跳过：无可用配置');
}

场景三：获取失败，无本地缓存

这通常发生在：

• 用户首次安装 App，且业务服务端也尚无缓存
• 极端网络环境下首次启动

处理方式：

• 跳过 SDK 初始化：业务流程正常继续，本次不上报事件
• 不要阻塞主流程，不要让用户感知到异常
• 下次启动时重新尝试

---

最佳实践

建议实现客户端本地缓存

将上次成功的密文存入 SharedPreferences（Flutter）或 localStorage（Web），可显著提升网络不稳定时的初始化成功率。

不要用空字符串初始化 SDK

如果获取密文失败且无缓存，不要将空字符串或 null 传入 SDK。应直接跳过初始化，避免 SDK 抛出解密错误。

异步初始化，不阻塞主流程

建议将密文获取和 SDK 初始化设计为异步操作，不阻塞 UI 渲染或业务主流程。埋点丢失一次通常比影响用户体验代价小。