Seller-deployed measurement SDK on buyer property — model the OAIQ / merchant-pixel pattern

[bokelley]

Summary

AdCP today doesn't have a clean primitive for the seller-provided measurement SDK that runs on the buyer's property — a JavaScript SDK the seller publishes and the buyer's merchant pages deploy to feed conversion / engagement / dwell events back to the seller's measurement infrastructure. ChatGPT's oaiq.min.js (running on advertiser merchant pages, posting events to bzr.openai.com), and the equivalent patterns in retail-media networks, are real implementations.

Structurally distinct from existing AdCP surfaces and worth a dedicated primitive.

Origin

Surfaced from analysis of ChatGPT's ad-serving and attribution architecture in the context of the post-#3884 measurement work. The OAIQ SDK pattern:

1. Buyer integrates oaiq.min.js on merchant pages.
2. SDK extracts attribution token (oppref) from URL on landing.
3. SDK stores __oppref first-party cookie (30-day TTL).
4. SDK POSTs every measurable user action (page view, add-to-cart, checkout, etc.) to bzr.openai.com/v1/sdk/events carrying merchant pixel ID + oppref.
5. OpenAI reconciles server-side using the attribution token chain.

Conversions flow back to OpenAI for closed-loop attribution. The merchant's existing analytics stack continues to work in parallel; OAIQ is additive — purely seller-instrumented.

How this differs from existing AdCP primitives

Surface	What it does	Why this is different
tracker_script / tracker_pixel (creative manifest)	Third-party verification trackers (DV, IAS) running on publisher inventory	OAIQ runs on buyer property (merchant pages), not on publisher inventory
sync_event_sources / log_event	Buyer-side instrumentation pushing buyer's own events to seller	OAIQ is seller's SDK running on buyer property, not buyer's SDK
conversion_tracking.platform_managed: true	Indicates seller provides closed-loop measurement	Doesn't carry the SDK pointer, integration spec, or event schema

The closest existing primitive is conversion_tracking.platform_managed: true. OAIQ is more specific: the seller doesn't just manage conversion tracking — they provide an SDK the buyer integrates.

Proposal options

Option A — Extend conversion_tracking with optional SDK fields

"conversion_tracking": {
  "platform_managed": true,
  "merchant_sdk": {
    "vendor": { "domain": "openai.com" },
    "url": "https://oaiq.openai.com/oaiq.min.js",
    "version": "0.1.3",
    "sri_hash": "sha384-...",
    "integration_docs": "https://platform.openai.com/docs/oaiq",
    "supported_events": ["pageview", "add_to_cart", "checkout", "purchase"]
  }
}

Pros: localized to one schema; aligns with existing platform_managed.
Cons: ties the SDK to the product's conversion_tracking. A seller with multiple products on the same SDK carries it redundantly.

Option B — New merchant_sdk block on the measurement-agent capability surface

Add to get_adcp_capabilities.measurement so the seller's measurement-agent capability declares the SDK once:

"measurement": {
  "metrics": [...],
  "merchant_sdk": {
    "url": "https://oaiq.openai.com/oaiq.min.js",
    "version": "0.1.3",
    "sri_hash": "sha384-...",
    "integration_docs": "https://platform.openai.com/docs/oaiq",
    "event_schema_url": "https://oaiq.openai.com/schema.json"
  }
}

Pros: centralized; reuses BrandRef → measurement-agent pattern; one SDK declaration covers all products.
Cons: adds a new top-level shape on the capability surface.

Option C — Hybrid (recommended)

Capability declares the SDK (per Option B). Products reference it via sdk_required: true + the seller's BrandRef so buyer agents know which products need the SDK deployed.

Pros: clean discovery + per-product enablement; matches the rest of AdCP's vendor-capability pattern.
Cons: two surfaces to keep in sync.

What buyer agents need to do

1. Discover the SDK at product time (capability or conversion_tracking lookup).
2. Verify the SDK URL resolves and is signed/trusted (sri_hash for supply-chain integrity).
3. Deploy the SDK on merchant property as a standard tag-management step.
4. Confirm events are flowing (potentially via a sync_event_sources-style confirmation handshake).

Today's protocol assumes any merchant-side instrumentation is the buyer's own. Modeling seller-provided SDKs explicitly avoids "buyer cobbles together SDK URLs from out-of-band docs."

Open questions

