Skip to content

t1k:marketing:monetization:max-bid-floor

FieldValue
Modulemonetization
Version1.49.21
Efforthigh
Tools—
/t1k:marketing:monetization:max-bid-floor

Push the floor Worker’s per-country ladder onto a game’s bidding MAX ad units, for INTER and REWARD — and get those units configured in the first place, by cloning the auto-bidding unit’s networks onto them.

⚠️ Money-risk, and asymmetric. A floor too low costs a little revenue per impression. A floor too high, or a floor on the wrong unit, costs all of it — the request simply does not fill, and the symptom looks like weak demand rather than a bad write. Read ad-network-mcp-write-safety.md (../../../core/rules/ad-network-mcp-write-safety.md) before any apply.

THE ONE RULE — never touch the auto-bidding ad unit

Section titled “THE ONE RULE — never touch the auto-bidding ad unit”

Every game here has one auto-bidding ad unit per format (no numeric suffix: GameB_Inter_AND) plus bidding rungs (_1 … _7).

The auto-bidding unit is what the shipped game is serving from right now, and it is the fallback when every bidding rung fails to fill. Putting a floor on it caps the one path that must always be able to serve — and if that floor is above market, the app’s ad revenue goes to zero with no error anywhere.

This skill never writes to it. The refusal is enforced inside the API client (createClient, protectedIds in scripts/max-floors-core.cjs), not by a caller or a flag: references/incident-history.md.

parity reads it, because the rungs are defined relative to it. Reading is the only interaction.

If a floor genuinely needs to change on the auto-bidding unit, do it by hand in the MAX dashboard as a separate, deliberate decision.

  • Applying the floor Worker’s grid to a game’s bidding rungs, per country
  • Checking whether the rungs actually mirror the auto-bidding unit’s networks
  • Auditing which countries currently carry a floor on which rung
  • Re-syncing after the Worker publishes a new grid version

Not for: creating ad units (the Management API refuses more than one per app×platform×format — make them in the UI); waterfall CPM lines (bid_floors is not a waterfall); CloudX floors (→ t1k-marketing-monetization-cloudx-price-floor); MAX SDK or API reference (→ t1k-marketing-monetization-applovin-max, which owns the endpoint contract this skill calls).

The arithmetic and the reads are fully specified before the run starts; the decisions are not (routing SSOT: rules/orchestration-rules.md § “Task-Type → Agent Routing”):

StepAgent
Run parity and report which rungs differ from the auto-bidding unitt1k-fact-fetcher
Run plan and tabulate the before → after difft1k-metrics-reporter
Reconcile live floors against the Worker grid and report driftt1k-data-verifier
Decide whether a floor level is right, or why a rung is not fillingstays on a reasoning tier — t1k-debugger
replicatenever delegated — it changes which networks serve on a live unit
applynever delegated — it moves money and needs the operator’s confirmation
restorenever delegated — it overwrites live floors from a file

How the system actually works — auto first, then the 2 rungs above its price

Section titled “How the system actually works — auto first, then the 2 rungs above its price”

The game loads the auto-bidding unit first, reads its revealed price, then requests only the 1-3 rungs (design: 2) whose floors sit immediately above that price; the highest fill wins. It does NOT load all 7 rungs per request. Verified in the client source (The1Studio/ThirdPartyServices master dd02faab, 2026-10-09, RevealedPriceProbeCycle + FloorGrid.Resolve). The auto-bidding unit is still the guaranteed fill, so an aggressive top rung is safe, and a floor on the auto-bidding unit would be catastrophic rather than merely suboptimal.

  • Rung order, and why uplift is never “rung eCPM minus the auto unit average”: references/serving-model.md.

Analysis consequences (uplift counterfactual, rung 1 counts, no probe on non-exact precision), the README.md/R16 discrepancy, and why an unfloored rung is useless rather than dangerous: references/serving-model.md.

Re-fitting once floors are live — fit on the auto unit only

