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

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

---

## Mục lục

1. [Tổng quan](#1-tổng-quan)
2. [Boolean key mới](#2-boolean-key-mới)
3. [Thay đổi `fo_config_ad_splash` / `ru_config_ad_splash`](#3-thay-đổi-fo_config_ad_splash--ru_config_ad_splash)
4. [Thay đổi `inapp_ad_<vị-trí>`](#4-thay-đổi-inapp_ad_vị-trí)
5. [Phần không đổi](#5-phần-không-đổi)
6. [Checklist rollout](#6-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

```json
{
  "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

```json
{
  "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.