RFC: standard ad-tech targeting dimensions (os, browser, media_type, custom, key_value_pairs)

[bokelley]

Background

Every major ad server (GAM, Kevel, Xandr, Triton, FreeWheel) supports five targeting dimensions that AdCP TargetingOverlay does not yet expose. Adopters carry these as local extensions on their internal targeting class, which means spec-conformant buyer agents cannot use them — defeating the point of having them.

device_type/device_type_exclude already landed as the precedent. This RFC bundles five sibling dimensions into one proposal modeled on it.

Proposed additions to TargetingOverlay

Field	Shape	Notes
os / os_exclude	list[str]	OS name (iOS, Android, Windows, …). Distinct from existing device_platform.
browser / browser_exclude	list[str]	Chrome, Safari, Firefox, …
media_type / media_type_exclude	list[str]	Display, video, audio, native, DOOH. (Distinct from format-level constraints.)
custom	dict[str, list[str]]	Free-form publisher-specific key-value targeting. Required for GAM customTargeting parity.
key_value_pairs	dict[str, str]	Managed-only injection (similar in shape to AXE-style segment annotations). Spec already defines 'key_value' as an ActivationKey.type literal in signals — concept is recognized.

Use case (real)

salesagent (Prebid AdCP reference implementation) carries all five locally. Filed as part of stale-annotation cleanup PR bokelley/salesagent#208 — the migration path is to use ext.salesagent.<field> until this lands, then move to spec.

Open questions

• custom shape — flat dict vs. nested? The dict-of-list shape covers the common "key in (a, b, c)" predicate; richer expressions could go through a future signals path.
• key_value_pairs access control — should it be marked managed-only on TargetingOverlay (e.g., overlay vs. server-only) or always-overlay?
• Naming — happy to align with whatever bikeshed shape lands.

Filing as RFC. Happy to iterate.

[bokelley]

Triage

Classification: Feature request (RFC)
Bucket(s): spec / protocol, schema, media-buy
Status: ready-for-human

What the experts said:

• ad-tech-protocol-expert: os — blocker; device_platform (which enumerates ios, android, windows, macos, fire_os, roku_os, etc.) is the OS field; adding os: list[str] creates a duplicate with weaker type guarantees — correct fix is device_platform_exclude. media_type — blocker; channels enum in product filters already handles channel selection at the right layer; TargetingOverlay is scoped to functional restrictions (compliance, compatibility, localization) and a media-type overlay would conflict with product selection at activation time. key_value_pairs — blocker; name collides with ActivationKey.type: "key_value" in the signals layer; TMP targeting_kvs already covers server-injected KV pass-through. browser — concern; needs Sec-CH-UA canonical enum + capability declaration, not list[str], and is undefined behavior for CTV / audio / DOOH. custom — concern; wire shape (dict[str, list[str]]) is correct and matches GAM customTargeting, but needs key namespacing and a capability declaration so buyers know what keys a given seller accepts.
• adtech-product-expert: Same findings on all five. Additional signal: promoting browser to first-class adds implementation overhead to every CTV, audio, and DOOH seller who can never honor it. key_value_pairs' managed-only boundary is unenforceable without an access-control model the spec does not currently have; TMP targeting_kvs already solves server-injection at the right layer. The only near-ready deliverables are device_platform_exclude (resolves the os gap without introducing a new concept) and custom with a capability gate.

My take: The RFC correctly identifies two real gaps — the missing device_platform_exclude and publisher-side KV targeting parity — but bundles them with three fields that need protocol redesign before they can land. Experts converge on the split: device_platform_exclude and optionally custom-with-cap-gate are 3.1-eligible; browser, media_type, and key_value_pairs need redirects, not first-class overlay fields.

@bokelley, your call between:

Option A — device_platform_exclude only (clean 3.1 PR, zero new concept):

// static/schemas/source/core/targeting.json
+  "device_platform_exclude": {
+    "type": "array",
+    "description": "Exclude specific platforms. Complement to device_platform. Seller must declare support in get_adcp_capabilities.",
+    "items": { "$ref": "/schemas/enums/device-platform.json" },
+    "minItems": 1
+  }

Sellers already declaring device_platform support have the underlying signal; exclusion can be declared alongside inclusion in capabilities with zero new schema surface.

Option B — add custom in the same PR (needs capability-schema design first):

get_adcp_capabilities — seller declares accepted KV taxonomy:

{
  "execution": {
    "targeting": {
      "custom_targeting_keys": [
        { "key": "acme_content_genre", "values": ["news", "sports"] }
      ]
    }
  }
}

TargetingOverlay.custom — buyer sends declared keys only:

{ "custom": { "acme_content_genre": ["news", "sports"] } }

Closes the GAM parity gap without ext.salesagent.*, but adds overhead: sellers must enumerate their KV taxonomy in capabilities, and the capability schema needs to be extended first.

For the other three: redirect browser to a follow-up RFC (Sec-CH-UA enum + capability gate); redirect media_type to product-filter / brief discovery (channel selection already handles this pre-activation); fold key_value_pairs into the TMP targeting_kvs path or, if buyer-supplied, merge the intent into custom with an access-control note in spec prose.

---

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

---

Generated by Claude Code