Skip to content

t1k:marketing:monetization:fb-instant-ads

FieldValue
Modulemonetization
Version1.49.21
Efforthigh
Tools—
/t1k:marketing:monetization:fb-instant-ads

Ads inside a Facebook/Messenger Instant Game (FBInstant SDK), served through Meta Audience Network and configured from the App Dashboard and Monetization Manager. This is not the native-app FAN path.

  • An Instant Game shows no ads, or getInterstitialAdAsync / getRewardedVideoAsync fails
  • Auditing or creating Instant Game placements (property, Ad Space, placement IDs)
  • Writing or reviewing the FBInstant ad integration

Not this skill: native-app FAN mediation (→ t1k-marketing-monetization-meta-audience-network), creating ad units on other networks (→ t1k-marketing-monetization-create-ad-unit-from-networks).

Step 1: Diagnose (read-only, always first)

Section titled “Step 1: Diagnose (read-only, always first)”

Nothing is created or changed until diagnosis is done. Read with the browser only (Claude in Chrome is acceptable). Checks, in order:

  1. App Dashboard (https://developers.facebook.com/apps/): the game’s App ID and mode.
  2. Monetization Manager Home: property table with Ad requests and Impressions per property.
  3. Property → Ad Space: placements with Status (Idle = not serving) and Placement ID.
  4. Mismatch check: every placement ID prefix must equal the game’s App ID (<APP_ID>_<number>). A different prefix means the placement belongs to another app, and the game gets no fill.

Report the readings as facts, then pick the branch:

FindingBranch
No property for this App IDStep 2 decides (reuse or create via Step 3)
Prefix ≠ App ID (placements live under another app’s property)Step 2 → new property via Step 3. A new placement in the SAME wrong property does not fix it
Requests > 0, impressions 0Audience Network Review checklist incomplete or Approval pending (Step 3 §2); not a code bug
Placements active, requests flat at zeroSDK integration (Step 4)

Procedure and exact labels: references/diagnose.md.

Step 2: Is this game already in Monetization Manager? (read-only)

Section titled “Step 2: Is this game already in Monetization Manager? (read-only)”

Run before any setup. Check three places, all read-only:

  • (a) Monetization Manager Home / Properties table: search by game name.
  • (b) Any placement whose ID prefix equals the game’s App ID (<APP_ID>_<number>).
  • (c) The App Dashboard: “Show ads in your game” → In-App Ads table. Read its placement rows.

Decision:

  • Already exists: the In-App Ads table lists placements with the game’s App ID prefix. The property exists. Reuse it. Do not create another.
  • Only a manual property, or nothing: the game appears only under a manually created property (Android or iOS platform, placement prefix of a different app ID), or not at all. Create a new property through the App Dashboard flow in Step 3 (“Show ads in your game” → “Go to Monetization Manager”). Never reuse or edit the old manual property.
  • Creating anything still needs the consent gates in Step 3.

Procedure: references/diagnose.md § “Already in Monetization Manager?”.

Section titled “Step 3: Setup in the App Dashboard (consent gates)”

Full click path: references/app-dashboard-setup.md. Summary:

  1. Use case “Launch an Instant Game on Facebook and Messenger” → Customize → “Add more to this use case” → “Show ads in your game” → + Add. This adds the “Audience Network” and “In-App Ads” sub-pages.
  2. “In-App Ads” → “Audience Network Review” checklist: onboarding (Instant Game Ads Placements, Audience Network Payment Account, Game Bundle), then Audience Network Approval.
  3. “Audience Network” → “Go to Monetization Manager” → “Add your first property”. The agent may prefill the property name. The human clicks Next, which accepts the Meta Audience Network Policy and Terms.
  4. ”+ Create Ad Space”: name, Platform = Games, and “Describe the steps we need to follow to find the ad”. This text is reviewer-facing. Ask the user for the real game flow and never invent it. Optional .mov/.mp4 upload.
  5. Create placement: name, Ad Space, display format, Chained Ads (default on), “Create placement”. Create Interstitial and Rewarded video only: the form still offers Rewarded interstitial (deprecated for Instant Games in 2025) and Banner (phasing out, no longer served after 2027-03-31). New placements show “Ready to publish”; IDs are <APP_ID>_<number>.
  6. Re-read the In-App Ads checklist. Once placements exist, the onboarding items can turn green on their own when the business already has a payout account. Only Audience Network Approval is Meta’s review; expect ADS_NO_FILL until it passes.

Consent gates

  • Terms acceptance is a human action. The agent never clicks it.
  • Each create action (property, Ad Space, placement) runs only on explicit user request. Name the exact object and display format back to the user first.
  • Do not use Monetization Manager “Create property” for an Instant Game. It offers only iOS and Android. No delete or archive of a property is exposed.

Rules, snippet, and error table: references/sdk-integration.md and references/error-codes.md.

  • Preload after FBInstant.startGameAsync() resolves, and again after each show.
  • One in-flight load per placement. Failed loads back off exponentially, starting at 30 s or more.
  • Never load on show. If the ad is not ready, skip the placement.
  • Grant a reward only when showAsync() resolves.
  • Manual property creation does not produce a working Instant Game property. Use the App Dashboard flow in Step 3.
  • A placement ID prefix that differs from the App ID fails silently as no fill. Check it before debugging code.
  • The “U.S. user data restriction” notice in Monetization Manager is unrelated to ad serving. Do not chase it as the cause of zero fill.
  • The Integration → Testing page is device-based (AAID/IDFA) for the native SDK. It is not the Instant Games test path.
  • ADS_FREQUENT_LOAD is caused by load loops. Stop the loop and back off. Do not retry tighter. The block lasts the whole session: fully close and reopen the game before re-testing.
  • Ads never serve on a desktop browser (CLIENT_UNSUPPORTED_OPERATION). Test the build uploaded to Web Hosting and pushed to Testing, inside the Facebook/Messenger mobile app, with an account that has a role on the app.
  • Placeholders only in docs and code: <APP_ID>, <PLACEMENT_ID>, <BUSINESS_ID>. Never paste real IDs, business IDs, or tokens into the skill, a PR, or a chat transcript.