t1k:marketing:monetization:fb-instant-ads
| Field | Value |
|---|---|
| Module | monetization |
| Version | 1.49.21 |
| Effort | high |
| Tools | — |
How to invoke
Section titled “How to invoke”/t1k:marketing:monetization:fb-instant-adsFacebook Instant Games Ads
Section titled “Facebook Instant Games 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.
When to Use
Section titled “When to Use”- An Instant Game shows no ads, or
getInterstitialAdAsync/getRewardedVideoAsyncfails - 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:
- App Dashboard (
https://developers.facebook.com/apps/): the game’s App ID and mode. - Monetization Manager Home: property table with Ad requests and Impressions per property.
- Property → Ad Space: placements with Status (
Idle= not serving) and Placement ID. - 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:
| Finding | Branch |
|---|---|
| No property for this App ID | Step 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 0 | Audience Network Review checklist incomplete or Approval pending (Step 3 §2); not a code bug |
| Placements active, requests flat at zero | SDK 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?”.
Step 3: Setup in the App Dashboard (consent gates)
Section titled “Step 3: Setup in the App Dashboard (consent gates)”Full click path: references/app-dashboard-setup.md. Summary:
- 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.
- “In-App Ads” → “Audience Network Review” checklist: onboarding (Instant Game Ads Placements, Audience Network Payment Account, Game Bundle), then Audience Network Approval.
- “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.
- ”+ 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.
- 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>. - 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_FILLuntil 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.
Step 4: SDK integration
Section titled “Step 4: SDK integration”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.
Hard rules
Section titled “Hard rules”- 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_LOADis 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.