--- name: admob-api-skills description: Comprehensive agent skill for interacting with Google AdMob REST API (v1 & v1beta). Use when building, integrating, querying, or managing Google AdMob publisher accounts, apps, ad units, ad unit mappings, mediation groups, A/B experiments, or generating Network, Mediation, or Campaign performance reports. --- # Google AdMob API Skill This skill provides precise instructions, REST specifications, exact request payloads, validation rules, and zero-error guardrails for managing Google AdMob accounts, applications, ad units, mediation configurations, and generating analytical reports via the AdMob REST API (`v1` and `v1beta`). --- ## When to Use Activate this skill when: - Querying publisher account info (`accounts.get`, `accounts.list`) - Creating or listing apps (`accounts.apps.create`, `accounts.apps.list`) - Configuring ad units & mediation ad unit mappings (`accounts.adUnits.create`, `accounts.adUnits.list`, `accounts.adUnits.adUnitMappings.create`, `accounts.adUnits.adUnitMappings.list`, `accounts.adUnitMappings.batchCreate`) - Managing mediation groups, ad sources, adapters, and A/B experiments (`accounts.adSources.list`, `accounts.adSources.adapters.list`, `accounts.mediationGroups.create`, `accounts.mediationGroups.list`, `accounts.mediationGroups.patch`, `accounts.mediationGroups.mediationAbExperiments.create`, `accounts.mediationGroups.mediationAbExperiments.stop`) - Generating Network, Mediation, or Campaign performance reports (`accounts.networkReport.generate`, `accounts.mediationReport.generate`, `accounts.campaignReport.generate`) --- ## Quick Reference & Base Configuration - **Base Service Endpoint**: `https://admob.googleapis.com` - **Supported API Versions**: `v1`, `v1beta` (Prefer `v1beta` for mediation & creation APIs) - **OAuth Scopes**: - `https://www.googleapis.com/auth/admob.readonly` (Read-only access to accounts, apps, ad units, mediation groups, and reports) - `https://www.googleapis.com/auth/admob.report` (Reporting and account reading access) - `https://www.googleapis.com/auth/admob.monetization` (Full management access including app creation, ad unit creation, mediation group setup, and A/B experiments) Detailed reference files: - [endpoints.md](file:///home/hasrat/WebstormProjects/admob-skills/references/endpoints.md): Complete list of REST endpoints, parameters, request/response schemas, and scopes. - [reporting.md](file:///home/hasrat/WebstormProjects/admob-skills/references/reporting.md): Supported metrics, dimensions, filters, micros earnings format, and reporting specs. --- ## Complete 19-Method API Matrix | Method Identifier | HTTP | Endpoint Path Pattern | OAuth Scope Required | Access Level / Limits | |---|---|---|---|---| | `accounts.get` | `GET` | `/v1beta/{name=accounts/*}` | `admob.readonly` \| `admob.report` | Standard | | `accounts.list` | `GET` | `/v1beta/accounts` | `admob.readonly` \| `admob.report` | Standard | | `accounts.adSources.list` | `GET` | `/v1beta/{parent=accounts/*}/adSources` | `admob.readonly` \| `admob.report` | Standard | | `accounts.adSources.adapters.list` | `GET` | `/v1beta/{parent=accounts/*/adSources/*}/adapters` | `admob.monetization` \| `admob.readonly` | Standard | | `accounts.adUnitMappings.batchCreate` | `POST` | `/v1beta/{parent=accounts/*}/adUnitMappings:batchCreate` | `admob.monetization` | Limited Access; Max **100** items | | `accounts.adUnits.create` | `POST` | `/v1beta/{parent=accounts/*}/adUnits` | `admob.monetization` | Limited Access | | `accounts.adUnits.list` | `GET` | `/v1beta/{parent=accounts/*}/adUnits` | `admob.monetization` \| `admob.readonly` | Standard | | `accounts.adUnits.adUnitMappings.create` | `POST` | `/v1beta/{parent=accounts/*/adUnits/*}/adUnitMappings` | `admob.monetization` | Limited Access | | `accounts.adUnits.adUnitMappings.list` | `GET` | `/v1beta/{parent=accounts/*/adUnits/*}/adUnitMappings` | `admob.monetization` \| `admob.readonly` | Limited Access | | `accounts.apps.create` | `POST` | `/v1beta/{parent=accounts/*}/apps` | `admob.monetization` | Limited Access | | `accounts.apps.list` | `GET` | `/v1beta/{parent=accounts/*}/apps` | `admob.monetization` \| `admob.readonly` | Standard | | `accounts.campaignReport.generate` | `POST` | `/v1beta/{parent=accounts/*}/campaignReport:generate` | `admob.readonly` \| `admob.report` | Date range max **30 days** | | `accounts.mediationGroups.create` | `POST` | `/v1beta/{parent=accounts/*}/mediationGroups` | `admob.monetization` | Limited Access | | `accounts.mediationGroups.list` | `GET` | `/v1beta/{parent=accounts/*}/mediationGroups` | `admob.monetization` \| `admob.readonly` | Limited Access | | `accounts.mediationGroups.patch` | `PATCH` | `/v1beta/{mediationGroup.name=accounts/*/mediationGroups/*}` | `admob.monetization` | Standard | | `accounts.mediationGroups.mediationAbExperiments.create` | `POST` | `/v1beta/{parent=accounts/*/mediationGroups/*}/mediationAbExperiments` | `admob.monetization` | Limited Access | | `accounts.mediationGroups.mediationAbExperiments.stop` | `POST` | `/v1beta/{name=accounts/*/mediationGroups/*/mediationAbExperiments}:stop` | `admob.monetization` | Limited Access | | `accounts.mediationReport.generate` | `POST` | `/v1beta/{parent=accounts/*}/mediationReport:generate` | `admob.readonly` \| `admob.report` | Streaming RPC | | `accounts.networkReport.generate` | `POST` | `/v1beta/{parent=accounts/*}/networkReport:generate` | `admob.readonly` \| `admob.report` | Streaming RPC | --- ## Common Agent Workflows ### 1. Generating Performance Reports (`networkReport` / `mediationReport` / `campaignReport`) When requested to fetch earnings, impressions, or eCPM performance data: 1. Formulate POST request to `https://admob.googleapis.com/v1beta/accounts/{publisher_id}/networkReport:generate`. 2. Construct the `reportSpec` payload: - Provide `startDate` and `endDate` (`year`, `month`, `day`). - Select required `metrics` (e.g. `["ESTIMATED_EARNINGS", "AD_REQUESTS", "MATCHED_REQUESTS", "IMPRESSIONS", "CLICKS"]`). - Select required `dimensions` (e.g. `["DATE", "APP", "AD_UNIT"]`). - Specify `localizationSettings` (e.g. `currencyCode: "USD"`). *Network Report Payload Example:* ```json { "reportSpec": { "dateRange": { "startDate": { "year": 2026, "month": 7, "day": 1 }, "endDate": { "year": 2026, "month": 7, "day": 27 } }, "dimensions": ["DATE", "APP", "AD_UNIT"], "metrics": ["ESTIMATED_EARNINGS", "AD_REQUESTS", "IMPRESSIONS", "CLICKS"], "dimensionFilters": [ { "dimension": "COUNTRY", "matchesAny": { "values": ["US", "CA"] } } ], "localizationSettings": { "currencyCode": "USD", "languageCode": "en-US" } } } ``` *Campaign Report Payload Example (Max 30-Day Range):* ```json { "reportSpec": { "dateRange": { "startDate": { "year": 2026, "month": 7, "day": 1 }, "endDate": { "year": 2026, "month": 7, "day": 25 } }, "dimensions": ["CAMPAIGN_ID", "CAMPAIGN_NAME", "DATE"], "metrics": ["IMPRESSIONS", "CLICKS", "CLICK_THROUGH_RATE", "INSTALLS", "ESTIMATED_COST"], "languageCode": "en-US" } } ``` --- ### 2. Creating Apps, Ad Units & Batch Mappings When setting up monetization for a new application: 1. **Create App**: `POST /v1beta/accounts/{publisher_id}/apps` ```json { "platform": "ANDROID", "manualAppInfo": { "displayName": "Awesome Game" } } ``` 2. **Create Ad Unit**: `POST /v1beta/accounts/{publisher_id}/adUnits` using generated `appId`. ```json { "appId": "ca-app-pub-9876543210987654~1234567890", "displayName": "Main Banner", "format": "BANNER", "adTypes": ["TEXT", "IMAGE"] } ``` 3. **Batch Create Mappings**: `POST /v1beta/accounts/{publisher_id}/adUnitMappings:batchCreate` (Max 100 per call). ```json { "requests": [ { "parent": "accounts/pub-9876543210987654/adUnits/9876543210", "adUnitMapping": { "adapterId": "12345", "adUnitConfigurations": { "pub_id": "1234" }, "state": "ENABLED" } } ] } ``` --- ### 3. Mediation Setup, Patching & A/B Experiments 1. **List Ad Sources & Adapters**: `GET /v1beta/accounts/{publisher_id}/adSources` and `GET /v1beta/accounts/{publisher_id}/adSources/{adSourceId}/adapters`. 2. **Create Mediation Group**: `POST /v1beta/accounts/{publisher_id}/mediationGroups`. 3. **Patch Mediation Group**: `PATCH /v1beta/accounts/{publisher_id}/mediationGroups/{groupId}?updateMask=mediationGroupLines["123"].cpm_micros`. 4. **Create A/B Experiment**: `POST /v1beta/accounts/{publisher_id}/mediationGroups/{groupId}/mediationAbExperiments`. 5. **Stop Experiment**: `POST /v1beta/accounts/{publisher_id}/mediationGroups/{groupId}/mediationAbExperiments:stop` with payload `{"variantChoice": "VARIANT_CHOICE_A"}`. --- ## Critical Zero-Error Rules & Guardrails 1. **Exact Resource Name Syntax**: Account IDs MUST follow `accounts/pub-XXXXXXXXXXXXXXXX` (e.g. `accounts/pub-9876543210987654`). 2. **Strict Metric-Dimension Incompatibility Rule**: - In `networkReport`, **NEVER** combine `AD_TYPE` dimension with `AD_REQUESTS`, `MATCH_RATE`, or `IMPRESSION_RPM` metrics. Doing so results in `400 INVALID_ARGUMENT`. 3. **Campaign Report Date Range Limit**: - In `campaignReport:generate`, the duration between `startDate` and `endDate` MUST NOT exceed **30 days**. 4. **Batch Operation Size Ceiling**: - In `adUnitMappings.batchCreate`, the maximum array size for `requests` is **100**. Requests exceeding 100 items will be rejected completely. 5. **Micros Earnings Unit Conversion**: - All revenue/earnings figures (`ESTIMATED_EARNINGS`, `IMPRESSION_RPM`, `OBSERVED_ECPM`, `cpmMicros`) are returned/provided in **micros** ($1.00 USD = `1000000` micros). Always divide by 1,000,000 when presenting currency values to users. 6. **EBNF Filter String Formatting**: - Use `IN` for singletons (`DISPLAY_NAME`, `PLATFORM`, `STATE`). - Use `CONTAINS_ANY` for collections (`AD_SOURCE_IDS`, `AD_UNIT_IDS`, `APP_IDS`, `TARGETED_REGION_CODES`). - Join multiple conditions with `AND`. `OR` is **not** supported in filter strings. 7. **Pagination Cycle**: - When calling list endpoints (`apps.list`, `adUnits.list`, `mediationGroups.list`, `adSources.list`), check for `nextPageToken` in response and pass it as `pageToken` in subsequent calls until `nextPageToken` is empty. 8. **Handling 403 Limited Access Errors**: - If an endpoint returns HTTP 403 Forbidden, inspect error details. Limited access APIs (`apps.create`, `adUnits.create`, `adUnitMappings.create`, `mediationGroups.create`, `mediationAbExperiments.*`) require developer account provisioning from Google account management.