diff --git a/docs/media-buy/api-reference.md b/docs/media-buy/api-reference.md index a796e56692..324b7a4133 100644 --- a/docs/media-buy/api-reference.md +++ b/docs/media-buy/api-reference.md @@ -712,13 +712,18 @@ Retrieves delivery data for all active media buys across all principals. ### 16. list_products -Lists all available advertising products for the authenticated principal. +Lists available advertising products for the authenticated principal. **Request:** ```json { - "category": "video", // Optional - filter by category - "min_budget": 1000 // Optional - filter by minimum budget + "brief": "Looking for premium sports inventory", // Optional - natural language brief + "filters": { // Optional filters based on product fields + "delivery_type": "guaranteed", // "guaranteed" or "non_guaranteed" + "formats": ["video"], // Filter by specific formats + "is_fixed_price": true, // Fixed price vs auction + "creative_types": ["video", "display"] // Filter by creative type + } } ``` @@ -730,10 +735,14 @@ Lists all available advertising products for the authenticated principal. "product_id": "connected_tv_prime", "name": "Connected TV - Prime Time", "description": "Premium CTV inventory 8PM-11PM", - "formats": ["video"], + "formats": [{ + "format_id": "video_standard" + }], "delivery_type": "guaranteed", + "is_fixed_price": true, + "cpm": 45.00, "min_spend": 10000, - "targeting_available": ["geography", "demographics", "interests"] + "brief_relevance": "Premium CTV inventory aligns with sports content request and prime time targeting" // If brief was provided } ] } diff --git a/docs/media-buy/creative-formats.md b/docs/media-buy/creative-formats.md index 1c00d500fa..9bc387e18e 100644 --- a/docs/media-buy/creative-formats.md +++ b/docs/media-buy/creative-formats.md @@ -5,7 +5,40 @@ title: Creative Formats # Creative Formats -All creative formats have a unique identifier and specify delivery methods: +All creative formats have a unique identifier and specify delivery methods. + +## Authoritative Source + +The official JSON schema for standard creative formats is available at: +- **Production**: https://adcontextprotocol.org/schemas/creative-formats-v1.json +- **GitHub**: https://github.com/adcontextprotocol/adcp/blob/main/static/schemas/creative-formats-v1.json + +### Programmatic Access + +Servers should fetch and cache this schema: + +```bash +# Fetch the latest creative formats +curl https://adcontextprotocol.org/schemas/creative-formats-v1.json + +# Or use the GitHub raw URL +curl https://raw.githubusercontent.com/adcontextprotocol/adcp/main/static/schemas/creative-formats-v1.json +``` + +### Schema Structure + +The JSON schema includes: +- **formats**: Organized by type (video, audio, display, rich_media, dooh) +- **specs**: Technical specifications for each format +- **delivery_options**: Supported delivery methods and protocols +- **delivery_protocols**: Reference information for VAST, MRAID, etc. + +### Version Management + +- Current version: v1 +- Updates will be versioned (creative-formats-v2.json, etc.) +- Breaking changes will increment the major version +- Implementations should check the `version` field #### Standard Video Formats diff --git a/docs/media-buy/media-products.md b/docs/media-buy/media-products.md index 9f399df6b7..52fe117bca 100644 --- a/docs/media-buy/media-products.md +++ b/docs/media-buy/media-products.md @@ -4,7 +4,7 @@ title: Media Products & Discovery # Media Products & Discovery -A **Product** is the core sellable unit in AdCP. This document details the Product model, including its pricing and delivery types, and the process for discovering standard, principal-specific, and custom-generated products. +A **Product** is the core sellable unit in AdCP. This document details the Product model, including its pricing and delivery types, and how products are discovered through the protocol. ## The Product Model @@ -12,7 +12,6 @@ A **Product** is the core sellable unit in AdCP. This document details the Produ - `name` (string, required) - `description` (string, required) - `formats` (list[Format], required): See [Creative Formats](creative-formats.md). -- `targeting_template` (Targeting, required): See [Targeting](targeting.md). - `delivery_type` (string, required): Either `"guaranteed"` or `"non_guaranteed"`. - `is_fixed_price` (bool, required): `true` if the price is fixed, `false` if it is auction-based. - `cpm` (float, optional): The fixed Cost Per Mille. **Required** if `is_fixed_price` is `true`. @@ -50,12 +49,19 @@ These products represent inventory available in an auction. The final price is n ### Custom & Principal-Specific Products A server can offer a general catalog, but it can also return: -- **Principal-Specific Products**: If a `principal_id` is sent in the `list_products` request, the server can return products reserved for or negotiated with that specific client. +- **Principal-Specific Products**: Servers can return products reserved for or negotiated with the authenticated principal. - **Custom Products**: The server can generate new, temporary products in response to a `brief`, returning them with `is_custom: true` and an `expires_at` timestamp. This allows for maximum flexibility without cluttering the main catalog. +## Product Discovery + +Servers determine how to match products to requests based on: +- The authenticated principal's identity and permissions +- Optional brief describing campaign objectives +- Optional filters for product attributes + ## Product Discovery Lifecycle -The product discovery process in AdCP is designed to be intuitive and AI-friendly, allowing buyers to find relevant inventory using natural language. Here's how it works: +The product discovery process is designed to be intuitive and AI-friendly, allowing buyers to find relevant inventory using natural language: ### 1. Natural Language Discovery (`discover_products`) @@ -88,12 +94,7 @@ The system returns products ranked by relevance: "min": 35.00, "max": 65.00 }, - "match_reasons": [ - "Prime time daypart matches request", - "CTV reaches pet owner households", - "California geo-targeting available" - ], - "relevance_score": 0.92 + "brief_relevance": "Premium CTV inventory with prime time daypart and California geo-targeting matches sports content request" } ] } @@ -101,45 +102,84 @@ The system returns products ranked by relevance: ### 3. Product Catalog Browsing (`list_products`) -Alternatively, buyers can browse the full product catalog with filters: +Buyers can browse the product catalog with filters: ```json { - "category": "video", - "min_budget": 5000, - "formats": ["video"] + "brief": "Looking for premium sports inventory", + "filters": { + "formats": ["video"], + "delivery_type": "guaranteed" + } } ``` -This returns all matching products available to the principal, including: -- Standard catalog products -- Principal-specific negotiated rates -- Custom products created for previous campaigns +The server returns products based on: +- The authenticated principal's access +- Brief matching (if provided) +- Applied filters ### 4. Custom Product Generation -For unique requirements, the system can generate custom products on-demand: +For unique requirements, servers can generate custom products on-demand: +- Products are marked with `is_custom: true` +- Include `expires_at` to prevent catalog bloat +- Pricing based on the specific requirements + +### Off-the-Shelf Products + +Publishers may offer standard products that are common across the industry, depending on their type: + +1. **Display Products**: + - Homepage takeover + - Run of site banner + - Mobile interstitial + - Native content units + +2. **Video Products**: + - Pre-roll video + - Mid-roll video + - Connected TV spots + - Outstream video + +3. **Audio Products**: + - Podcast pre-roll + - Streaming audio spots + - Voice assistant placements -1. **Brief Analysis**: The AI analyzes requirements that don't match existing products -2. **Custom Creation**: New products are created with `is_custom: true` -3. **Expiration**: Custom products include `expires_at` to prevent catalog bloat -4. **Pricing**: Custom pricing based on the specific requirements +4. **DOOH Products**: + - Digital billboards + - Transit displays + - Retail screens ### Discovery Best Practices -1. **Start Broad**: Begin with natural language discovery to understand options -2. **Refine Requirements**: Use discovery insights to refine targeting and budget -3. **Check Availability**: Move to `get_avails` once products are identified -4. **Consider Custom**: For unique campaigns, leverage custom product generation +1. **Use Natural Language Briefs**: Help servers understand campaign intent +2. **Apply Relevant Filters**: Use product field filters effectively +3. **Consider Custom Products**: For unique campaigns that don't match standard inventory + +### Example Product + +```json +{ + "product_id": "sports_premium", + "name": "Sports - Premium Inventory", + "description": "High-impact placements on sports content", + "formats": [{ + "format_id": "display_leaderboard" + }], + "delivery_type": "guaranteed", + "is_fixed_price": true, + "cpm": 25.00 +} +``` ### Discovery to Purchase Flow ``` -1. discover_products → Find relevant inventory +1. list_products → Find relevant inventory 2. get_avails → Check availability and pricing -3. create_media_buy → Purchase selected products +3. create_media_buy → Purchase using product_id 4. add_creative_assets → Upload creatives 5. Monitor delivery → Track performance ``` - -The discovery process is designed to feel conversational while providing structured data for programmatic execution. diff --git a/docs/media-buy/targeting.md b/docs/media-buy/targeting.md index 41921002b6..17cadc87d7 100644 --- a/docs/media-buy/targeting.md +++ b/docs/media-buy/targeting.md @@ -129,28 +129,11 @@ Used primarily for AEE (Ad Effectiveness Engine) signal integration: Some platform-specific fields within `custom` targeting may also be managed-only, depending on the adapter configuration. -## Layered Application +## Targeting Application -Targeting is applied in two layers: +### Media Buy Targeting Overlay -### 1. Product Targeting Template - -Products define their base audience: - -```json -{ - "product_id": "premium_sports_video", - "targeting_template": { - "content_category_any_of": ["IAB17"], // Sports - "device_type_any_of": ["ctv", "desktop"], - "media_type_any_of": ["video"] - } -} -``` - -### 2. Media Buy Targeting Overlay - -Media buys can refine the targeting: +Media buys apply targeting through the overlay: ```json { @@ -166,12 +149,9 @@ Media buys can refine the targeting: } ``` -### 3. Final Effective Targeting +### Final Effective Targeting -The system combines both layers: -- Lists are merged (union for `any_of`, union for `none_of`) -- Structured fields use the most specific value -- Custom fields are merged by platform +The targeting overlay is applied to the media buy and combined with any targeting inherent in the product. This includes both audience selection criteria and ad server-specific settings like geographic targeting. ## Platform Compatibility @@ -261,7 +241,7 @@ Example error: 1. **Validate Support**: Check platform capabilities before creating media buys 2. **Start Broad**: Begin with fewer restrictions and refine based on performance 3. **Use Standard Dimensions**: Prefer standard over custom targeting when possible -4. **Layer Thoughtfully**: Use product templates for common criteria, overlays for campaign-specific needs +4. **Apply Targeting via Overlay**: All targeting is applied through the media buy's targeting_overlay 5. **Monitor Compatibility**: Pay attention to platform warnings and errors ## Future Enhancements diff --git a/static/schemas/creative-formats-v1.json b/static/schemas/creative-formats-v1.json new file mode 100644 index 0000000000..37c195e99b --- /dev/null +++ b/static/schemas/creative-formats-v1.json @@ -0,0 +1,182 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "AdCP Standard Creative Formats", + "version": "1.0.0", + "description": "Authoritative list of standard creative formats for Ad Context Protocol", + "lastUpdated": "2024-01-30", + "formats": { + "display": { + "display_300x250": { + "format_id": "display_300x250", + "type": "display", + "description": "Medium Rectangle banner", + "specs": { + "dimensions": "300x250" + }, + "is_3p_served": false + }, + "display_3p_300x250": { + "format_id": "display_3p_300x250", + "type": "display", + "description": "Medium Rectangle with third-party tag", + "specs": { + "dimensions": "300x250" + }, + "is_3p_served": true + }, + "display_728x90": { + "format_id": "display_728x90", + "type": "display", + "description": "Leaderboard banner", + "specs": { + "dimensions": "728x90" + }, + "is_3p_served": false + }, + "display_3p_728x90": { + "format_id": "display_3p_728x90", + "type": "display", + "description": "Leaderboard with third-party tag", + "specs": { + "dimensions": "728x90" + }, + "is_3p_served": true + }, + "display_320x50": { + "format_id": "display_320x50", + "type": "display", + "description": "Mobile banner", + "specs": { + "dimensions": "320x50" + }, + "is_3p_served": false + }, + "display_3p_320x50": { + "format_id": "display_3p_320x50", + "type": "display", + "description": "Mobile banner with third-party tag", + "specs": { + "dimensions": "320x50" + }, + "is_3p_served": true + }, + "display_native": { + "format_id": "display_native", + "type": "display", + "subtype": "native", + "description": "Native ad matching content style", + "specs": { + "requirements": ["title", "description", "image", "click URL"] + }, + "is_3p_served": false + } + }, + "video": { + "video_standard": { + "format_id": "video_standard", + "type": "video", + "description": "Standard video ad", + "specs": { + "common_durations": ["15s", "30s"], + "common_resolutions": ["1920x1080", "1280x720"] + }, + "is_3p_served": false + }, + "video_3p_standard": { + "format_id": "video_3p_standard", + "type": "video", + "description": "Standard video with VAST tag", + "specs": { + "delivery": "VAST URL" + }, + "is_3p_served": true + }, + "video_vertical": { + "format_id": "video_vertical", + "type": "video", + "description": "Vertical video for mobile", + "specs": { + "aspect_ratio": "9:16", + "common_durations": ["6s", "15s", "30s"] + }, + "is_3p_served": false + }, + "video_ctv": { + "format_id": "video_ctv", + "type": "video", + "description": "Connected TV video", + "specs": { + "features": ["non-skippable", "sound on"], + "common_durations": ["15s", "30s", "60s"] + }, + "is_3p_served": false + }, + "video_3p_ctv": { + "format_id": "video_3p_ctv", + "type": "video", + "description": "Connected TV with VAST tag", + "specs": { + "delivery": "VAST URL" + }, + "is_3p_served": true + } + }, + "audio": { + "audio_standard": { + "format_id": "audio_standard", + "type": "audio", + "description": "Standard audio ad", + "specs": { + "common_durations": ["15s", "30s", "60s"] + }, + "is_3p_served": false + }, + "audio_3p_standard": { + "format_id": "audio_3p_standard", + "type": "audio", + "description": "Audio with VAST tag", + "specs": { + "delivery": "VAST URL" + }, + "is_3p_served": true + }, + "audio_podcast": { + "format_id": "audio_podcast", + "type": "audio", + "description": "Podcast audio ad", + "specs": { + "insertion_points": ["pre-roll", "mid-roll", "post-roll"] + }, + "is_3p_served": false + } + }, + "rich_media": { + "rich_interstitial": { + "format_id": "rich_interstitial", + "type": "rich_media", + "description": "Full-screen interactive ad", + "specs": { + "features": ["interactive", "expandable"] + }, + "is_3p_served": false + } + }, + "dooh": { + "dooh_standard": { + "format_id": "dooh_standard", + "type": "dooh", + "description": "Digital out-of-home display", + "specs": { + "common_durations": ["8s", "10s", "15s"], + "features": ["weather triggers", "dayparting"] + }, + "is_3p_served": false + } + } + }, + "notes": { + "flexibility": "These formats are intentionally underspecified to allow maximum flexibility. Publishers should accept standard assets and handle platform-specific requirements.", + "third_party": "Formats with is_3p_served: true accept third-party ad tags. Others accept direct assets.", + "verification": "All formats should support optional ad verification/measurement tags where applicable." + } +} \ No newline at end of file