# MonetizeD7 — Ad Unit ID & Config Reference

**SDK:** `1.1.1` • **Ngày:** 2026-05-14
**Người đọc:** Đối tác (Partner Dev) • **Người gửi:** BA / Ad Ops (Apero)

Tài liệu liệt kê **ad unit ID** cần cung cấp cho từng vị trí ad + code config tương ứng. Mọi logic hiển thị, waterfall, fallback do Apero điều khiển qua Firebase Remote Config.

> **Quy ước:** Chưa có ID nào → truyền chuỗi rỗng `""` — SDK tự skip tier đó, không gọi AdMob lãng phí.

---

## Mục lục

1. [Luồng FirstOpen — Config theo vị trí ad](#1-luồng-firstopen--config-theo-vị-trí-ad)
2. [Luồng InApp — Config theo touchpoint](#2-luồng-inapp--config-theo-touchpoint)
3. [Code tổng hợp — FirstOpenConfig.Builder](#3-code-tổng-hợp--firstopenconfigbuilder)

---

## 1. Luồng FirstOpen — Config theo vị trí ad

Luồng: **Launcher → Splash → Onboarding → Main**. Mỗi vị trí ad bên dưới liệt kê ID cần cung cấp + code config.

---

### 1.1 Splash (bắt buộc)

**Ad unit ID cần cung cấp:**

| # | Vị trí | Tier | Format | ID | BuildConfig field |
|---|---|---|---|---|---|
| 1 | Splash Native | 2ID | Native | `ca-app-pub-___/___` | `NATIVE_SPLASH_HF` |
| 2 | Splash Native | Normal | Native | `ca-app-pub-___/___` | `NATIVE_SPLASH` |
| 3 | Splash Inter | 2ID | Interstitial | `ca-app-pub-___/___` | `INTER_SPLASH_HF` |
| 4 | Splash Inter | Normal | Interstitial | `ca-app-pub-___/___` | `INTER_SPLASH` |
| 5 | Splash Banner | 2ID | Banner | `ca-app-pub-___/___` | `BANNER_SPLASH_HF` |
| 6 | Splash Banner | Normal | Banner | `ca-app-pub-___/___` | `BANNER_SPLASH` |

**Khai báo trong `build.gradle.kts`:**

```kotlin
// debug
buildConfigField("String", "NATIVE_SPLASH_HF", "\"ca-app-pub-3940256099942544/2247696110\"")
buildConfigField("String", "NATIVE_SPLASH",    "\"ca-app-pub-3940256099942544/2247696110\"")
buildConfigField("String", "INTER_SPLASH_HF",  "\"ca-app-pub-3940256099942544/1033173712\"")
buildConfigField("String", "INTER_SPLASH",     "\"ca-app-pub-3940256099942544/1033173712\"")
buildConfigField("String", "BANNER_SPLASH_HF", "\"ca-app-pub-3940256099942544/6300978111\"")
buildConfigField("String", "BANNER_SPLASH",    "\"ca-app-pub-3940256099942544/6300978111\"")

// release — thay bằng production ID từ AdMob console
buildConfigField("String", "NATIVE_SPLASH_HF", "\"ca-app-pub-XXXX/YYYY\"")
// ... tương tự
```

**Code config:**

```kotlin
.setSplashAdConfig(
    FirstOpenConfig.SplashAdConfig(
        nativeSplash2ID = NativeAd2Id(BuildConfig.NATIVE_SPLASH_HF),
        nativeSplash    = NativeAdId(BuildConfig.NATIVE_SPLASH),
        interSplash2ID  = InterAd2Id(BuildConfig.INTER_SPLASH_HF),
        interSplash     = InterAdId(BuildConfig.INTER_SPLASH),
        bannerSplash    = BannerAdDouble(
            highFloor = BannerAd2Id(BuildConfig.BANNER_SPLASH_HF),
            standard  = BannerAdId(BuildConfig.BANNER_SPLASH),
        ),
    )
)
```

---

### 1.2 Onboarding (tùy chọn)

**Ad unit ID cần cung cấp:**

| # | Vị trí | Tier | Format | ID | BuildConfig field |
|---|---|---|---|---|---|
| 1 | Onboarding Native | 2ID | Native | `ca-app-pub-___/___` | `NATIVE_OB_HF` |
| 2 | Onboarding Native | Normal | Native | `ca-app-pub-___/___` | `NATIVE_OB` |

**Khai báo trong `build.gradle.kts`:**

```kotlin
buildConfigField("String", "NATIVE_OB_HF", "\"ca-app-pub-3940256099942544/2247696110\"")
buildConfigField("String", "NATIVE_OB",    "\"ca-app-pub-3940256099942544/2247696110\"")
```

**Code config:**

```kotlin
.setOnboardingAdConfig(
    FirstOpenConfig.OnboardingAdConfig(
        nativeOnboarding = NativeAdDouble(
            highFloor = NativeAd2Id(BuildConfig.NATIVE_OB_HF),
            standard  = NativeAdId(BuildConfig.NATIVE_OB),
        ),
    )
)
```

> Bỏ block `.setOnboardingAdConfig(...)` nếu không cần ad onboarding.

---

### 1.3 Resume — khi user quay lại app (tùy chọn)

**Ad unit ID cần cung cấp:**

| # | Vị trí | Tier | Format | ID | BuildConfig field |
|---|---|---|---|---|---|
| 1 | Resume | Normal | App Open | `ca-app-pub-___/___` | `APP_OPEN_RESUME` |
| 2 | Resume | Normal | Native | `ca-app-pub-___/___` | `NATIVE_RESUME` |

**Khai báo trong `build.gradle.kts`:**

```kotlin
buildConfigField("String", "APP_OPEN_RESUME", "\"ca-app-pub-3940256099942544/9257395921\"")
buildConfigField("String", "NATIVE_RESUME",   "\"ca-app-pub-3940256099942544/2247696110\"")
```

**Code config:**

```kotlin
.setResumeAdConfig(
    FirstOpenConfig.ResumeAdConfig(
        appOpenResume = AppOpenAdId(BuildConfig.APP_OPEN_RESUME),
        nativeResume  = NativeAdId(BuildConfig.NATIVE_RESUME),
    )
)
```

> Bỏ block `.setResumeAdConfig(...)` nếu không cần ad resume.

---

## 2. Luồng InApp — Config theo touchpoint

InApp Ad = ad hiển thị tại **các điểm trong app** (sau first-open flow). Mỗi điểm gọi là **touchpoint (tp)**.

> **Tên touchpoint do BA quy ước.** Đối tác **PHẢI dùng đúng tên** BA đã define — sai tên (kể cả viết hoa/thường) sẽ khiến SDK không nhận diện được vị trí, ad không hiển thị và Remote Config không có tác dụng.
>
> BA bổ sung / chỉnh sửa bảng mỗi touchpoint bên dưới trước khi gửi đối tác.

---

### 2.1 Touchpoint: `home`

| Thông tin | Giá trị |
|---|---|
| **Tên touchpoint (`tp`)** | `home` |
| **Mô tả** | Màn Home → bấm nút chuyển tiếp → show ad → đi tiếp |
| **Preload ở đâu** | `HomeActivity` — dùng `bindActivity` (SDK tự preload mỗi `onStart`) |
| **Show ở đâu** | `HomeActivity` — khi user bấm nút chuyển tiếp |

**Ad unit ID cần cung cấp:**

| # | Tier | Format | ID |
|---|---|---|---|
| 1 | 2ID | Native | `ca-app-pub-___/___` |
| 2 | Normal | Native | `ca-app-pub-___/___` |
| 3 | — | Interstitial | `ca-app-pub-___/___` |

**Register (trong Application):**

```kotlin
.register(
    tp = "home",                                           // ← đúng tên BA quy ước
    nativeAd2Id  = NativeAd2Id(BuildConfig.NATIVE_HOME_HF),
    nativeAdId   = NativeAdId(BuildConfig.NATIVE_HOME),
    inter        = InterAdId(BuildConfig.INTER_HOME),
    bindActivity = HomeActivity::class.java,               // SDK tự preload
)
```

**Show (trong HomeActivity):**

```kotlin
// bindActivity đã tự preload — không cần gọi preload thủ công
InAppAdManager.show(this, "home") {
    startActivity(Intent(this, ResultActivity::class.java))
}
```

---

### 2.2 Touchpoint: `share`

| Thông tin | Giá trị |
|---|---|
| **Tên touchpoint (`tp`)** | `share` |
| **Mô tả** | Màn Share → bấm chia sẻ → show ad → thực hiện share |
| **Preload ở đâu** | `ShareActivity` — dùng `bindActivity` (SDK tự preload mỗi `onStart`) |
| **Show ở đâu** | `ShareActivity` — khi user bấm nút share |

**Ad unit ID cần cung cấp:**

| # | Tier | Format | ID |
|---|---|---|---|
| 1 | 2ID | Native | `ca-app-pub-___/___` |
| 2 | Normal | Native | `ca-app-pub-___/___` |
| 3 | — | Interstitial | _(không dùng)_ |

**Register:**

```kotlin
.register(
    tp = "share",                                           // ← đúng tên BA quy ước
    nativeAd2Id = NativeAd2Id(BuildConfig.NATIVE_SHARE_HF),
    nativeAdId  = NativeAdId(BuildConfig.NATIVE_SHARE),
    inter       = InterAdId(""),                            // skip inter
    bindActivity = ShareActivity::class.java,
)
```

**Show (trong ShareActivity):**

```kotlin
InAppAdManager.show(this, "share") {
    proceedShare()
}
```

---

### 2.N Touchpoint: `___` _(BA thêm tiếp theo mẫu trên)_

| Thông tin | Giá trị |
|---|---|
| **Tên touchpoint (`tp`)** | `___` |
| **Mô tả** | _mô tả vị trí + hành vi_ |
| **Preload ở đâu** | _Activity nào, dùng `bindActivity` hay `bindPreload()`_ |
| **Show ở đâu** | _Activity/Fragment nào, khi nào trigger_ |

**Ad unit ID cần cung cấp:**

| # | Tier | Format | ID |
|---|---|---|---|
| 1 | 2ID | Native | `ca-app-pub-___/___` |
| 2 | Normal | Native | `ca-app-pub-___/___` |
| 3 | — | Interstitial | `ca-app-pub-___/___` |

---

## 3. Code tổng hợp — FirstOpenConfig.Builder

Ghép tất cả ad unit ID vào `FirstOpenConfig.Builder` trong `Application.onCreate()`:

```kotlin
FirstOpenSDK.configure(
    FirstOpenConfig.Builder(MyNextActionListener())
        .setDevelopment(BuildConfig.DEBUG)

        // ── 1.1 Splash (bắt buộc) ──
        .setSplashAdConfig(
            FirstOpenConfig.SplashAdConfig(
                nativeSplash2ID = NativeAd2Id(BuildConfig.NATIVE_SPLASH_HF),
                nativeSplash    = NativeAdId(BuildConfig.NATIVE_SPLASH),
                interSplash2ID  = InterAd2Id(BuildConfig.INTER_SPLASH_HF),
                interSplash     = InterAdId(BuildConfig.INTER_SPLASH),
                bannerSplash    = BannerAdDouble(
                    highFloor = BannerAd2Id(BuildConfig.BANNER_SPLASH_HF),
                    standard  = BannerAdId(BuildConfig.BANNER_SPLASH),
                ),
            )
        )

        // ── 1.2 Onboarding (tùy chọn) ──
        .setOnboardingAdConfig(
            FirstOpenConfig.OnboardingAdConfig(
                nativeOnboarding = NativeAdDouble(
                    highFloor = NativeAd2Id(BuildConfig.NATIVE_OB_HF),
                    standard  = NativeAdId(BuildConfig.NATIVE_OB),
                ),
            )
        )

        // ── 1.3 Resume (tùy chọn) ──
        .setResumeAdConfig(
            FirstOpenConfig.ResumeAdConfig(
                appOpenResume = AppOpenAdId(BuildConfig.APP_OPEN_RESUME),
                nativeResume  = NativeAdId(BuildConfig.NATIVE_RESUME),
            )
        )

        // ── 2.x InApp (tùy chọn) ──
        .setInAppAd(
            InAppAdConfig.Builder()
                .register(   // 2.1 home
                    tp = "home",
                    nativeAd2Id  = NativeAd2Id(BuildConfig.NATIVE_HOME_HF),
                    nativeAdId   = NativeAdId(BuildConfig.NATIVE_HOME),
                    inter        = InterAdId(BuildConfig.INTER_HOME),
                    bindActivity = HomeActivity::class.java,
                )
                .register(   // 2.2 share
                    tp = "share",
                    nativeAd2Id = NativeAd2Id(BuildConfig.NATIVE_SHARE_HF),
                    nativeAdId  = NativeAdId(BuildConfig.NATIVE_SHARE),
                    inter       = InterAdId(""),
                    bindActivity = ShareActivity::class.java,
                )
                .build()
        )
        .build()
)
```

> Tên `tp` phải khớp chính xác với bảng mỗi touchpoint ở mục 2 do BA quy ước.