From 6fea4b864327077ad68a9ba3065161f6dfb41797 Mon Sep 17 00:00:00 2001 From: Nick Yang Date: Wed, 12 Aug 2026 09:27:52 +0800 Subject: [PATCH] Setup shapes: correct parallel to Trusted Arbiter, add standalone, per-format shape matrix The coexist playbook described parallel as a placement/traffic split; the supported mechanism is Trusted Arbiter (docs pages exist on Android, iOS, Unity, React Native). Rework the guidance so the repo orchestrates and docs carry the substance: - coexist-mediation.md: three named shapes (first look / parallel via Trusted Arbiter / standalone per-format split), each pointing at its live docs page; mode list is discovered from llms.txt (open set, availability varies by platform); shape is chosen per ad format, recorded as a format -> shape matrix; decision-point guardrail (post-bid and publisher-controlled comparison frames are unsupported - stop and surface); AdMob note: estimated pricing is dashboard-side, never encode an estimated eCPM as a bid in app code. - cloudx-integrate SKILL.md: Plan phase establishes the matrix by enumerating available modes live; Audit checks each format against its shape's docs page; Report states the matrix. - cloudx-audit SKILL.md: coexistence step reconstructs the matrix and audits per shape. - playbook-index.md: setup-shape intent signals route to the playbook. - doc-map.md: fixed first-look/trusted-arbiter rows replaced by the open setup-mode pattern. verify.sh green. Co-Authored-By: Claude Fable 5 --- .agents/skills/cloudx-audit/SKILL.md | 9 ++- .agents/skills/cloudx-integrate/SKILL.md | 32 ++++++--- .../cloudx-integrate/references/doc-map.md | 3 +- .../references/playbook-index.md | 1 + playbooks/coexist-mediation.md | 67 +++++++++++++------ 5 files changed, 78 insertions(+), 34 deletions(-) diff --git a/.agents/skills/cloudx-audit/SKILL.md b/.agents/skills/cloudx-audit/SKILL.md index ffdc5b0..6c7a9e4 100644 --- a/.agents/skills/cloudx-audit/SKILL.md +++ b/.agents/skills/cloudx-audit/SKILL.md @@ -35,9 +35,12 @@ and still be wrong or incomplete; the platform changelog page shows what changed - Each ad format: creation, listeners, readiness checks, show requirements, lifecycle/destroy handling per the current docs page. - Removed/renamed APIs still referenced (changelog is the evidence). -4. **Coexistence** — if another mediation stack is present: both init paths - intact, fallback or first-look wiring per the platform's first-look docs - page, no circular loading, per `coexist-mediation.md`. +4. **Coexistence** — if another mediation stack is present: reconstruct the + format → shape matrix from the code (first look / trusted arbiter / + standalone split, per format) and audit each format against its shape's + docs page — both init paths intact, fallback wiring per + `integrations/first-look.md`, arbitration wiring per `trusted-arbiter.md`, + no circular loading, per `coexist-mediation.md`. 5. **Privacy** — CMP writes IAB consent strings before ads load; no usage of privacy APIs the changelog marks removed; consent forwarded to any coexisting mediation SDK (per `consent-and-cmp.md`). diff --git a/.agents/skills/cloudx-integrate/SKILL.md b/.agents/skills/cloudx-integrate/SKILL.md index 19e7240..c5cc77c 100644 --- a/.agents/skills/cloudx-integrate/SKILL.md +++ b/.agents/skills/cloudx-integrate/SKILL.md @@ -57,14 +57,24 @@ Identify, from the project's files: publisher which networks are enabled (or read their config via the CloudX MCP/CLI `config/show` if they have it set up). Never guess and never default to "all". -3. Fetch the platform's integration overview page, the pages for each ad format +3. If an existing mediation stack is present (or the user named a setup shape + — first look, parallel/Trusted Arbiter, standalone), establish the **setup + shape per ad format**. The platform's available modes are the pages under + `en//integrations/` plus the `trusted-arbiter` family in + `llms.txt` — enumerate them live; never assume the set. Ask the publisher + format by format if unstated, presenting each mode's own one-line + description from the index. Record the format → shape matrix; + `coexist-mediation.md` holds the decision procedure and the invariants. +4. Fetch the platform's integration overview page, the pages for each ad format the user wants (default: ask, or start with the formats the app already - shows), and the adapter overview page for every network in the adapter set. - `references/doc-map.md` explains which page stems answer which questions. -4. Read the playbooks selected in Detect. -5. Present a short plan: dependencies to add, files to create/modify, formats to - implement, playbook considerations. Confirm with the user if anything is - ambiguous (formats, networks, coexistence vs replacement intent). + shows), the docs page for every setup shape in the matrix, and the adapter + overview page for every network in the adapter set. `references/doc-map.md` + explains which page stems answer which questions. +5. Read the playbooks selected in Detect. +6. Present a short plan: dependencies to add, files to create/modify, formats to + implement with each format's setup shape, playbook considerations. Confirm + with the user if anything is ambiguous (formats, networks, setup shape, + coexistence vs replacement intent). ### Phase 3 — Integrate @@ -111,7 +121,8 @@ pages if uncertain): config. - If the app has an existing mediation stack: its code paths are untouched and still reachable (coexistence), or fully removed (migration) — per the intent - established in Detect. + established in Detect — and each format's wiring matches its row in the + setup-shape matrix, as that shape's docs page specifies. - Privacy: a CMP writes IAB consent strings before ads load, per the docs privacy guidance and the `consent-and-cmp` playbook if selected. - No placeholder credentials silently left behind — every placeholder is listed @@ -119,8 +130,9 @@ pages if uncertain): ### Phase 6 — Report -Summarize: files changed (with paths), formats implemented, networks/adapters -enabled, playbooks applied, build result, and required follow-ups (replace +Summarize: files changed (with paths), formats implemented (with each format's +setup shape when a mediator coexists), networks/adapters enabled, playbooks +applied, build result, and required follow-ups (replace placeholder app key / ad unit IDs, register the app's bundle ID in the CloudX dashboard, CMP configuration). Link the docs pages you used. diff --git a/.agents/skills/cloudx-integrate/references/doc-map.md b/.agents/skills/cloudx-integrate/references/doc-map.md index a5a1e69..566835f 100644 --- a/.agents/skills/cloudx-integrate/references/doc-map.md +++ b/.agents/skills/cloudx-integrate/references/doc-map.md @@ -15,8 +15,7 @@ wrong and must be updated (CI checks this). | `en//integration.md` | Always, first. Setup, current version + dependency coordinates, initialization, core features. | | `en//ad-formats/.md` | Per ad format you implement (`banner-mrec`, `interstitial`, `rewarded`, `app-open`, `native`). Flutter: formats are covered in the integration overview. | | `en//adapters//overview.md` | Per bidder network in the adapter set (Android/iOS). Unity uses `en/unity/adapters/.md`. Lists supported formats and the dependency — and may carry required extra steps (additional Maven repositories, manifest/Info.plist entries, SDK-track choices, native asset requirements). Apply the whole page, not just the coordinate. | -| `en//integrations/first-look.md` | Publisher keeps an existing mediation stack and tries CloudX first with fallback (Android/iOS today). Pairs with the `coexist-*` playbooks. | -| `en//trusted-arbiter.md` | Publisher wants CloudX bid comparison against third-party bids. | +| `en//integrations/.md` and `en//trusted-arbiter.md` | The platform's available **setup modes** for running CloudX alongside an existing mediation stack (first look, trusted arbiter, …). The set is open and varies by platform — enumerate what llms.txt actually lists, then fetch the page for every shape in the format → shape matrix. Pairs with `coexist-mediation.md`. | | `en//changelog.md` | Diagnosing behavior differences between SDK versions, or confirming when an API changed. | | `en//connectors//overview.md` | Revenue-connector setup (e.g. AppsFlyer; Android/iOS). | diff --git a/.agents/skills/cloudx-integrate/references/playbook-index.md b/.agents/skills/cloudx-integrate/references/playbook-index.md index 30c46eb..c615abd 100644 --- a/.agents/skills/cloudx-integrate/references/playbook-index.md +++ b/.agents/skills/cloudx-integrate/references/playbook-index.md @@ -8,6 +8,7 @@ repository root. |---|---| | Any existing mediation SDK present — AppLovin MAX (`com.applovin` deps, `applovin.sdk.key` manifest entry, `AppLovinSdk`/`MAX` symbols, `AppLovinSDK` pod), LevelPlay/ironSource (`com.ironsource`/`com.unity3d.mediation` deps, `IronSource`/`LevelPlay` symbols, `IronSourceSDK` pod), Google AdMob/Ad Manager (`com.google.android.gms.ads.APPLICATION_ID` manifest entry, `GADApplicationIdentifier` in Info.plist, Google Mobile Ads symbols), or another mediator | `coexist-mediation.md` — note which mediator was detected; the playbook is mediator-agnostic and instructs looking up the mediator's own current APIs live | | User intent is *replace* an existing mediation stack (not add alongside) | `migrate-from-mediation.md` | +| User names a setup shape or mechanism — "first look", "parallel", "Trusted Arbiter"/"TPA", "standalone"/"full platform" — or asks about post-bid arrangements | `coexist-mediation.md` — note the requested shape; its setup-shapes section maps each shape to the right docs page and holds the decision-point guardrail | | CMP present: UMP, Usercentrics, Sourcepoint, OneTrust, Didomi artifacts; `IABTCF_`/`IABGPP_`/`IABUSPrivacy_` reads/writes | `consent-and-cmp.md` | | Android project at all (always load for Android): Groovy vs KTS DSL, `libs.versions.toml`, `minifyEnabled true` | `android-build-variants.md` | | iOS project at all (always load for iOS): `Podfile` vs `Package.swift`, `use_frameworks!`, static/dynamic linking | `ios-dependency-managers.md` | diff --git a/playbooks/coexist-mediation.md b/playbooks/coexist-mediation.md index d5975d6..095205c 100644 --- a/playbooks/coexist-mediation.md +++ b/playbooks/coexist-mediation.md @@ -1,7 +1,7 @@ --- applies_to: [android, ios, unity, react-native, flutter] -signals: ["any existing mediation SDK detected: AppLovin MAX, LevelPlay/ironSource, Google AdMob/Ad Manager, or another mediator", "publisher wants CloudX alongside existing monetization"] -last_verified: 2026-08-03 +signals: ["any existing mediation SDK detected: AppLovin MAX, LevelPlay/ironSource, Google AdMob/Ad Manager, or another mediator", "publisher wants CloudX alongside existing monetization", "publisher names a setup shape: first look, parallel, Trusted Arbiter/TPA, standalone/full platform, or asks about post-bid"] +last_verified: 2026-08-12 --- # Coexisting with an existing mediation stack @@ -20,20 +20,44 @@ privacy APIs from memory.** Mediator SDKs move as fast as CloudX does; look up the detected mediator's current documentation live before touching its code paths. -## The two engagement shapes - -Publishers with an existing mediator almost never remove it on day one. The -motion is one of: - -- **First look:** CloudX gets the first chance at an impression; on no-fill, - the existing mediator's placement serves as before. Per-placement wiring — - the platform's first-look docs page covers it. -- **Parallel:** both stacks run live on different placements (or a traffic - split), and the publisher compares revenue in the dashboard - (`en/dashboard/total-revenue.md`). - -Ask which shape the publisher wants if it isn't stated. If they actually want -the mediator *removed*, switch to `migrate-from-mediation.md`. +## Setup shapes + +Publishers with an existing mediator almost never remove it on day one. Decide +in this order: + +1. If the intent is to *remove* the mediator, switch to + `migrate-from-mediation.md`. +2. Enumerate the setup modes the platform actually offers: the pages under + `en//integrations/` plus the `trusted-arbiter` family in + `llms.txt`. The list below names today's shapes, but the docs index is the + source of truth — the set is open and availability varies by platform; a + mode not listed there for the platform doesn't exist for it yet. +3. Choose a shape **per ad format, not per app** — mixed setups are normal + (e.g. first look on interstitials, standalone banners, rewarded untouched). + Ask the publisher format by format if unstated, presenting each mode's own + one-line description from `llms.txt`. Record the resulting format → shape + matrix; integration, audit, and reporting all key off it. + +Today's shapes: + +- **First look** — CloudX gets the first chance at an impression; on no-fill, + the existing mediator's placement serves as before. Wiring per the platform's + `integrations/first-look.md` page — fetch it; it is the source of truth. +- **Parallel (Trusted Arbiter)** — CloudX-controlled arbitration compares a + CloudX bid with the incumbent's bid for the same slot and shows the winner. + Wiring per the platform's `trusted-arbiter.md` page — fetch it; it is the + source of truth, including how revenue is reported in both directions. +- **Standalone (per-format split)** — CloudX exclusively owns selected formats + (commonly banner/MREC/native) while the mediator keeps the rest. No + cross-stack fallback wiring for CloudX-owned formats; each side runs its own + placements. (Dedicated docs page pending — until it ships, this paragraph is + the field guidance.) + +**Decision-point guardrail.** CloudX must sit at or ahead of the decision +point for any impression it competes on. If the publisher's architecture runs +an auction *behind* CloudX (post-bid), or the bid comparison happens inside a +publisher-controlled framework, stop and surface it — that arrangement is +unsupported; the supported parallel mechanism is Trusted Arbiter. ## Universal rules @@ -83,9 +107,14 @@ the mediator *removed*, switch to `migrate-from-mediation.md`. offer an AdMob-waterfall adapter path (`adapters/googlewaterfall` pages) that serves existing AdMob waterfall placements through CloudX. Fetch its overview and put the choice to the publisher before wiring first-look. + AdMob does not price an ad before the impression; comparing against an + estimated AdMob price is dashboard-side configuration — never encode an + estimated eCPM in app code as a bid. ## Reporting the outcome -State explicitly which placements got first-look treatment, which run parallel, -and which remain untouched mediator placements; point the publisher at the -dashboard's mediation-comparison view for the revenue read. +State the final format → shape matrix explicitly — which formats got +first-look treatment, which run through the arbiter, which are standalone +CloudX, and which remain untouched mediator placements; point the publisher at +the dashboard's mediation-comparison view for the revenue read +(`en/dashboard/total-revenue.md`).