版本识别

Bugly 对于灰度版和正式版的识别有两种方式：

1. 根据 DAU 阈值推测：平台根据 DAU 数据自动推测版本类型，业务可自定义阈值。
2. 通过 OpenAPI 主动标识：调用 Bugly 提供的 OpenAPI 接口，主动设置版本类型，这种方式最为高效和准确。

---

一、基于 DAU 阈值的自动识别

1. 背景

原判定逻辑使用固定常量（灰度 5000 / 正式 10000），其根本问题在于固定值不随 App 体量变化：小 App 永远够不到，大 App 太容易升上去。当前方案将两个常量替换为一条公式，对任意规模的 App 统一适用。

2. 阈值计算公式

灰度阈值 = max(50,  min(0.5% × baseDAU, 500,000))
正式阈值 = max(200, min(5%  × baseDAU, 2,000,000))

其中：

• baseDAU：该 App 过去 24h 全量联网设备数，每次 4h 巡检顺带取出。
• 判定逻辑：版本 24h 联网设备数 ≥ 阈值 → 升级为对应版本类型。

一句话表述

灰度 = App 总 DAU 的 0.5%，正式 = 5%，并限制在 50 – 50 万 / 200 – 200 万 之间。

3. 设计思路

• 为什么用百分比替代固定常量 —— 阈值随 App 体量自然缩放，是解决"一套数字包打天下"根因的唯一办法。
• 为什么灰度 0.5%、正式 5% —— 对齐 Google Play 分阶段发布 day-1 实际覆盖量，以及业界"覆盖 5% 即主力版本"的惯例。1:10 的比例关系让灰度扮演"早期信号"、正式扮演"大规模铺开"的角色。
• 为什么还要上下限 —— 纯百分比在两端会失真：小 App 的 0.5% 可能只有几台设备，容易被测试机或内部推送误触发；大 App 的 5% 可能几百万台，永远升不上去。下限 50 / 200 给小 App 兜底，上限 50 万 / 200 万给大 App 封顶。
• 为什么不分档 —— 分档必然在档位边界产生 2–5x 的阈值突变（App DAU 涨一点点，阈值突然跳变，反直觉也难解释）。单一公式全程平滑，一句话能讲清。

4. 关键效果

App 规模	DAU 范围	灰度阈值	正式阈值
小 App	< 1 万 DAU	走下限 50	走下限 200
主流 App	10 万 – 1000 万 DAU	按 0.5% / 5% 动态缩放	按 0.5% / 5% 动态缩放
超大 App	≥ 1 亿 DAU	封顶 50 万	封顶 200 万

5. 自定义阈值

业务可以根据自身产品特点自定义灰度和正式版的 DAU 阈值比例，不必使用平台默认值。如有需要，请联系 Bugly 运营同学进行配置。

---

二、通过 OpenAPI 主动标识版本类型

通过 OpenAPI 主动标识版本类型是最高效、最准确的方式。业务可以在发布流程中集成该接口，自动为每个版本设置对应的版本类型（开发版/灰度版/发布版）。

1. 接口信息

项目	说明
接口地址	POST https://api.bugly.tds.qq.com/v1/version/set_versions_release
鉴权方式	请求头携带 X-Token，通过 Bugly 平台获取

2. 请求参数

参数名	类型	必填	说明
appId	string	是	应用 ID
platformId	int	是	平台 ID（1: Android, 2: iOS）
version	string	是	应用版本号
versionType	int	是	版本类型：1-开发版，2-灰度版，3-发布版

3. 响应参数

参数名	类型	说明
code	int	返回码，0 表示成功
message	string	返回信息

4. 调用示例（curl）

curl -X POST 'https://api.bugly.tds.qq.com/v1/version/set_versions_release' \
  -H 'Content-Type: application/json' \
  -H 'X-Token: your_token_here' \
  -d '{
    "appId": "your_app_id",
    "platformId": 1,
    "version": "1.2.0",
    "versionType": 2
  }'

5. 版本类型的作用

自动识别或通过 OpenAPI 设置的版本类型信息，可以在「设置 / 产品配置 / 应用版本」中查看。这些版本信息是告警和版本指标的数据来源，帮助业务：

1. 精准告警：根据版本类型区分告警策略，灰度版可设置更敏感的告警阈值，正式版关注大规模影响。
2. 版本指标分析：按版本类型筛选数据，方便区分灰度阶段和正式上线阶段的质量表现。