Section titled “Re-fitting once floors are live — fit on the auto unit only”

Refit on the auto-bidding unit’s impressions only (no _N suffix). Rung impressions are recorded at floor-raised prices, so a mixed fit ratchets each ladder up (owner decision, 2026-11-03).

When the fitter refuses a slice — donor-app derivation

Section titled “When the fitter refuses a slice — donor-app derivation”

Below the gates (>= 8 impressions per user, >= 100 qualifying users) there are two options: the pooled grid (grid_scope: pooled), or a same-archetype donor’s percentile position, matched per country, never a raw value. Procedure: references/refit-and-donor-policy.md.

One ad unit per rung; the country lives in bid_floors, not in the name. bid_floors is not a ladder — each unit holds one floor per country, and the ladder is expressed across ad units. Full diagram and why it forces a read-modify-write: references/ad-unit-conventions.md.

⚠️ Two naming conventions exist, and they are not interchangeable. packages/floor-schema puts the country in the name; the live account (<Game>_<Format>_<PLAT>[_<n>]) does not, and this skill implements the live account. Detail: references/ad-unit-conventions.md.

Terminal window
read -rs MAX_MANAGEMENT_KEY && export MAX_MANAGEMENT_KEY

The Management Key (Account → General → Keys), not the Reporting Key. It is account-wide write access. Never write it to a tracked file.

Terminal window
bun scripts/max-floors.cjs parity --map apps/<game>.json

Asserts two things and decides nothing:

  • every bidding rung carries the same networks, enabled the same way, as the auto-bidding unit;
  • the auto-bidding unit is unfloored.

A rung missing networks has no demand to floor. It will not fill, the ladder degrades to the fallback, and the symptom reads as “our floors are too high” — which invites lowering floors in response to a config bug. Fix parity first.

Exits non-zero on any finding, so it can gate apply in a script.

Scope it with --package, --platform, or --all plus --yes; the command listing and the JSON audit output are in references/workflow-commands.md.

2. replicate — clone the auto-bidding unit’s networks onto empty rungs

Section titled “2. replicate — clone the auto-bidding unit’s networks onto empty rungs”

RUNGS ONLY. The auto-bidding unit is never written to — not its floors, not its networks. It is the source the config is copied FROM, and it is only ever read. It is what the shipped game is serving from right now and the fallback when every rung fails to fill: a floor on it caps the one path that must always serve, and a network change on it alters live serving behaviour. If either genuinely needs to change, do it by hand in the MAX dashboard as a separate, deliberate decision.

replicate --all does the same for every app with an auto unit and at least one rung, discovering units by naming convention, for the apps that have no map. Always --dry-run first: it prints each change, the source unit, and the confirm phrase for that exact scope. Enforcement detail and commands: references/workflow-commands.md.

Key behaviours: a freshly created MAX ad unit ships with only the two AppLovin defaults and has no third-party demand; replicate copies the auto-bidding unit’s bidding networks onto every rung still in that state. If the source is in that state too, the group is refused (!! N group(s) NOT queued) rather than queued — fix the auto unit by hand in the dashboard first.

Per format, always: interstitial rungs clone the interstitial auto unit, rewarded rungs the rewarded one; waterfall networks are never cloned; configured rungs are skipped unless --include-configured.

Full rationale and the evidence for each: references/network-replication.md.

Terminal window
bun scripts/max-floors.cjs plan --map apps/<game>.json --country US
bun scripts/max-floors.cjs plan --map apps/<game>.json --json /tmp/plan.json # all countries

Prints before → after per ad unit per country and writes nothing. It also prints the exact --confirm phrase apply will demand.

plan --drift is the health question: it exits 2 on any drift from the published grid, and counts a permanently-BLOCKED rung as drift (a clearing decision for a human). The command is in references/workflow-commands.md.

**Smoke ONE unit, one country, verify, then widen.** Per `rules/preview-first-batch.md`. Override: the user explicitly says to skip it.

