Hướng dẫn cấu hình quảng cáo (Remote Config) — MonetizeD7

Tài liệu nội bộ dành cho BA / PO / Ad Ops. Mục đích: biết cần đặt thiết lập nào trên Firebase, giá trị bao nhiêu, để app hoạt động đúng theo mong muốn kinh doanh.

Phiên bản SDK: 1.1.0 • Đối chiếu code: 2026-05-12

Mục lục

1. Cách hoạt động (đọc 1 phút)
2. Bộ thiết lập mặc định — đầy đủ
3. Chi tiết từng thiết lập
4. Bảng tra cứu kết quả theo cấu hình
5. Changelog phiên bản tài liệu

1. Cách hoạt động (đọc 1 phút)

• App đọc Firebase Remote Config 1 lần ở màn Splash mỗi khi mở app.
• Sau khi đổi giá trị trên Firebase, người dùng phải đóng hẳn app rồi mở lại mới thấy giá trị mới (giá trị bị giữ cố định trong suốt 1 phiên dùng app).
• App ở chế độ debug (cho QA): cứ 30 giây mới đồng bộ lại 1 lần.
• App ở chế độ production (release): 12 tiếng mới đồng bộ lại (mặc định Firebase).
• Người dùng chia làm 2 nhóm:
  • Người dùng mới (FO — First-Open): chưa hoàn tất onboarding.
  • Người dùng cũ (RU — Return User): đã hoàn tất onboarding rồi.
  • 2 nhóm dùng 2 bộ thiết lập Splash khác nhau → cho phép chiến lược khác nhau.
• Người dùng đã trả phí (premium) sẽ không bao giờ thấy quảng cáo, dù Firebase bật hay tắt.

2. Bộ thiết lập mặc định — đầy đủ

Đây là toàn bộ thiết lập Firebase mà app đọc, kèm giá trị mặc định khi thiết lập vắng mặt. Khi tạo Firebase project mới: chỉ cần tạo các thiết lập dưới với đúng kiểu và dán giá trị mặc định để mô phỏng hành vi mặc định của SDK.

2.1 Bảng tổng — sao chép vào Firebase Console

Tổng: 9 thiết lập Boolean + 4 nhóm thiết lập JSON + N thiết lập inapp_ad_* (số lượng tuỳ vào số "vị trí hiển thị ad" mà đối tác đăng ký).

2.2 Giá trị JSON mặc định cho fo_config_ad_splash & ru_config_ad_splash

{
  "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"
}

2.3 Giá trị JSON mặc định cho fo_config_ad_resume

{
  "is_enabled": true,
  "type": null,
  "layout_type": "na_re",
  "countdown_seconds": 5,
  "time_pass_seconds": 3
}

2.4 Giá trị JSON mặc định cho mỗi inapp_ad_<tên-vị-trí>

Từ SDK 1.1.0: schema mới dạng nested fo / ru block (gộp luôn rule-show). BA vẫn phải giữ các trường legacy phẳng fo_layout / return_layout để tương thích ngược với các thiết bị còn cài SDK 1.0.0 (xem ghi chú "Dual-shape" cuối §2.4 và §3.6).

{
  "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
  }
}

Dual-shape (tương thích SDK 1.0.0 ↔ 1.1.0). Giữ song song cả 2 dạng cho tới khi tỷ lệ cài SDK 1.0.0 < 1%:

• SDK 1.0.0 chỉ đọc fo_layout / return_layout (bỏ qua khối fo / ru, ad2id_enabled, logic_reload_fallback, start, step, logic_load_ad — không crash).
• SDK 1.1.0 ưu tiên đọc khối nested fo / ru. Nếu chỉ có flat fo_layout / return_layout (schema 1.0.0), SDK tự synthesize sang nested với mặc định: logic_load_ad="na_then_in", start=1, step=2.

2.5 Giá trị JSON mặc định cho fo_onboarding_config (tuỳ chọn — dùng nếu muốn đổi nội dung onboarding qua Firebase)

Mặc định = chuỗi rỗng → app dùng text + ảnh hardcode trong code. Nếu muốn đổi:

{
  "timePerSlide": 8,
  "slides": [
    {"title": "...", "subtitle": "...", "image": "https://...", "actionLabel": "Next"},
    {"title": "...", "subtitle": "...", "image": "https://...", "actionLabel": "Next"},
    {"title": "...", "subtitle": "...", "image": "https://...", "actionLabel": "Get Started"}
  ]
}