---

三、版本类型与构建类型的区别

重要概念区分

版本类型和 SDK 中的构建类型是两个不同的概念，请勿混淆。

1. 构建类型（Build Type）

构建类型是通过 SDK 接口在应用初始化时设置的，描述的是该次构建的用途，例如：

• Release：正式发布构建
• Debug：调试构建
• Gray：灰度构建

构建类型是静态的，在构建时就已经确定，无法在运行时修改。修改构建类型意味着产生一个新的构建包。

关于接口命名

由于历史命名原因，各平台 SDK 中设置构建类型的接口名称可能包含 "version_type" 或 "versionMode" 等字样，容易与本文描述的"版本类型"概念混淆。但为了历史兼容，接口未做修改。请注意：SDK 接口中设置的实际上是构建类型，而非平台侧的版本类型。

各平台 SDK 设置构建类型的接口

Android SDK

通过 BuglyBuilder 在初始化时设置：

// 推荐，在初始化时设置构建类型
builder.appVersionType = BuglyAppVersionMode.DEBUG;    // 开发版本
builder.appVersionType = BuglyAppVersionMode.GRAY;     // 灰度版本
builder.appVersionType = BuglyAppVersionMode.RELEASE;  // 发布版本

iOS SDK

通过 BuglyConfig 的 buildConfig 属性设置：

BuglyConfig *config = [[BuglyConfig alloc] initWithAppId:APP_ID appKey:APP_KEY];
// 设置构建类型
config.buildConfig = BuglyBuildConfigDebug;   // 开发版本
config.buildConfig = BuglyBuildConfigGray;    // 灰度版本
config.buildConfig = BuglyBuildConfigRelease; // 发布版本

[Bugly start:modules config:config completeHandler:^{
    // 初始化完成回调
}];

对应 API 声明：@property (nonatomic, assign) BuglyBuildConfig buildConfig;

Harmony SDK

通过 BuglyBuilder 的 appVersionMode 属性设置：

import { Bugly, BuglyBuilder, AppVersionMode } from "bugly";

let builder = new BuglyBuilder();
builder.appVersionMode = AppVersionMode.DEBUG;    // 开发版本
// 或 AppVersionMode.GRAY / AppVersionMode.RELEASE

Bugly.init(context, builder);

tip

默认值均为未知类型（Unknown），建议在初始化时主动设置构建类型。

2. 版本类型（Version Type）

版本类型是在构建完成后，根据实际数据（DAU 阈值推测）或实际用途（OpenAPI 主动标识）来动态决定的，例如：

• 开发版：用于内部测试
• 灰度版：小范围发布验证
• 发布版：正式全量上线

版本类型是动态的，可以随时通过 OpenAPI 修改，也会被平台根据 DAU 数据自动调整。

3. 为什么需要区分

举个实际场景：业务构建了一个 Release 包，本意是用于灰度发布，但上线前测试发现了 Bug，最终取消了灰度计划。此时：

• 构建类型仍然是 Release（已固定，无法修改，修改就是新构建）
• 版本类型可以不标记为灰度版（因为实际并未灰度发布）

这就是为什么两者必须是独立的概念：构建类型反映的是"构建意图"，版本类型反映的是"实际发布状态"。

4. 当前机制说明

当前状态

目前 SDK 配置中的构建类型过滤条件，取的是业务通过 SDK 接口设置的构建类型，尚未对接本文描述的自动识别版本类型。也就是说：

• 「设置 / 产品配置 / 应用版本」中展示的版本类型 → 来自 DAU 自动识别或 OpenAPI 主动标识
• 「SDK 配置」中的构建类型过滤条件 → 来自 SDK 初始化时业务设置的构建类型

---

四、两种识别方式对比

对比项	DAU 阈值推测	OpenAPI 主动标识
准确性	基于统计推测，存在误判可能	精确标识，无误判
时效性	需等待 DAU 数据积累（至少 24h）	实时生效
接入成本	无需开发，平台自动判定	需在发布流程中集成 API 调用
适用场景	无发布系统或未集成 CI/CD 的团队	有完善发布流程的团队

推荐

建议有条件的团队优先使用 OpenAPI 主动标识 方式，可以在版本发布后第一时间准确标识版本类型，避免等待 DAU 数据积累期间的误判。