@adcp/client 4.20.0 → 4.22.0

package/storyboards/media_buy_catalog_creative.yaml

@@ -0,0 +1,457 @@
+id: media_buy_catalog_creative
+version: "1.0.0"
+title: "Catalog-driven creative and conversion tracking"
+category: media_buy_catalog_creative
+summary: "Seller that renders dynamic ads from product catalogs, tracks conversions, and optimizes delivery based on performance feedback."
+platform_types:
+  - retail_media
+
+track: media_buy
+required_tools:
+  - create_media_buy
+  - sync_creatives
+narrative: |
+  You run a platform that supports catalog-driven advertising — think Snap Dynamic Ads,
+  Meta Product Catalogs, or retail media product listing ads. The buyer pushes a product
+  catalog (menu items, retail products, hotel listings), and your platform renders ads
+  dynamically from that feed. When a user converts, events are logged back and attributed
+  to catalog items, closing the optimization loop.
+
+  This storyboard walks through the full catalog-to-conversion flow: account setup,
+  catalog sync, creative formats for catalog items, media buy with catalog packages,
+  event source configuration, conversion logging, and performance feedback.
+
+  The key difference from the standard media buy flow is that creatives are catalog-driven —
+  the buyer doesn't build individual ads. They push a feed, and your platform renders
+  the right item to the right user at the right time.
+
+agent:
+  interaction_model: media_buy_seller
+  capabilities:
+    - sells_media
+    - accepts_catalogs
+    - supports_conversion_tracking
+    - catalog_driven_creative
+  examples:
+    - "Snap (Dynamic Ads)"
+    - "Retail media networks"
+    - "Travel platforms"
+    - "Local commerce platforms"
+
+caller:
+  role: buyer_agent
+  example: "Scope3 (DSP)"
+
+prerequisites:
+  description: |
+    The caller needs a product catalog (feed URL or inline items) and an event source
+    for conversion tracking. The test kit provides a sample brand with catalog-compatible
+    assets.
+  test_kit: "test-kits/acme-outdoor.yaml"
+
+phases:
+  - id: account_setup
+    title: "Account setup"
+    narrative: |
+      The buyer establishes an account relationship with your platform. For catalog-driven
+      campaigns, the account must be active before any catalog sync can happen.
+
+    steps:
+      - id: sync_accounts
+        title: "Establish account"
+        narrative: |
+          The buyer registers their brand and operator. Sandbox accounts are provisioned
+          instantly for testing catalog flows.
+        task: sync_accounts
+        schema_ref: "account/sync-accounts-request.json"
+        response_schema_ref: "account/sync-accounts-response.json"
+        doc_ref: "/accounts/tasks/sync_accounts"
+        stateful: true
+        expected: |
+          Return the account with account_id, status (active for sandbox), and billing terms.
+
+        sample_request:
+          accounts:
+            - brand:
+                domain: "amsterdam-steakhouse.com"
+                name: "Amsterdam Steakhouse"
+              operator: "pinnacle-agency.com"
+              billing: "operator"
+              sandbox: true
+
+        validations:
+          - check: response_schema
+            description: "Response matches sync-accounts-response.json schema"
+          - check: field_present
+            path: "accounts[0].account_id"
+            description: "Account has a platform-assigned ID"
+
+  - id: catalog_sync
+    title: "Product catalog sync"
+    narrative: |
+      The buyer pushes their product catalog to your platform. This is the foundation of
+      catalog-driven advertising — every ad your platform renders comes from this feed.
+
+      For a restaurant, this is the menu. For retail, it is the product feed. For travel,
+      it is hotel or flight listings. Your platform validates each item against your
+      format requirements (image dimensions, required fields, pricing format) and returns
+      per-item approval status.
+
+      Large feeds may go async — the buyer gets back a submitted status and waits for
+      your platform to finish processing. Small feeds (inline items) are processed
+      synchronously.
+
+    steps:
+      - id: discover_catalog_formats
+        title: "Check catalog format requirements"
+        narrative: |
+          Before pushing catalog items, the buyer checks what creative formats your
+          platform supports for catalog-driven ads. This tells the buyer what image
+          dimensions, text lengths, and required fields each catalog item needs.
+        task: list_creative_formats
+        schema_ref: "creative/list-creative-formats-request.json"
+        response_schema_ref: "creative/list-creative-formats-response.json"
+        doc_ref: "/creative/task-reference/list_creative_formats"
+        stateful: false
+        expected: |
+          Return creative formats that accept catalog assets. Look for formats with
+          catalog-specific asset slots (product_image, product_title, price, description).
+
+        sample_request:
+          channels: ["display", "native"]
+
+        validations:
+          - check: response_schema
+            description: "Response matches list-creative-formats-response.json schema"
+          - check: field_present
+            path: "formats"
+            description: "Response contains formats array"
+
+      - id: sync_catalogs
+        title: "Push product catalog"
+        narrative: |
+          The buyer pushes their product feed. This can be a URL to an existing feed
+          (your platform fetches and re-fetches on a schedule) or inline items for
+          small catalogs.
+
+          Your platform validates each item: images meet minimum dimensions, required
+          fields are present, prices are formatted correctly. Items that fail validation
+          are rejected with specific reasons. Items that pass are approved and available
+          for dynamic creative rendering.
+        task: sync_catalogs
+        schema_ref: "media-buy/sync-catalogs-request.json"
+        response_schema_ref: "media-buy/sync-catalogs-response.json"
+        doc_ref: "/media-buy/task-reference/sync_catalogs"
+        stateful: true
+        expected: |
+          Return per-catalog results with:
+          - catalog_id and action (created/updated)
+          - item_count, items_approved, items_pending, items_rejected
+          - item_issues for rejected items with specific reasons
+          - next_fetch_at for URL-based feeds
+
+        sample_request:
+          account:
+            brand:
+              domain: "amsterdam-steakhouse.com"
+            operator: "pinnacle-agency.com"
+          catalogs:
+            - catalog_id: "menu_spring_2026"
+              catalog_type: "product"
+              name: "Spring 2026 Menu"
+              items:
+                - item_id: "ribeye_36oz"
+                  title: "36oz Tomahawk Ribeye"
+                  description: "Dry-aged 45 days, served with truffle butter and roasted bone marrow"
+                  url: "https://amsterdam-steakhouse.com/menu/ribeye-36oz"
+                  image_url: "https://cdn.amsterdam-steakhouse.com/menu/ribeye-36oz-hero.jpg"
+                  price:
+                    amount: 89.00
+                    currency: "USD"
+                - item_id: "seafood_tower"
+                  title: "Grand Seafood Tower"
+                  description: "Oysters, king crab, lobster tail, shrimp cocktail, tuna tartare"
+                  url: "https://amsterdam-steakhouse.com/menu/seafood-tower"
+                  image_url: "https://cdn.amsterdam-steakhouse.com/menu/seafood-tower-hero.jpg"
+                  price:
+                    amount: 145.00
+                    currency: "USD"
+                - item_id: "wagyu_flight"
+                  title: "A5 Wagyu Tasting Flight"
+                  description: "Three cuts of Japanese A5 Wagyu — striploin, ribeye cap, tenderloin"
+                  url: "https://amsterdam-steakhouse.com/menu/wagyu-flight"
+                  image_url: "https://cdn.amsterdam-steakhouse.com/menu/wagyu-flight-hero.jpg"
+                  price:
+                    amount: 195.00
+                    currency: "USD"
+
+        validations:
+          - check: response_schema
+            description: "Response matches sync-catalogs-response.json schema"
+          - check: field_present
+            path: "catalogs[0].catalog_id"
+            description: "Catalog has an ID"
+          - check: field_present
+            path: "catalogs[0].item_count"
+            description: "Catalog reports item count"
+          - check: field_present
+            path: "catalogs[0].items_approved"
+            description: "Catalog reports approved item count"
+
+  - id: create_buy
+    title: "Create catalog-driven media buy"
+    narrative: |
+      The buyer creates a media buy with catalog-driven packages. Instead of assigning
+      individual creatives, the buyer references the synced catalog. Your platform
+      renders the right catalog items dynamically based on user context, intent signals,
+      and inventory availability.
+
+      The key schema difference: packages include a catalogs[] array instead of (or
+      alongside) creative_assignments[].
+
+    steps:
+      - id: get_products
+        title: "Discover catalog-compatible products"
+        narrative: |
+          The buyer finds products that support catalog-driven delivery. These products
+          accept catalog references and render dynamic ads from the feed.
+        task: get_products
+        schema_ref: "media-buy/get-products-request.json"
+        response_schema_ref: "media-buy/get-products-response.json"
+        doc_ref: "/media-buy/task-reference/get_products"
+        stateful: false
+        expected: |
+          Return products that support catalog-driven creative. Products should indicate
+          catalog compatibility in their format requirements.
+
+        sample_request:
+          buying_mode: "brief"
+          brief: "Dynamic product ads for a high-end steakhouse. Geo-targeted to 10 miles around Amsterdam location. Drive reservations and foot traffic."
+          brand:
+            domain: "amsterdam-steakhouse.com"
+          account:
+            brand:
+              domain: "amsterdam-steakhouse.com"
+            operator: "pinnacle-agency.com"
+
+        validations:
+          - check: response_schema
+            description: "Response matches get-products-response.json schema"
+          - check: field_present
+            path: "products"
+            description: "Response contains products"
+
+      - id: create_media_buy
+        title: "Create media buy with catalog packages"
+        narrative: |
+          The buyer creates the media buy with packages that reference the synced catalog.
+          Each package has a catalogs[] array specifying which catalog feeds drive the
+          dynamic creative for that line item.
+
+          Your platform optimizes across catalog items within each package's budget
+          envelope — showing the ribeye to steak lovers and the seafood tower to
+          seafood enthusiasts.
+        task: create_media_buy
+        schema_ref: "media-buy/create-media-buy-request.json"
+        response_schema_ref: "media-buy/create-media-buy-response.json"
+        doc_ref: "/media-buy/task-reference/create_media_buy"
+        stateful: true
+        expected: |
+          Create the media buy with catalog-driven packages. Return:
+          - media_buy_id
+          - status: active or confirmed
+          - packages with catalog references preserved
+
+        sample_request:
+          account:
+            brand:
+              domain: "amsterdam-steakhouse.com"
+            operator: "pinnacle-agency.com"
+          brand:
+            domain: "amsterdam-steakhouse.com"
+          start_time: "2026-04-07T00:00:00Z"
+          end_time: "2026-06-30T23:59:59Z"
+          packages:
+            - product_id: "local_display_dynamic"
+              pricing_option_id: "cpm_standard"
+              budget: 5000
+              catalogs:
+                - catalog_id: "menu_spring_2026"
+                  catalog_type: "product"
+
+        validations:
+          - check: response_schema
+            description: "Response matches create-media-buy-response.json schema"
+
+  - id: event_setup
+    title: "Conversion tracking setup"
+    narrative: |
+      The buyer configures event sources so your platform can attribute conversions to
+      catalog items. For a restaurant, the events are reservations and walk-ins. For
+      retail, they are purchases and add-to-carts.
+
+      Your platform returns setup snippets (pixel code, SDK instructions) that the
+      buyer installs on their conversion surfaces.
+
+    steps:
+      - id: sync_event_sources
+        title: "Configure event sources"
+        narrative: |
+          The buyer tells your platform where conversion events will come from —
+          a website pixel, a mobile SDK, or a server-to-server integration. Your
+          platform returns the integration code.
+        task: sync_event_sources
+        schema_ref: "media-buy/sync-event-sources-request.json"
+        response_schema_ref: "media-buy/sync-event-sources-response.json"
+        doc_ref: "/media-buy/task-reference/sync_event_sources"
+        stateful: true
+        expected: |
+          Return event sources with:
+          - event_source_id and seller_id
+          - setup.snippet: integration code (JavaScript pixel, HTML tag, or pixel URL)
+          - setup.instructions: human-readable integration guide
+          - action: created or updated
+
+        sample_request:
+          account:
+            brand:
+              domain: "amsterdam-steakhouse.com"
+            operator: "pinnacle-agency.com"
+          event_sources:
+            - event_source_id: "amsterdam_website"
+              name: "Amsterdam Steakhouse Website"
+              event_types: ["purchase", "add_to_cart", "page_view", "lead"]
+              allowed_domains: ["amsterdam-steakhouse.com", "book.amsterdam-steakhouse.com"]
+
+        validations:
+          - check: response_schema
+            description: "Response matches sync-event-sources-response.json schema"
+          - check: field_present
+            path: "event_sources[0].setup.snippet"
+            description: "Event source includes setup snippet"
+
+  - id: conversion_tracking
+    title: "Log conversions"
+    narrative: |
+      The campaign is running and customers are converting. The buyer logs conversion
+      events back to your platform, attributing them to catalog items via content_ids.
+
+      When someone books a reservation after seeing the ribeye ad, the event includes
+      content_ids: ["ribeye_36oz"] — linking the conversion to the catalog item that
+      drove it. Your platform uses this signal to optimize which items to show.
+
+    steps:
+      - id: log_events
+        title: "Send conversion events"
+        narrative: |
+          The buyer sends a batch of conversion events. Each event includes the event
+          type, value, and content_ids linking to catalog items. Your platform processes
+          these for attribution and optimization.
+        task: log_event
+        schema_ref: "media-buy/log-event-request.json"
+        response_schema_ref: "media-buy/log-event-response.json"
+        doc_ref: "/media-buy/task-reference/log_event"
+        stateful: true
+        expected: |
+          Process the events and return:
+          - events_received and events_processed counts
+          - partial_failures for events that failed validation
+          - match_quality: how well events matched to ad exposures (0.0-1.0)
+
+        sample_request:
+          event_source_id: "amsterdam_website"
+          events:
+            - event_id: "evt_001"
+              event_type: "purchase"
+              timestamp: "2026-04-15T19:30:00Z"
+              content_ids: ["ribeye_36oz"]
+              value: 89.00
+              currency: "USD"
+            - event_id: "evt_002"
+              event_type: "lead"
+              timestamp: "2026-04-15T20:15:00Z"
+              content_ids: ["wagyu_flight"]
+              value: 195.00
+              currency: "USD"
+            - event_id: "evt_003"
+              event_type: "page_view"
+              timestamp: "2026-04-15T20:45:00Z"
+              content_ids: ["seafood_tower"]
+
+        validations:
+          - check: response_schema
+            description: "Response matches log-event-response.json schema"
+          - check: field_present
+            path: "events_received"
+            description: "Response reports events received"
+          - check: field_present
+            path: "match_quality"
+            description: "Response includes match quality score"
+
+  - id: optimization_loop
+    title: "Performance feedback and optimization"
+    narrative: |
+      The buyer closes the optimization loop by telling your platform how the campaign
+      is performing against their goals. A performance_index above 1.0 means the
+      campaign is exceeding expectations — your platform should maintain or increase
+      delivery. Below 1.0 means underperforming — your platform should adjust targeting,
+      item selection, or pacing.
+
+    steps:
+      - id: provide_feedback
+        title: "Submit performance feedback"
+        narrative: |
+          The buyer reports that the campaign is driving 1.4x the expected reservation
+          rate. Your platform uses this signal to optimize delivery — showing more of
+          the high-performing catalog items and adjusting bid strategies.
+        task: provide_performance_feedback
+        schema_ref: "media-buy/provide-performance-feedback-request.json"
+        response_schema_ref: "media-buy/provide-performance-feedback-response.json"
+        doc_ref: "/media-buy/task-reference/provide_performance_feedback"
+        stateful: true
+        expected: |
+          Acknowledge the feedback. The seller should adjust delivery optimization
+          based on the performance_index signal.
+
+        sample_request:
+          media_buy_id: "mb_amsterdam_spring_2026"
+          measurement_period:
+            start: "2026-04-07T00:00:00Z"
+            end: "2026-04-14T23:59:59Z"
+          performance_index: 1.4
+          metric_type: "conversion_rate"
+          feedback_source: "buyer_attribution"
+
+        validations:
+          - check: response_schema
+            description: "Response matches provide-performance-feedback-response.json schema"
+          - check: field_value
+            path: "success"
+            description: "Feedback accepted"
+
+      - id: check_delivery
+        title: "Monitor delivery with catalog attribution"
+        narrative: |
+          The buyer checks delivery metrics to see which catalog items are driving
+          performance and how spend is allocated across the product feed.
+        task: get_media_buy_delivery
+        schema_ref: "media-buy/get-media-buy-delivery-request.json"
+        response_schema_ref: "media-buy/get-media-buy-delivery-response.json"
+        doc_ref: "/media-buy/task-reference/get_media_buy_delivery"
+        stateful: true
+        expected: |
+          Return delivery metrics including impressions, clicks, spend, and
+          conversion data attributed to catalog items.
+
+        sample_request:
+          account:
+            brand:
+              domain: "amsterdam-steakhouse.com"
+            operator: "pinnacle-agency.com"
+          media_buy_ids:
+            - "mb_amsterdam_spring_2026"
+          include_package_daily_breakdown: true
+
+        validations:
+          - check: response_schema
+            description: "Response matches get-media-buy-delivery-response.json schema"