# Turn 2: Add flow — Spec (SDK 1.1.0)

|  |  |
|---|---|
| **Department** | Android — Monetize |
| **Link design** | [Figma — lib-D7](https://www.figma.com/design/laK9wkxD0n57BTVq2LhfmL/lib-D7?node-id=0-1) |
| **Event tracking** | [Google Sheet](https://docs.google.com/spreadsheets/d/1DY6tZNud_NBYwDu1ZFzK-o8UwC9SNfNaT6WsfL6oae4/edit?gid=117527867) |
| **Version baseline** | `1.1.0` |

---

## I. Tổng quan

| Hiện trạng | Nguyên nhân | Mục tiêu | Action |
|---|---|---|---|
| Ad in-app hiện chỉ là ad native 2ID + inter thường. Khi show native dạng preparing/resume bị lệch UI. Không A/B test được nhiều kịch bản ad. | Đối soát chưa kỹ, thiếu phương án native thường làm fallback. | Bổ sung hỗ trợ ad native thường trong các ad in-app. | — |

---

## II. Mô tả chi tiết

### 1. Ad splash

**Hiện trạng:** ad splash chỉ hỗ trợ load native 2ID với inter thường.

**Mong muốn:**

- Hỗ trợ load alternate ad native 2ID và ad native thường.
- Thêm `variant_3`: load alternate `native_splash_2ID` và `native_splash`.

---

### 2. Ad inapp

**Hiện trạng:** hỗ trợ load alternate ad native 2ID và ad inter thường cho all layout ad.

**Mong muốn:**

- Hỗ trợ load alternate ad native 2ID và ad inter thường / native thường.
- Đối tác có thể truyền vào cả 3 ID cho cùng 1 vị trí.
- Thêm trường JSON quy định loại load ad là native 2ID + native thường hay native 2ID + inter thường.
- Thêm `start` và `step` cho show ad in-app tách theo luồng FO và Return User.

**Remote config:**

| key | value |
|---|---|
| `inapp_ad_<tên-vị-trí>` | `{ "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", "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ường | Value | Des |
|---|---|---|
| `enabled` | `true` (default) / `false` | Bật/tắt toàn bộ touchpoint. `false` → chạy action ngay, không show ad. |
| `native_enabled` | `true` (default) / `false` | Bật/tắt nhánh native |
| `inter_enabled` | `true` (default) / `false` | Bật/tắt nhánh inter |
| `ad2id_enabled` | `true` (default) / `false` | Bật/tắt nhánh HF native (`NativeAd2Id`) |
| `logic_reload_fallback` | `true` / `false` (default) | Xem Task 4 |
| `countdown_seconds` | int (default `5`) | Khoá nút close trong N giây |
| `time_auto_pass_second` | int (default `0`) | Auto-dismiss sau N giây. `0` = tắt |
| `fo.layout`, `ru.layout` | `na_in` (default) / `na_re` / `na_preparing` | Layout native cho từng luồng |
| `fo.logic_load_ad` | `na_then_in` (default) | load alternate native 2ID và inter thường cho luồng FO |
|  | `only_na` | load alternate native 2ID và native thường cho luồng FO |
| `ru.logic_load_ad` | `na_then_in` (default) | load alternate native 2ID và inter thường cho luồng Return |
|  | `only_na` | load alternate native 2ID và native thường cho luồng Return |
| `fo.start`, `ru.start` | int (default `1`) | Lần đầu show ad là lần thứ mấy. `0` = không show |
| `fo.step`, `ru.step` | int (default `2`) | Step show ad sau `start`. `1` = mọi lần |

---

### 3. Thay đổi UI Loading ad

**Hiện trạng:** UI loading ad cũ (xem `image-2026-5-6_17-51-38.png`).

**Mong muốn:** điều chỉnh thành dạng mới (xem `image-2026-5-6_17-52-25.png`). Đối tác truyền vào **Lottie JSON** (animation) hoặc **drawable** (static image) cho phần hiệu ứng ad break.

| Resource key | Loại | Mô tả |
|---|---|---|
| `fo_anim_ad_loading` | raw (Lottie JSON) | Animation override (ưu tiên) |
| `fo_img_ad_loading` | drawable | Static image override (fallback nếu thiếu Lottie) |
| `fo_loading_indicator` | raw (Lottie JSON) | SDK bundled animation (default khi đối tác không override) |

---

### 4. Logic reload ad

**Hiện trạng:** với các ad native full hiện tại khi reload không theo logic fallback.

**Mong muốn:** khi reload ad cần reload theo logic fallback. Ví dụ: load ad 2ID trước, fail thì load ad all-price.

| Key | Value | Des |
|---|---|---|
| `logic_reload_fallback` | `true` | bật logic reload fallback |
|  | `false` (default) | tắt logic reload fallback |

**Phạm vi áp dụng:**

| Surface | Áp `logic_reload_fallback` |
|---|---|
| Splash `variant_3` (`NATIVE_DUAL`) | ✅ |
| In-app `only_na` | ✅ |
| Splash `variant_1`, `variant_2` | ❌ |
| In-app `na_then_in` | ❌ |
| Onboarding, Resume, Banner | ❌ |