# Turn 2 — Thay đổi cho tài liệu BA / Remote Config

> **Mục tiêu:** liệt kê các điểm cần cập nhật trong `docs/ba-remote-config-playbook.md` (và link md2link tương ứng) khi release Turn 2.
> **SDK version:** `1.1.0-alpha01` (alpha — còn test + fixbug).
> **Phạm vi:** key `inapp_ad_<tp>` cho mỗi touchpoint trong app.

---

## 1. Schema JSON `inapp_ad_<tp>` — cấu trúc mới

Trước đây flat. Turn 2 gộp rule-show vào trong nested block `fo` / `ru`:

```json
{
  "enabled": true,
  "native_enabled": true,
  "ad2id_enabled": true,
  "inter_enabled": true,
  "countdown_seconds": 5,
  "time_auto_pass_second": 0,
  "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
  }
}
```

> **Trước (cần XOÁ khỏi doc):** `fo_layout`, `return_layout` ở top-level, key riêng `inapp_ad_rule_show_<tp>`.

## 2. Trường mới (cần bổ sung table chi tiết)

### Top-level

| Trường | Kiểu | Mặc định | Tác dụng |
|--------|------|----------|----------|
| `ad2id_enabled` | bool | `true` | Bật/tắt thử high-floor (`NativeAd2Id`). `false` → bỏ qua hf, dùng standard luôn (chỉ áp với `only_na`) |

### Nested `fo` / `ru` block (mới)

| Trường | Kiểu | Mặc định | Giá trị hợp lệ | Tác dụng |
|--------|------|----------|----------------|----------|
| `layout` | string | `na_in` | `na_in`, `na_re`, `na_preparing` | Layout UI cho flow |
| `logic_load_ad` | string | `na_then_in` | `na_then_in`, `only_na` | Chiến lược waterfall — xem §3 |
| `start` | int | `1` | `>= 1` | Lần impression đầu tiên được show. `0` = không bao giờ show |
| `step` | int | `2` | `>= 1` | Show mỗi N lần đếm sau `start`. `1` = mọi lần |

> Trường `time_auto_pass_second` đã có từ trước Turn 2 — **không phải mới**, chỉ note giữ nguyên.

## 3. Bảng tra cứu `logic_load_ad`

| Giá trị | Hành vi | Khi dùng |
|---------|---------|----------|
| `na_then_in` (default) | Thử high-floor → fail → interstitial | InApp touchpoint thông thường |
| `only_na` | Sequential: high-floor → standard. **Không** fallback inter | Surface chỉ chạy native |

**Lưu ý quan trọng:** với `na_then_in`, `NativeAdDouble.standard` của partner bị **bỏ qua** — chỉ thử high-floor. Muốn dùng standard, BA phải bật `only_na`.

## 4. Combo cấu hình → hành vi

| Cấu hình | Kết quả |
|----------|---------|
| `enabled=true, native_enabled=true, inter_enabled=true, fo.logic_load_ad=na_then_in` | hf native fail → inter (90% case) |
| `enabled=true, native_enabled=true, inter_enabled=false` | Chỉ native, không fallback |
| `enabled=true, native_enabled=true, fo.logic_load_ad=only_na` | hf → standard, no inter |
| `enabled=true, native_enabled=false, inter_enabled=true` | Chỉ interstitial |
| `enabled=false` | Tắt touchpoint, action chạy luôn |
| `ad2id_enabled=false` (chỉ áp `only_na`) | Bỏ qua high-floor, dùng standard |
| `start=0` | Không bao giờ show |
| `start=1, step=1` | Show mọi trigger |
| `start=2, step=3` | Show ở trigger thứ 2, 5, 8, … |

## 5. Section cần cập nhật cụ thể trong `ba-remote-config-playbook.md`

- **§2.4** "Giá trị JSON mặc định cho mỗi `inapp_ad_<tên-vị-trí>`" — thay bằng JSON mới ở §1 trên.
- **§3.6** "Quảng cáo trong app (InApp)" — thay table fields:
  - **Bỏ:** `fo_layout`, `return_layout` ở top-level.
  - **Thêm:** `ad2id_enabled` (top-level); nested `fo` / `ru` block với `layout`, `logic_load_ad`, `start`, `step`.
- **§4.4** "InApp theo từng vị trí" — bổ sung bảng combo §4 ở trên.

## 6. Migration cho remote đã deploy schema cũ

SDK có **legacy adapter** — nếu Firebase còn dùng schema phẳng cũ (`fo_layout`, `return_layout`), SDK tự synthesize:
- `layout` = parsed từ `fo_layout` / `return_layout`
- `logic_load_ad` = `na_then_in`
- `start` = `1`, `step` = `2` (mặc định spec)

→ BA có thể deploy SDK Turn 2 trước, migrate JSON sang nested sau, không cần đổi đồng thời.