目录— 个文件
⌕
目录加载中…
…/module/ab/ABManager.ts
1import { IFrameworkManager } from "../../core/base/IFrameworkManager";
2import { Singleton } from "../../core/base/Singleton";
3import { DataFrameKey } from "../../core/data/DataFrameKey";
4import { EventFrameCode } from "../../core/event/EventFrameCode";
5import { Framework } from "../../Framework";
6import { SdkConfig } from "../sdk/SdkConfig";
7import {
8 ABExperimentDef,
9 ABFlowDecision,
10 ABTestId,
11} from "./ABFrameDefine";
12import { ABModel } from "./ABModel";
13
14/**
15 * AB 测试管理器;项目在启动时提供本次参与的实验。
16 * - 在注入清单内:按 openRatio 分 open/close 并本地固化
17 * - 不在清单内:不测,功能对全员开放
18 * - 已落盘的分流下次进入直接复用,不再重新随机
19 */
20export class ABManager extends Singleton<ABManager> implements IFrameworkManager {
21 public Name: string = "ABManager";
22 public Model: ABModel = new ABModel();
23 /** 通过事件拿到的玩家 ID(优先用于分流)。 */
24 private eventPlayerId: string = "";
25 private experiments: readonly ABExperimentDef[] | null = null;
26
27 /** 只装配清单原引用,不读取存档或分桶;无实验的项目应显式传入空清单。 */
28 public SetExperiments(experiments: readonly ABExperimentDef[]): void {
29 this.experiments = experiments;
30 }
31
32 /** 初始化运行模型并监听最终玩家存档就绪事件。 */
33 public async Init(): Promise<void> {
34 if (this.experiments === null) {
35 throw new Error("[ABManager] 尚未装配项目实验清单");
36 }
37 if (this.Model.IsReady) {
38 return;
39 }
40 this.Model.Init();
41 this.Model.IsReady = true;
42 Framework.Event.RegisterEvent(EventFrameCode.PLAYER_DATA_READY, this.EnsureDecisions, this);
43 }
44
45
46
47 /** 销毁:清空运行态。 */
48 public DeInit(): void {
49 Framework.Event.UnRegisterEvent(EventFrameCode.PLAYER_DATA_READY, this.EnsureDecisions, this);
50 this.Model.DeInit();
51 this.eventPlayerId = "";
52 }
53
54 /** 每帧更新(AB 无帧逻辑)。 */
55 public Update(_deltaTime: number): void {
56 }
57
58 /**
59 * 为本版清单中尚未缓存的实验补齐分流并落盘。
60 * 最终玩家存档确认后,加载已有分流并补齐尚未缓存的实验。
61 */
62 public EnsureDecisions(): void {
63 if (!this.Model.IsReady) {
64 Framework.Log.Log("ABManager", "EnsureDecisions", "ABManager.Init 未完成,跳过补桶");
65 return;
66 }
67 this.LoadLocalCache();
68 const now: number = Date.now();
69 let assignedAny: boolean = false;
70 for (const def of this.experiments!) {
71 if (this.Model.DecisionMap.has(def.key)) {
72 continue;
73 }
74 this.AssignDecision(def, now);
75 assignedAny = true;
76 }
77 if (assignedAny) {
78 this.PersistLocalCache();
79 }
80 }
81
82 /**
83 * 功能是否对当前玩家开放。
84 * - 不在本版清单:恒为 true
85 * - 在清单:看固化方案是否为 open
86 */
87 public IsOpen(expKey: string): boolean {
88 return this.GetCurrentTestId(expKey) === ABTestId.Open;
89 }
90
91 /**
92 * 获取当前命中的方案编号(open / close)。
93 * 不在本版清单时视为 open。
94 */
95 public GetCurrentTestId(expKey: string): string {
96 const manualTestId = this.GetManualOverride(expKey);
97 if (manualTestId) {
98 return manualTestId;
99 }
100 if (!this.FindActiveDef(expKey)) {
101 return ABTestId.Open;
102 }
103 return this.GetOrAssignDecision(expKey).testId;
104 }
105
106 /**
107 * 获取分流结果(testId / bucket / assignedAt)。
108 * 不在本版清单时返回占位 open,不落盘。
109 */
110 public GetDecision(expKey: string): ABFlowDecision {
111 if (!this.FindActiveDef(expKey)) {
112 return {
113 testId: ABTestId.Open,
114 bucket: 0,
115 assignedAt: 0,
116 };
117 }
118 return this.GetOrAssignDecision(expKey);
119 }
120
121 /** 只有确认入组才返回上报组别,玩法兜底 A 不算对照组。 */
122 public GetReportGroup(expKey: string): "A" | "B" | "" {
123 if (!this.FindActiveDef(expKey)) return "";
124 const decision = this.GetOrAssignDecision(expKey);
125 if (decision.enrolled !== true) return "";
126 return this.GetCurrentTestId(expKey) === ABTestId.Open ? "B" : "A";
127 }
128
129 /** 在本版清单中查找实验定义;未在测返回 null。 */
130 private FindActiveDef(expKey: string): ABExperimentDef | null {
131 if (this.experiments === null) {
132 throw new Error("[ABManager] 尚未装配项目实验清单");
133 }
134 for (const def of this.experiments) {
135 if (def.key === expKey) {
136 return def;
137 }
138 }
139 return null;
140 }
141
142 /**
143 * 读取已有分流;没有则从存档再灌一次,仍没有则首次分桶并落盘。
144 * 保证同玩家同实验结果粘性。
145 */
146 private GetOrAssignDecision(expKey: string): ABFlowDecision {
147 let existed: ABFlowDecision | undefined = this.Model.DecisionMap.get(expKey);
148 if (existed) {
149 return existed;
150 }
151 this.LoadLocalCache();
152 existed = this.Model.DecisionMap.get(expKey);
153 if (existed) {
154 return existed;
155 }
156 const def: ABExperimentDef = this.FindActiveDef(expKey)!;
157 const assigned: ABFlowDecision = this.AssignDecision(def, Date.now());
158 this.PersistLocalCache();
159 return assigned;
160 }
161
162 /**
163 * 按稳定种子 + expKey 哈希到 [0,99],再按 openRatio 命中 open/close,写入内存。
164 */
165 private AssignDecision(def: ABExperimentDef, assignedAt: number): ABFlowDecision {
166 const seed: string = this.GetStableSeed();
167 const bucket: number = this.StableHashPercent(seed + ":" + def.key);
168 const openRatio: number = Math.max(0, Math.min(100, Math.floor(def.openRatio)));
169 // 资格来自最终原始存档;老玩家不参加新实验。
170 const isNewer = Framework.Data.IsNewPlayerForAB;
171 let testId: string = ABTestId.Close;
172 if (isNewer && bucket < openRatio) testId = ABTestId.Open;
173 const decision: ABFlowDecision = {
174 enrolled: isNewer,
175 testId,
176 bucket,
177 assignedAt,
178 };
179 this.Model.DecisionMap.set(def.key, decision);
180 Framework.Log.Log("ABManager", "AssignDecision", `expKey=${def.key}, testId=${testId}, bucket=${bucket}, openRatio=${openRatio}`);
181 return decision;
182 }
183
184 /** 从本地存档灌入 anonId 与已固化分流(只接受 open/close)。 */
185 private LoadLocalCache(): void {
186 const anonId: string = Framework.Data.GetData<string>(DataFrameKey.AB_ANON_ID, "");
187 if (anonId) {
188 this.Model.AnonId = anonId;
189 }
190
191 const localCache: Record<string, ABFlowDecision> =
192 Framework.Data.GetData<Record<string, ABFlowDecision>>(DataFrameKey.AB_EXPERIMENT_DECISIONS, {});
193 for (const expKey of Object.keys(localCache)) {
194 const item: ABFlowDecision = localCache[expKey];
195 if (!item || !this.IsValidTestId(item.testId)) {
196 continue;
197 }
198 this.Model.DecisionMap.set(expKey, {
199 enrolled: item.enrolled === true,
200 testId: item.testId,
201 bucket: Math.max(0, Math.min(99, Number(item.bucket ?? 0))),
202 assignedAt: item.assignedAt ?? Date.now(),
203 });
204 }
205 }
206
207 /** 将 anonId 与 DecisionMap 写回本地存档。 */
208 private PersistLocalCache(): void {
209 if (!this.Model.AnonId) {
210 this.Model.AnonId = this.GenerateAnonId();
211 }
212 Framework.Data.SaveData(DataFrameKey.AB_ANON_ID, this.Model.AnonId);
213
214 const data: Record<string, ABFlowDecision> = {};
215 this.Model.DecisionMap.forEach((value: ABFlowDecision, key: string) => {
216 data[key] = value;
217 });
218 Framework.Data.SaveData(DataFrameKey.AB_EXPERIMENT_DECISIONS, data);
219 }
220
221 /** 校验缓存 testId 是否为合法方案编号。 */
222 private IsValidTestId(testId: string): boolean {
223 return testId === ABTestId.Open || testId === ABTestId.Close;
224 }
225
226 /** 稳定分桶种子:openId 优先,anonId 次之。 */
227 private GetStableSeed(): string {
228 const openId: string = this.GetUserOpenId();
229 if (openId) {
230 return `openId:${openId}`;
231 }
232 if (!this.Model.AnonId) {
233 this.Model.AnonId = this.GenerateAnonId();
234 }
235 return `anonId:${this.Model.AnonId}`;
236 }
237
238 /** 读取用户 openId(事件注入优先,否则当前渠道 OpenId)。 */
239 private GetUserOpenId(): string {
240 return (this.eventPlayerId || SdkConfig.GetCurrentOpenId()).trim();
241 }
242
243 /** 生成本地匿名 ID(无账号态时用于稳定分桶)。 */
244 private GenerateAnonId(): string {
245 return `anon_${Date.now()}_${Math.floor(Math.random() * 1000000)}`;
246 }
247
248 /** 稳定 hash:字符串 -> [0,99]。 */
249 private StableHashPercent(text: string): number {
250 let hash: number = 2166136261;
251 for (let i: number = 0; i < text.length; i++) {
252 hash ^= text.charCodeAt(i);
253 hash = Math.imul(hash, 16777619);
254 }
255 return (hash >>> 0) % 100;
256 }
257
258 /** 测试面板手动指定实验分组;结果持久化,下一次启动读取配置时生效。 */
259 public SetManualOverride(expKey: string, testId: ABTestId): boolean {
260 if (!this.FindActiveDef(expKey) || !this.IsValidTestId(testId)) {
261 return false;
262 }
263 const overrideMap = this.LoadManualOverrideMap();
264 overrideMap[expKey] = testId;
265 Framework.Data.SaveData(DataFrameKey.AB_MANUAL_OVERRIDE, overrideMap);
266 return true;
267 }
268
269 /** 清除手动分组后恢复已固化的自动分桶结果。 */
270 public ClearManualOverride(expKey: string): void {
271 const overrideMap = this.LoadManualOverrideMap();
272 if (!(expKey in overrideMap)) {
273 return;
274 }
275 delete overrideMap[expKey];
276 Framework.Data.SaveData(DataFrameKey.AB_MANUAL_OVERRIDE, overrideMap);
277 }
278
279 /** 返回有效的手动分组;未设置时返回空字符串。 */
280 public GetManualOverride(expKey: string): ABTestId | "" {
281 const testId = this.LoadManualOverrideMap()[expKey];
282 return this.IsValidTestId(testId) ? testId as ABTestId : "";
283 }
284
285 private LoadManualOverrideMap(): Record<string, string> {
286 return Framework.Data.GetData<Record<string, string>>(DataFrameKey.AB_MANUAL_OVERRIDE, {});
287 }
288}
讲解289 行
实验分流人工通读
ABManager.ts
项目先注入实验清单,管理器基础初始化后监听玩家数据就绪,届时从存档恢复并补齐分桶,结果保存在 ABModel。查询不在清单中的功能默认开放;老玩家虽固化为 close,却不入组上报,手动覆盖只改变当前组别判断。
先看 SetExperiments、Init、EnsureDecisions,再看 GetCurrentTestId、GetReportGroup 与 AssignDecision。
特殊处理与易错点
- 易错点Init 的 IsReady 只表示注册完成,提前查询仍可能在最终玩家数据就绪前触发分桶。L33
- 易错点手动覆盖优先于当前清单检查,已退出清单的实验如果残留覆盖仍可被 GetCurrentTestId 读到。L95
- 易错点GetDecision 返回自动分桶结果,不反映手动覆盖;GetReportGroup 只对 enrolled 为 true 者上报。L110
- 易错点eventPlayerId 在此文件没有赋值入口,实际种子通常来自 SdkConfig 的当前 OpenId。
20注释ABManager:AB 测试:按 openId/anonId 稳定分桶并固化,支持 IsOpen/GetCur
21属性名称(string):模块/组件名称,用于日志、缓存 Key 或资源查找。
22属性匿名标识、就绪标志和实验结果 Map 的所属模型。
24属性代码预留的优先身份字段,本文件仅清空没有写入。
25属性项目注入的只读清单引用,null 表示尚未装配。
28方法保存项目传入的实验清单原引用,供后续查询与补桶使用。
33方法校验实验清单并重置模型,注册最终玩家数据就绪后的补桶回调。
48方法注销玩家数据就绪监听并清空实验运行态与事件身份字段。
55方法保留框架逐帧接口,实验分流不在此处推进任何状态。
62方法加载本地分组并为当前清单缺失实验分桶,有新增时保存存档。
87方法按当前分组判断指定实验功能是否应该向玩家开放。
95方法优先读取手动覆盖,清单外默认开放,清单内读取或创建固化分组。
110方法取得自动固化的分桶详情,清单外返回不写存档的开放占位。
122方法仅对清单内且确认入组的玩家返回按当前分组确定的上报组别。
130方法顺序查找当前实验清单中的定义,缺少清单配置时明确抛错。
146方法依次检查内存和存档,仍缺失时首次分桶并将结果持久化。
165方法用稳定身份和实验键哈希分桶,结合新用户资格生成并缓存分组。
170注释资格来自最终原始存档;老玩家不参加新实验。
185方法恢复匿名种子与合法分组记录,将缺少资格标记的历史记录视为未入组。
208方法保证匿名种子存在,将匿名标识和当前所有实验结果分别保存到存档。
222方法检查传入方案是否恰好为系统允许的开放或关闭字符串。
227方法优先用当前账号标识构造种子,无账号时建立并复用匿名种子。
239方法读取事件身份或渠道当前身份并去除首尾空白,供稳定分桶使用。
244方法组合当前毫秒时间与随机整数,生成无账号时的本地分桶标识。
249方法逐字符异或并乘哈希常数,将种子稳定映射到一百个分桶。
259方法校验实验与方案后把手动分组写入存档,不修改自动分桶结果。
270方法删除存档中指定实验的手动分组,让后续查询恢复自动结果。
280方法读取指定实验的手动覆盖并过滤不合法的分组字符串。
285方法从存档读取全部手动覆盖映射,未存储时取得空映射。