Thay đổi Playbook `1.0.0` → `1.1.0`

Đối tượng: BA / PO / Ad Ops. Tham chiếu: ba-remote-config-playbook.md. Ngày: 2026-05-12.

Mục lục

Tổng quan
Boolean key mới
Thay đổi fo_config_ad_splash / ru_config_ad_splash
Thay đổi inapp_ad_<vị-trí>
Phần không đổi
Checklist rollout

1. Tổng quan

Hạng mục	1.0.0	1.1.0
Số Boolean key	6	9 (+3)
Số JSON key	4	4 (giữ nguyên)
Splash `logic`	`variant_1`, `variant_2`	`variant_1`, `variant_2`, `variant_3`
Schema `inapp_ad_<tp>`	Flat	Dual-shape (flat + nested)
Back-compat	—	100% — không đổi default, không xoá key cũ

Nếu không sửa Firebase, hành vi SDK 1.1.0 giống hệt 1.0.0.

2. Boolean key mới

Bổ sung 3 key vào §2.1 và §3.8 của playbook.

Key	Default	Mô tả
`fo_refill_by_ad`	`true`	`true` → auto reload Native ad sau end-of-video hoặc sau khi user đóng bottom-sheet click ad. `false` → giữ ad cũ tới chu kỳ refresh.
`fo_logic_inter_splash_inc_impression`	`false`	Chỉ áp FO user. `true` → cho phép Inter Splash overlap với Onboarding/Main để tăng impression. `false` → đợi user đóng Inter mới chuyển màn.
`fo_enable_open_ad_on_continue_bar`	`true`	`true` → bật App Open Ad khi user resume từ thanh "Continue" của OS. `false` → bỏ qua App Open ở case này.

Action: tạo 3 key trên Firebase với đúng default → Publish.

3. Thay đổi `fo_config_ad_splash` / `ru_config_ad_splash`

3.1 Trường `logic` — thêm giá trị `variant_3`

Giá trị	Waterfall	Có Inter fallback
`variant_1`	Native → Interstitial	Có
`variant_2`	Interstitial HF → Interstitial standard	Có
`variant_3` (mới)	Native HF → Native standard → null	Không

3.2 Field mới `logic_reload_fallback`

Field	Default	Điều kiện áp dụng	Tác dụng
`logic_reload_fallback`	`false`	`logic=variant_3` + `native_2id_enabled=true`	Loader thử HF + Standard song song trong 1 lần gọi để giảm thời gian khi HF no-fill.

3.3 Ràng buộc khi dùng `variant_3`

Yêu cầu partner đã cấp ID nativeSplash (Native standard) ở code-side. Nếu chưa cấp, chain rút gọn còn HF → null.
Cả 2 tầng dùng chung timeout_seconds. Nên nới timeout hoặc bật logic_reload_fallback khi enable.
Rủi ro skip-ad: nếu cả 2 tầng fail, splash đi tiếp không có ad. BA cần align với PO trước khi đổi.

3.4 JSON mặc định mới

{
  "is_enabled": true,
  "logic": "variant_1",
  "countdown_seconds": 5,
  "timeout_seconds": 60,
  "native_2id_enabled": false,
  "inter_2id_enabled": false,
  "logic_reload_fallback": false,
  "time_pass_seconds": 0,
  "layout_type": "na_re"
}

So với 1.0.0: thêm dòng "logic_reload_fallback": false.

4. Thay đổi `inapp_ad_<vị-trí>`

Schema chuyển sang dual-shape: giữ field phẳng cũ + thêm khối nested fo / ru.

4.1 Field top-level mới

Field	Default	Tác dụng
`ad2id_enabled`	`true`	`false` → bỏ qua ID Native HF (`NativeAd2Id`), chỉ thử standard. Áp với cả `na_then_in` và `only_na`.
`logic_reload_fallback`	`false`	Chỉ áp khi `ad2id_enabled=true` + `logic_load_ad=only_na`. Loader thử HF + Standard song song.

4.2 Khối nested `fo` / `ru` (mới)

Mỗi khối mô tả hành vi riêng cho FO (user mới) và RU (user cũ).