1. Trust / supply chain: SDK delivered from seller domain executes on buyer property with access to merchant DOM. What attestation or signing should the protocol require? sri_hash covers content integrity; what about origin trust beyond brand.json agents[type='measurement'] discovery?
2. Event schema discoverability: Should the seller publish the SDK's event schema in a structured form so buyer agents validate or generate event payloads programmatically?
3. Multi-SDK coordination: A merchant running campaigns on ChatGPT, Walmart Connect, and another retail-media network would deploy three SDKs. Event collision, cookie collision, performance concerns?
4. Privacy and consent: Seller's SDK collects events on buyer's property. Buyer's privacy policy and consent management must cover it — typically yes since the buyer has a commercial relationship with the seller, but worth flagging.

Strawman

Option C (hybrid). Capability declares the SDK once; products reference it. Matches the rest of AdCP's vendor-capability pattern.

Related

• feat(schemas): unify outcome measurement into the row-shape vocabulary (closes #3857) #3884 — outcome-measurement unification (the framing this builds on)
• docs(measurement): add three-layer taxonomy doc #3843 — measurement taxonomy doc (graduated metrics, atomic unit, BrandRef discipline)
• feat(schemas): unify metric accountability — timestamped contract + symmetric audit #3576 — committed_metrics (BrandRef pattern this would extend)
• Tracker firing path (client / server / mixed) — is this a buyer concern AdCP needs to model, and where? #3832 — tracker_firing path declaration (related but distinct: tracker_firing is per-event firing path on inventory; merchant_sdk is per-buyer-property SDK)
• ChatGPT/OAIQ case study: https://www.buchodi.com/how-chatgpt-serves-ads-heres-the-full-attribution-loop/

[bokelley]

Triage

Classification: Feature request
Bucket(s): spec / protocol
Status: ready-for-human

What the experts said:

• ad-tech-protocol-expert: Option C matches the vendor-capability pattern, but flags two normative gaps before it can ship: (1) sdk_required: true on a product MUST be a conformance error when measurement.merchant_sdk is absent at capability level — that cross-reference must be a spec MUST with a storyboard scenario; (2) sri_hash covers content integrity only — spec must require that the SDK URL's eTLD+1 is authorized by brand.json agents[type='measurement'] for the seller's domain (same check already specified for delivery_measurement.vendors). Also notes measurement block has additionalProperties: false so merchant_sdk must be added explicitly to the schema, not smuggled via ext.
• adtech-product-expert: Prefers a simplified B+bool shape over Option C — capability declares the SDK once, product carries a plain merchant_sdk_required: true boolean (no BrandRef, since seller is already implied by product context). Critical flag: tag deployment (step c) is not agent-executable today; spec language must describe it as a deployment requirement surfaced to the operator, not an autonomous agent action. Privacy/consent should be a privacy_obligations URL (link to seller's DPA) rather than a bare boolean, matching how the broader protocol handles data-agreement references.

My take: Both experts endorse capability-level SDK declaration + a product-level signal; they split on the product-level shape. That choice has downstream implications for multi-vendor scenarios (a merchant deploying two sellers' SDKs). Three normative questions need prose regardless of shape chosen: origin-trust binding, operator-mediated deployment semantics, and privacy obligations reference. @bokelley, your call:

Option C — BrandRef on conversion_tracking (allows future multi-vendor expansion):

// get_adcp_capabilities.measurement
+ "merchant_sdk": {
+   "url": "https://sdk.example.com/measure.min.js",
+   "version": "0.1.3",
+   "sri_hash": "sha384-...",
+   "integration_docs": "https://example.com/docs/sdk"
+ }

// product.conversion_tracking
  "platform_managed": true,
+ "sdk_required": true,
+ "vendor": { "domain": "example.com", "brand_id": "..." }

Explicit vendor binding; redundant for single-seller products but extensible.

Simplified B+bool — single boolean on conversion_tracking (simpler, seller already implicit):

// get_adcp_capabilities.measurement — same merchant_sdk block above

// product.conversion_tracking
  "platform_managed": true,
+ "merchant_sdk_required": true

One hop at product discovery; no BrandRef duplication; loses multi-vendor handle.

---

Triaged by Claude Code. Session: https://claude.ai/code/cse_0123t1vNEwz6CoUSVGmqkTfo

---

Generated by Claude Code