Smoke one unit, one country first: run apply without --confirm (every read and gate runs, no POST is sent, and it prints the diff and the exact phrase for that scope), then re-run with that phrase and --expect-version, then the whole run. Command listing: references/workflow-commands.md.

--dry-run runs every read and every gate and sends no POST.

The phrase binds the scope — it carries the --only target and the country set, so a phrase from a whole-run plan cannot unlock an --only smoke. Run apply without --confirm first: it performs every read and gate, sends no POST, prints the diff, and then prints the exact phrase and --expect-version for that scope. --expect-version <v> makes apply refuse if the Worker grid was republished since your plan, so you cannot confirm one set of numbers and write another. Each floor POST also re-reads its unit first and is refused if the floors changed since the plan. Why the gates exist: references/incident-history.md § snapshot/restore and § write races.

There is no undo on this API and MAX keeps no version history. The writing commands take the snapshot for you:

The table of pre-images (apply, replicate, replicate --all) is in references/workflow-commands.md.

The writing commands print their own restore line after each run (apply for floors only, replicate for floors plus networks). Commands: references/workflow-commands.md.

--networks is a merge, not a restore, and never replays AdMob: it cannot remove a network added since the snapshot, and says so per unit; an AdMob entry is skipped because RefreshAdmobIds may have rotated its id since the snapshot. Every pre-image records bid_floors and the raw ad_network_settings for that reason. Detail: references/incident-history.md.

6. collapse — one group per country on a rung

Section titled “6. collapse — one group per country on a rung”

apply refuses a country that sits in several overlapping groups. collapse --map apps/<game>.json --rung 1 --format INTER dry-runs the de-stack (middle price per stack, two-deep flagged REVIEW) and prints a --expect-state fingerprint and a --confirm phrase; the write needs both. Usage, guards and the refit limit: references/collapse.md.

Every one was learned from a live account. The five that bite hardest:

  • bid_floors is replaced WHOLESALE on POST, never merged per country — so every write is read-modify-write, and an absent key is not an empty one.
  • Verify on a re-GET, never on the POST echo, and ask for bid_floors explicitly or the read comes back without it.
  • Seven rungs per format is a fixed budget — MAX refuses a second ad unit for an app x platform x format that already has one, so a wasted slot is permanent.
  • A floor must be > 0 and <= 500, and a country covered by several overlapping groups is refused rather than guessed at.
  • MAX keeps ONE group per price per ad unit and silently drops the rest — two countries at the same cent means one never lands. Observed 2026-09-11, not documented by AppLovin; plan/apply now refuse it. Remedy is a human decision.

Full list — rate limits, EXCLUDE groups, pooled-grid scope, the kill switch, retry policy, identity fields a POST body must carry: references/incident-history.md.

One refit cycle, step by step (fetch, fit, plan, apply, publish, verify): references/refit-runbook.md.

One JSON file per game under apps/ (apps/help-monster-3.json ships). Validation rejects rather than repairs; shape and checks: references/app-map-and-remote-config.md.

Worker-free delivery: a fitted grid plus the app map become Remote Config JSON with real 16-hex MAX unit ids. Read-only toward MAX.

Terminal window
bun scripts/max-rc-grid.cjs --map apps/<game>.json --grid grids/<fit>.json --out <file> --verify

--verify needs MAX_MANAGEMENT_KEY; without it the output says UNVERIFIED-AGAINST-MAX. Rollback, kill switch and publishing: references/app-map-and-remote-config.md.

  • t1k-marketing-monetization-applovin-max — the Management API contract, rate limits, and ad-unit creation. Owns the endpoint reference; this skill calls it.
  • t1k-marketing-monetization-cloudx-price-floor — the same job for CloudX First Look.
  • t1k-marketing-monetization-mediation-strategy — whether these floors are the right strategy, as opposed to how to apply them.
  • rules/ad-network-mcp-write-safety.md — the money-risk guardrail this skill obeys.