Field	Default	Giá trị hợp lệ	Tác dụng
`layout`	`na_in`	`na_in` / `na_re` / `na_preparing`	Layout UI
`logic_load_ad`	`na_then_in`	`na_then_in` / `only_na`	Chiến lược waterfall — xem §4.3
`start`	`1`	`0` = không show, `≥1`	Lần trigger đầu tiên được show
`step`	`2`	`≥1`	Show mỗi N lần trigger sau `start`

4.3 Bảng `logic_load_ad`

Giá trị	Waterfall	Khi dùng
`na_then_in` (mặc định)	Native HF → fail → Interstitial	90% touchpoint
`only_na`	Native HF → fail → Native standard	Surface chỉ chạy native

Lưu ý: với na_then_in, ID NativeAdId (standard) bị bỏ qua. Muốn dùng standard, BA phải set only_na.

4.4 Bảng `start` / `step`

`start`	`step`	Show ở các lần trigger
`0`	*	Không bao giờ
`1`	`1`	1, 2, 3, 4, … (mọi lần)
`1`	`2`	1, 3, 5, 7, … (chuẩn)
`2`	`3`	2, 5, 8, 11, …

Counter đếm riêng cho FO và RU, lưu cục bộ trên thiết bị.

4.5 JSON mặc định mới

{
  "enabled": true,
  "native_enabled": true,
  "inter_enabled": true,
  "ad2id_enabled": true,
  "logic_reload_fallback": false,
  "countdown_seconds": 5,
  "time_auto_pass_second": 0,
  "fo_layout": "na_in",
  "return_layout": "na_in",
  "fo": {
    "layout": "na_in",
    "logic_load_ad": "na_then_in",
    "start": 1,
    "step": 2
  },
  "ru": {
    "layout": "na_in",
    "logic_load_ad": "na_then_in",
    "start": 1,
    "step": 2
  }
}

4.6 Quy tắc dual-shape

SDK trên thiết bị	Cách đọc
`1.0.0`	Chỉ đọc `fo_layout` / `return_layout`. Bỏ qua khối `fo` / `ru` và các field mới. Không crash.
`1.1.0`	Ưu tiên đọc khối nested `fo` / `ru`. Nếu Firebase chỉ có field phẳng, SDK tự synthesize nested với default: `logic_load_ad=na_then_in`, `start=1`, `step=2`.

Điều kiện xoá field phẳng fo_layout / return_layout: tỷ lệ cài SDK 1.0.0 < 1%.

4.7 Key cũ cần xoá

Nếu trước đây BA đã tạo inapp_ad_rule_show_<vị-trí> — xoá. Rule-show đã gộp vào start / step trong khối nested.

5. Phần không đổi

6 Boolean key cũ: fo_banner_splash, fo_hf_banner_splash, fo_enable_onboarding, fo_native_onboarding, fo_native_onboarding_2ID, fo_allow_log_tester.
JSON fo_config_ad_resume (Resume Ad).
JSON fo_onboarding_config (nội dung onboarding).
Hành vi variant_1 và variant_2 của Splash.
Mọi giá trị mặc định.

6. Checklist rollout

#	Việc	Bắt buộc
1	Tạo 3 Boolean key mới (§2) với default ở bảng	Có
2	Cập nhật mỗi `inapp_ad_<vị-trí>` sang JSON dual-shape (§4.5), giữ cả field phẳng + nested	Có
3	Thêm `"logic_reload_fallback": false` vào `fo_config_ad_splash` và `ru_config_ad_splash` (§3.4)	Có
4	Nếu cần thử `variant_3`: confirm code-side đã cấp `nativeSplash`, align với PO, rồi đổi `logic`	Tuỳ chọn
5	Publish trên Firebase Remote Config	Có
6	Verify trên build QA: bật `fo_allow_log_tester=true`, đọc log `[InAppAd]` / `[SplashAd]`	Có
7	Tắt `fo_allow_log_tester=false` trước khi release production	Có

SDK 1.1.0 có legacy adapter — có thể release SDK trước, migrate JSON sau.

Thay đổi Playbook 1.0.0 → 1.1.0