完整接入流程

流程总览

flowchart TD
    A([底层配置服务\n/sdk/getAvailableDomainList])

    subgraph SERVER["业务服务端（后台定时任务）"]
        B[定时调用配置接口\n建议每 10 分钟一次]
        C{拉取成功?}
        D[更新缓存\n保存最新密文 data]
        E[使用上次缓存\n作为兜底]
        F[提供客户端接口\n返回密文 data]
    end

    subgraph CLIENT["客户端（App / Web 页面）"]
        G[App 启动 / 页面加载]
        H[调用业务服务端接口\n获取密文 data]
        I{获取成功?}
        J[将密文 data 原样传入 SDK]
        K[处理失败情况\n可跳过初始化或使用默认配置]
    end

    subgraph SDK["SDK 内部"]
        L[接收密文 data]
        M[AES-256-GCM 解密]
        N[使用 domainList\n测速选最优上报域名]
        O[使用 eventList\n过滤事件上报]
        P[批量上报事件]
    end

    A -->|定时拉取| B
    B --> C
    C -->|成功| D --> F
    C -->|失败| E --> F
    F -->|客户端请求| H
    G --> H
    H --> I
    I -->|成功| J --> L
    I -->|失败| K
    L --> M --> N & O --> P

分步说明

第一步：业务服务端定时拉取配置

业务服务端需要建立一个定时任务，定期调用底层配置接口：

# 正式环境
GET https://api.dc-server.cc/sdk/getAvailableDomainList

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

• 建议频率：每 10 分钟拉取一次
• 成功时：将返回的 data（密文字符串）保存到缓存（Redis / 数据库 / 内存均可）
• 失败时：保留上次成功的缓存数据，不清空

⚠️ 服务端不需要解密 data 字段。密文直接存储，原样返回给客户端即可。

接口响应格式：

{
  "code": 0,
  "msg": "success",
  "data": "<加密字符串>"
}

第二步：业务服务端提供客户端接口

业务服务端需要对外暴露一个自有接口，供客户端在启动时调用。该接口返回当前缓存的密文 data：

{
  "code": 0,
  "msg": "success",
  "data": "<密文字符串，与拉取时一致>"
}

接口设计建议：

• 直接返回缓存中的密文，不做额外处理
• 如无缓存数据，返回明确的错误状态，由客户端决策
• 建议记录缓存更新时间，方便排查问题

第三步：客户端启动时获取密文

在 App 启动或页面加载时，客户端调用业务服务端的接口，获取密文 data。

Flutter App：

// 伪代码 —— 请替换为实际 SDK API 和业务接口调用
final response = await yourApi.getSdkConfig();
final encryptedData = response.data; // 密文字符串

Web 页面：

// 伪代码 —— 请替换为实际业务接口调用
const response = await fetch('/your-api/sdk-config');
const { data: encryptedData } = await response.json();

第四步：将密文原样传入 SDK

客户端获取密文后，不做任何处理，直接传给 SDK。

Flutter SDK（占位示例，请确认实际 API）：

// 请替换为实际 Flutter SDK API
SdkInitConfig.configure(
  encryptedConfig: encryptedData,
);
await AnalyticsSdk.instance.init(
  appId: 'your_app_id',
  // ... 其他参数
);

Web SDK：

WebSDK.init({
  appId: 'your_app_id',
  uid: '',
  channel: 'organic',
  encryptedConfig: encryptedData, // 从业务服务端获取的密文
});

第五步：SDK 内部完成解密与初始化

SDK 接收到密文后，内部自行完成以下操作（业务方无需干预）：

1. AES-256-GCM 解密密文
2. 解析 domainList（上报域名列表）和 eventList（事件白名单）
3. 对域名列表进行测速，选择最优上报域名
4. 启动批量上报队列

缓存策略详解

场景	业务服务端行为	客户端感知
定时拉取成功	更新缓存为最新密文	下次启动获取最新配置
定时拉取失败，有历史缓存	继续使用上次缓存	获取到上次有效配置，SDK 正常工作
定时拉取失败，无历史缓存	返回错误或空	客户端需处理此情况（见启动初始化流程）

原则：优先使用最新成功数据；最新数据不可用时，使用上次缓存保障服务可用性；始终返回密文给客户端，解密始终由 SDK 内部完成。