/flame-harness-admob

name: flame-harness-admob
description: Phase 7 — analyze the game, decide a rewarded-ad strategy, guide manual AdMob ad-unit creation, and inject google_mobile_ads + ATT/UMP consent code.
argument-hint: ""
allowed-tools: [Agent, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion]

flame-harness-admob

Phase 7 of the flutter-flame-harness pipeline. Analyzes the game's loop, decides where rewarded ads fit naturally, guides the user through manual ad-unit creation in the AdMob console, then injects `google_mobile_ads`, iOS ATT, and UMP consent code.

All file schemas (`config.md`, `state.md`, `pipeline-log.md`) and the phase transition table are defined in `docs/harness-protocol.md` — that document is the single source of truth (§1 for `config.md` including the `admob:` block; §2 for `state.md`; §6 for log schemas; §7 for the `admob → build` transition and the `skip_admob` branch rule). Do not redefine schemas here.

---

Input — Read Inputs

Before any action, load:

1. `docs/harness/config.md` — extract `app_slug`, `app_name`, and `skip_admob` (bool). 2. `docs/harness/state.md` — confirm `next_role: admob`. 3. PRD at `docs/harness/prd.md` — read the game loop, monetization intent, and any explicit ad placement requests.

---

Skip Flag — skip_admob Handling

Check `skip_admob` from `docs/harness/config.md` immediately after loading inputs.

If `skip_admob: true`:

1. Write `docs/harness/config.md` with `admob.enabled: false` (per protocol §1 `admob:` block). 2. Write `docs/harness/state.md` with:

   status: running
   current_phase: admob
   next_role: build
   updated_at: "<ISO-8601 UTC now>"

3. Append to `docs/harness/pipeline-log.md` (per protocol §6):

   | <ISO-8601 UTC now> | complete | admob | skip_admob=true; AdMob skipped; next: build |

4. Exit immediately. Do not ask questions, do not inject code.

---

Strategy — Rewarded Ad Placement

Read the PRD and game loop carefully. The goal is rewarded ads that feel like a natural reward mechanic, not an interruption.

Rewarded Ad Placement Principles

• **Revive / continue**: Offer a rewarded ad when the player dies or fails — "Watch an ad to

continue?". This is the highest-converting rewarded placement for Flame games.

• **Double coins / bonus**: After a session ends, offer a rewarded ad to double the score or

coins earned.

• **Extra life / shield**: Mid-game offer for an extra life when health is critical.
• **Unlock hint / skip**: In puzzle games, offer a rewarded ad to reveal a hint or skip a level.

Choose placements that match the PRD's described game loop. Document the chosen placements explicitly — a fresh Claude running `flame-harness-generator` must know exactly where to add the `RewardedAdHelper.show()` call.

No Intrusive Interstitials

Do **not** add interstitial ads unless the PRD explicitly requests them. Interstitials between levels or at session start hurt retention and risk App Store policy violations. Rewarded ads are opt-in and always preferred.

Banner Ads (conditional)

Add a banner ad only if the PRD explicitly requests one. If a banner is used, apply the SafeArea banner gap pattern: wrap the game canvas in a `Column` with a `SafeArea`-padded `BannerAdWidget` at the bottom so the ad never overlaps game content.

---

Manual Unit Creation — AdMob Console

Google's API cannot create AdMob ad units programmatically. The user must create them manually in the AdMob console. Follow these steps:

Step 1 — Collect App IDs

Use `AskUserQuestion` to ask the user:

> "Please open the AdMob console (https://admob.google.com) and: > 1. Add your iOS app → copy the **iOS App ID** (format: `ca-app-pub-XXXX~YYYY`). > 2. Add your Android app → copy the **Android App ID** (format: `ca-app-pub-XXXX~ZZZZ`). > > Paste both IDs here. If you haven't done this yet, type 'defer' and I'll pause."

If the user types `defer` or says they haven't done it yet, write `docs/harness/state.md` with:

status: paused
current_phase: admob
next_role: admob
pause_reason: manual_action
updated_at: "<ISO-8601 UTC now>"

Then stop. The harness will resume when the user runs `flame-harness-resume`.

Step 2 — Collect Ad Unit IDs

For each rewarded placement identified in the Strategy section, use `AskUserQuestion` to ask the user to create a rewarded ad unit in the AdMob console and paste back both the iOS and Android unit IDs. Example for a "revive" unit:

> "In the AdMob console, under your app → Ad units → Add ad unit → Rewarded: > - Unit name: `<app_slug>_rewarded_revive` > - Copy the **iOS unit ID** (format: `ca-app-pub-XXXX/IIII`) and the > **Android unit ID** (format: `ca-app-pub-XXXX/AAAA`). > > Paste both here. Type 'defer' to pause."

Again apply the same `pause_reason: manual_action` pause if the user defers.

Step 3 — Write config.md admob block

Once all IDs are collected, write the `admob:` block in `docs/harness/config.md` (per protocol §1):

admob:
  enabled: true
  ios_app_id: "ca-app-pub-XXXX~YYYY"
  android_app_id: "ca-app-pub-XXXX~ZZZZ"
  ad_units:
    - key: rewarded_revive
      ios_id: "ca-app-pub-XXXX/IIII"
      android_id: "ca-app-pub-XXXX/AAAA"
      format: rewarded
    # add one entry per placement

---

Code Injection

After collecting IDs, inject the integration code into the Flutter project at `<projects-dir>/<app_slug>/`.

1. pubspec.yaml — Add Dependencies

dependencies:
  google_mobile_ads: ^5.1.0
  app_tracking_transparency: ^2.0.6

Run `flutter pub get` after editing.

2. iOS ATT Permission — Info.plist (localize for EVERY configured locale)

Read `default_language` from `docs/harness/config.md`. The configured App Store localizations are `default_language` **plus English when `default_language ≠ en`** — the same set as the l10n Hard Gate. The ATT prompt string must exist in **every** one of them, or you get a repeat rejection: a reviewer (or user) in another locale sees a foreign-lan