thomaslimitedthomaslimited/game-shipping-skills/skills/game-ads/SKILL.md

game-ads

Skill1 starsChanged 52 days agoMITView on GitHub

Add or fix advertising in a mobile game or app — AdMob, Google Ad Manager, and mediation through AppLovin MAX, Unity LevelPlay/ironSource or Liftoff. Covers banner, interstitial, rewarded, rewarded interstitial, app open and native formats, placement and frequency design, eCPM and fill, GDPR/DMA consent with the UMP SDK, Apple ATT, COPPA and the Google Play Families ads policy, test ad units, and how ads coexist with a remove-ads purchase. Use when integrating an ad SDK, choosing formats, diagnosing low revenue or no fill, or checking ad policy compliance for a kids' app.

In this repository4 other files it gives its agents.
- app-authSkill
- game-iapSkill
- store-listingSkill
- store-releaseSkill

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
If you sell a premium unlock, a remove-ads entitlement is mandatory, and buying it must remove ads instantly without a restart.
line 25
Distinctive:
Start with AdMob alone. Add mediation when you have enough daily impressions that a second network's bid actually competes — below roughly …
line 44
Distinctive:
Test ad unit IDs only, until release: Never hit production units during development — Google treats self-clicking as invalid traffic and …
line 53
Very specific:
Never set both to true — the child-directed setting wins, and Google applies the most conservative treatment.
line 74

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

Game Ads

Ads are a product decision before they are an integration. The SDK takes a day; the placement design decides whether the game survives its own monetization.

Decide first

1. Should this game have ads at all?

Signal	Lean
Premium unlock already converts, small audience, kids' game	No ads. Ads in a paid kids' game are a policy minefield and a review magnet, and cannibalize the unlock.
Large free audience, short sessions, low intent to pay	Ads, mostly rewarded
Mid-size audience, some payers	Hybrid: rewarded ads + a "remove ads" or premium purchase

If you sell a premium unlock, a remove-ads entitlement is mandatory, and buying it must remove ads instantly without a restart. See the game-iap skill for the entitlement plumbing.

2. Which formats?

Format	Player cost	Use when	Avoid when
Rewarded	Opt-in, positive	extra life, double coins, hint, skip a wait	never a reason to avoid it — this is the format to start with
Rewarded interstitial	Opt-out with a countdown	natural transition where a reward makes sense	kids' apps
Interstitial	Forced	between levels, after a run ends	during gameplay, on app start, before the first interaction
Banner	Persistent screen space	menus, low-attention screens	over gameplay controls; anchored banners eat safe-area space on notched phones
App open	Forced at launch/resume	resume after a long background	cold start before your own loading screen; this is a top rejection cause
Native	Blends in	shop lists, level select	anywhere it could be mistaken for a game button — that is a policy violation

Hard rule: never place an ad where a mis-tap is likely. Accidental clicks get your AdMob account limited or disabled, and that is far more expensive than the lost impression.

3. Direct AdMob or mediation?

Start with AdMob alone. Add mediation when you have enough daily impressions that a second network's bid actually competes — below roughly 50k daily impressions the extra SDKs, consent surface and crash risk cost more than the eCPM lift. Details: references/mediation-and-networks.md

Integration order that avoids rework

Consent first. UMP SDK, before any ad request. If you bolt consent on later you will have shipped requests that had no legal basis, and the fix is a forced update.
Test ad unit IDs only, until release. Never hit production units during development — Google treats self-clicking as invalid traffic and suspends accounts without much dialogue.
One format end to end (rewarded), including the reward-not-granted path.
Then the rest.

Android specifics and code order: references/admob-integration.md

Consent, privacy and children

This is where ads go wrong legally rather than technically. Full detail in references/consent-and-kids.md. The load-bearing facts:

UMP SDK call order, every launch: getConsentInformation → requestConsentInfoUpdate → loadAndShowConsentFormIfRequired → check canRequestAds() before initializing the ads SDK / requesting an ad. Also expose a persistent "Privacy options" entry point when getPrivacyOptionsRequirementStatus() says it is required.
iOS: App Tracking Transparency is separate from UMP consent. No IDFA without ATT authorization, and the ATT prompt must follow your own explanation screen, not precede it.
Child-directed: AdMob's setTagForChildDirectedTreatment(TRUE) disables interest-based ads and remarketing and stops transmission of the advertising ID. setTagForUnderAgeOfConsent(TRUE) disables personalized ads for under-age-of-consent users. Never set both to true — the child-directed setting wins, and Google applies the most conservative treatment. Also set setMaxAdContentRating("G") for a children's game.
Google Play Families policy: apps whose target audience includes children may only use self-certified ad SDKs from Google's published list (AdMob/Ad Manager, Unity Ads, ironSource, Vungle and about ten others). A non-certified SDK may only serve users you have established are adults via a neutral age screen. Ads must be age-appropriate, and the Play Console target-audience and ads declarations must match what the app actually does.
Apple: the Kids Category forbids behavioural advertising outright, and as of 2026 Apple's age-rating system (4+/9+/13+/16+/18+) plus the Declared Age Range API change what you may serve to whom in several jurisdictions.

Diagnosing revenue problems

Symptom	First checks
No fill / no ads at all	New ad unit (can take hours to serve), app not yet linked to a store listing, consent not obtained so `canRequestAds()` is false, test device flag left on, ad unit ID typo
eCPM collapsed	Geo mix shifted, consent rate dropped (non-personalized pays far less), personalization disabled by a tag you set, seasonal January drop
Revenue fine, retention falling	Interstitial frequency too high — cap it and measure D1/D7, not just ARPDAU
AdMob account warnings	Invalid traffic from your own testing, or a placement that invites mis-taps

Metric that matters: ARPDAU held against D7 retention. Ads that raise ARPDAU while cutting retention lose money over a month. references/placement-and-economics.md

Sources

Verified 2026-09-24:

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free