2.6 Checklist setup Firebase Project mới

• Tạo 9 thiết lập Boolean (#1–#9 ở §2.1) với giá trị mặc định ở §2.1
• Tạo 4 thiết lập JSON (#10–#13) — dán JSON mẫu từ §2.2 / §2.3 / §2.5
• Hỏi đối tác danh sách vị trí hiển thị ad → tạo 1 thiết lập inapp_ad_<tên> cho mỗi vị trí, dán JSON §2.4 (giữ cả nested + flat cho tới khi sunset SDK 1.0.0)
• Bấm Publish trên Firebase Remote Config
• Kiểm tra trong app: bật fo_allow_log_tester=true rồi đọc logcat tag [InAppAd] để verify

Nếu không tạo thiết lập nào trên Firebase, app vẫn chạy bình thường với giá trị mặc định trên — không bị crash. Chỉ cần tạo trên Firebase khi muốn đổi giá trị so với mặc định.

3. Chi tiết từng thiết lập

3.1 Banner Splash

3.2 Quảng cáo toàn màn hình ở Splash — cho người dùng mới (fo_config_ad_splash)

Tên thiết lập trên Firebase: fo_config_ad_splash — kiểu String JSON.

3.2.1 Lưu ý quan trọng cho logic=variant_3 (NATIVE_DUAL)

• Waterfall: nativeSplash2ID (highfloor) → nativeSplash (standard) → null (không hiển thị ad).
• Không có fallback Interstitial. Nếu cả 2 tầng native đều fail → splash đi tiếp không có ad (skip).
• Yêu cầu đối tác đã cấp nativeSplash (ID native standard) ở code-side. Nếu chưa cấp (truyền ""), chain rút gọn còn 2ID → null.
• Khuyến nghị chỉ dùng cho app có inventory native mạnh và chấp nhận đôi lúc không show ad. Nếu bắt buộc luôn show ad → dùng variant_1 (có inter fallback) hoặc variant_2.
• Timeout note: cả 2 tầng dùng chung timeout_seconds. HF chạy gần hết timeout có thể "ăn" hết thời gian của standard. Khi bật variant_3 nên cân nhắc nới timeout_seconds hoặc bật logic_reload_fallback (nạp song song).

3.3 Quảng cáo toàn màn hình ở Splash — cho người dùng cũ (ru_config_ad_splash)

Cấu trúc y hệt fo_config_ad_splash (kể cả logic=variant_3 và logic_reload_fallback). Áp dụng khi user đã hoàn tất onboarding.

Tách riêng để có thể đặt chiến lược khác nhau giữa người dùng mới (cần ấn tượng mạnh) và người dùng cũ (cần nhẹ nhàng).

3.4 Onboarding

Cấu trúc JSON fo_onboarding_config:

3.5 Quảng cáo Resume (khi user mở lại app từ background)

Tên thiết lập trên Firebase: fo_config_ad_resume — kiểu String JSON.

3.6 Quảng cáo trong app (InApp) — theo từng vị trí

Mỗi vị trí hiển thị ad trong app (do đối tác đăng ký) có 1 thiết lập riêng tên: inapp_ad_<tên-vị-trí> — kiểu String JSON.

Ví dụ: inapp_ad_home, inapp_ad_save, inapp_ad_share, inapp_ad_settings.

Từ SDK 1.1.0, schema chuẩn là nested (fo / ru block), kèm các trường legacy phẳng (fo_layout, return_layout) phải giữ song song để forward-compat với SDK 1.0.0 đang cài trên user thật. Xem ghi chú "Dual-shape" ở cuối §2.4.

3.6.1 Trường top-level

3.6.2 Khối nested fo / ru (MỚI 1.1.0)

Mỗi block mô tả hành vi riêng cho 1 flow:

Ví dụ rule-show: start=2, step=3 → show ở trigger thứ 2, 5, 8, 11, …

3.6.3 Bảng tra cứu logic_load_ad

⚠️ Lưu ý cho BA: với logic_load_ad=na_then_in, ID NativeAdId (standard) do partner cấp sẽ bị bỏ qua — chỉ thử HF (NativeAd2Id). Muốn dùng standard, BA phải set logic_load_ad=only_na.

3.7 Các kiểu giao diện (Layout)

Resume Ad chỉ chấp nhận na_re hoặc na_preparing (không hỗ trợ na_in).

3.8 Các thiết lập hành vi khác

4. Bảng tra cứu kết quả theo cấu hình

4.1 Splash toàn màn hình (cho cả FO/RU)

4.2 Onboarding

4.3 Resume Ad

4.4 InApp theo từng vị trí

4.4.1 Bật/tắt tổng & loại ad

4.4.2 Rule-show theo start / step (trong block fo hoặc ru)

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

5. Changelog phiên bản tài liệu

Bám theo CHANGELOG.md của SDK. Mỗi mục liệt kê đúng những gì BA / Ad Ops phải đổi trên Firebase Remote Config ở phiên bản đó.

1.1.0 — 2026-05-12

Thêm key Boolean mới (§2.1, §3.8):

• fo_refill_by_ad (mặc định true) — auto refill native ad sau end-of-video / sau click bottom-sheet.
• fo_logic_inter_splash_inc_impression (mặc định false) — chỉ FO user; cho phép Inter Splash overlap màn kế tiếp.
• fo_enable_open_ad_on_continue_bar (mặc định true) — bật/tắt App Open Ad khi resume từ thanh Continue.

Đổi schema fo_config_ad_splash / ru_config_ad_splash (§2.2, §3.2):

• logic thêm giá trị variant_3 → ánh xạ tới SplashAdVariant.NATIVE_DUAL (Native HF → Native standard, không có Inter fallback).
• Thêm trường top-level logic_reload_fallback (bool, mặc định false) — bật song song HF + Standard cho variant_3.
• variant_3 đòi hỏi partner đã cấp nativeSplash (ID Native standard) ở code-side. Cấu hình rủi ro skip-ad cao → BA phải align với PO trước khi bật.

Đổi schema inapp_ad_<tp> (§2.4, §3.6) — dual-shape:

• Schema mới gộp rule-show vào nested block fo / ru (mỗi block có layout, logic_load_ad, start, step).
• Thêm trường top-level: ad2id_enabled (bật/tắt thử ID Native highfloor), logic_reload_fallback (song song HF+Standard cho only_na).
• Giữ song song flat keys fo_layout / return_layout để SDK 1.0.0 còn sống trên user thật vẫn đọc đúng. Chỉ XOÁ flat keys khi tỷ lệ cài SDK 1.0.0 < 1%.
• SDK 1.1.0 có legacy adapter: nếu Firebase chỉ có flat keys (chưa migrate), SDK tự sinh fo/ru với defaults (logic_load_ad=na_then_in, start=1, step=2) → BA có thể release SDK trước, migrate JSON sau.
• Bỏ key cũ (nếu BA từng tạo trước đây): inapp_ad_rule_show_<tp> — đã gộp vào start/step trong nested block.

Đổi giá trị mặc định:

• Không có giá trị mặc định nào thay đổi ngược (back-compat). Mọi mặc định ở §2 giữ nguyên hành vi như 1.0.0 nếu BA không sửa Firebase.

Action item cho BA khi rollout 1.1.0:

1. Tạo 3 boolean mới (#7–#9 ở §2.1) trên Firebase với mặc định ở bảng.
2. Nếu muốn thử variant_3 ở splash → confirm code-side đã có nativeSplash rồi mới đổi logic JSON sang variant_3.
3. Cập nhật mỗi inapp_ad_<tp> sang JSON dual-shape ở §2.4 (giữ cả nested + flat).
4. Bấm Publish và verify bằng fo_allow_log_tester=true trên build QA.

1.0.0 — 2026-04-26

• Phiên bản đầu tiên của tài liệu.
• Schema gốc: fo_banner_splash, fo_hf_banner_splash, fo_enable_onboarding, fo_native_onboarding, fo_native_onboarding_2ID, fo_allow_log_tester, fo_onboarding_config, fo_config_ad_splash, ru_config_ad_splash, fo_config_ad_resume, inapp_ad_<tp> (schema flat — chỉ có fo_layout / return_layout).
• fo_config_ad_splash.logic hỗ trợ variant_1 (NATIVE_FIRST) và variant_2 (INTER_FIRST).