Document A2UI user-action to SI session event mapping

[pkras]

Summary

user-action.json exists in the A2UI schema (shipped in #906) and defines component-level interaction events. SI has its own session event model. The end-to-end mapping between A2UI user actions (viewed, clicked, expanded, submitted, etc.) and SI session measurement events is not documented.

What's Needed

• Mapping table: A2UI user-action.json event types → SI session event types
• Clarify who fires the SI measurement event — the host (which sees the user action) or the SI agent (which receives the action callback)?
• Document how host apps should report A2UI interaction data back into the SI measurement pipeline
• Consider whether user-action.json needs additional event types to cover SI-specific interactions (e.g. "add to cart", "checkout initiated")

Ref: #2904 (original RFC), #906 (implementation PR), a2ui/user-action.json

[bokelley]

Triage

Classification: Doc gap (+ one schema question)
Bucket(s): web / site / docs, spec / protocol
Status: ready-for-human (mapping table is draftable; commerce-event extension needs ruling)

What the experts said:

• ad-tech-protocol-expert: Host fires measurement events — host sees the DOM-level interaction, owns the measurement pinhole to SI, agent receives the callback and correlates to session. Matches OpenRTB/OMID conventions where the surface owner fires the beacon. Mapping table belongs in measurement.mdx (or a consolidated A2UI guide). The "add_to_cart" question IS architectural — extending user-action.json with commerce-semantic types couples A2UI to SI vocabulary and should go through @bokelley.
• docs-expert: Most bot-draftable of the three A2UI follow-ups — mechanical table from user-action.json to SI event schema, with "who fires" already implicit in implementing-si-agents.mdx/implementing-si-hosts.mdx. Flag gaps as open questions, don't invent event types.

My take: Experts agree on the mapping-table content (host fires, agent correlates) and agree the user-action.json event-type extension (e.g., add_to_cart, checkout_initiated) is a separate architectural call. Recommend landing the mapping table inside the consolidated A2UI integration guide (see #2919 / #2918), and splitting out the event-vocabulary extension as its own issue after @bokelley rules on whether A2UI carries commerce semantics or stays presentation-only.

---

Triaged by Claude Code. Session: https://claude.ai/code/1c1fb33b-fecb-4d12-b1db-01a2d5f4f49b

---

Generated by Claude Code

[bokelley]

Triage

Classification: Doc/spec question
Bucket(s): spec / protocol, documentation
Status: clarify

What the experts said:

• ad-tech-protocol-expert: Three distinct questions bundled — (1) mapping table is doc-only and executable, (2) who fires measurement (host-observes vs SI-callback) is architectural and parallels VAST tracker ownership, (3) new event types for commerce (add-to-cart, checkout) is a schema change needing enum-extension policy review.
• docs-expert: Mapping table can't be written without (2) and (3). Natural home is a new docs/sponsored-intelligence/measurement.mdx section; a user-action.json enum extension would need a protocol changeset.

My take: Experts converge on "split this". The mapping half is tractable standalone once ownership is decided; measurement locus and commerce event types each deserve their own thread.

Questions:

1. Can this be split into three issues — (a) mapping table, (b) who fires the SI measurement event, (c) commerce event types in user-action.json?
2. For (b), do you have a preference between host-observes and SI-callback, or is that exactly what you want decided?

---

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

---

Generated by Claude Code

[bokelley]

Drafted user-action mapping as part of the consolidated A2UI integration page in #3761. Two flows from one click — host → SI agent (si_send_message, turn-driving) and host → AdCP measurement (engagement counting). Open question on standardizing action name vocabulary is called out inline. Marked draft + needs-wg-review.