# Compass Web SDK: Recommendation Attribution

Source: https://dev.arcxp.com/content-recommendations/sdk/attribution/

Tag the recommendations you render yourself so the Compass Web SDK reports their exposures and clicks.

This page shows how to register rendered recommendations so the Compass Web SDK emits the `recommendation_exposure` and `recommendation_click` events that Confirmed CTR is built from. For what attribution is and how clicks are matched to exposures, see [Attribution and Confirmed CTR](https://dev.arcxp.com/content-recommendations/content-recommendations-attribution/).

You rarely emit these events by hand: after each rendered recommendation is registered — by stamping DOM attributes or by an imperative call — the SDK times the exposure and captures the click for you, reusing the same consent gate, identity, batching, and retry behavior as every other event.

> **Note:**
> 
> This page is for **host-rendered** recommendation surfaces (an Arc XP PageBuilder Engine block, a recipe, or custom UI) where your own markup represents each recommendation, and you register those elements so the SDK can time their exposure and capture their clicks. For turning ranked recommendations into rendered cards, see [Rendering Recommendations](https://dev.arcxp.com/content-recommendations/content-recommendations-rendering-story-cards/).

## Host-rendered sets: the `data-arc-compass-*` binding

When your site renders recommendations itself, stamp one set of `data-arc-compass-*` attributes on each rendered recommendation element and the SDK discovers them automatically — an initial scan at `init()` (deferred to `DOMContentLoaded` when needed) plus a `MutationObserver` that picks up elements inserted later by lazy load, infinite scroll, or an SPA re-render. Discovered elements feed the same detector as every other path, so exposure timing, click delegation, consent, and batching are identical. This is the recommended host-rendered path: it is declarative and framework-agnostic, and there is no handle to manage.

| Attribute                       | Required | Maps to                                                                                                                                |
| ------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| data-arc-compass-item-id        | **Yes**  | Envelope item\_id — the recommended item this card points at.                                                                          |
| data-arc-compass-attribution-id | **Yes**  | attributionId — the per-item join token from the Recommender. Also the discovery key: elements are found by this attribute’s presence. |
| data-arc-compass-exposure-id    | **Yes**  | exposureId — shared by every card in one rendered set.                                                                                 |
| data-arc-compass-surface-id     | No       | surfaceId.                                                                                                                             |
| data-arc-compass-position       | No       | position (integer).                                                                                                                    |
| data-arc-compass-issued-at      | No       | issuedAt (ISO-8601 string).                                                                                                            |

```html
<div
  data-arc-compass-item-id="REC-A"
  data-arc-compass-attribution-id="attr-a"
  data-arc-compass-exposure-id="set-1"
  data-arc-compass-surface-id="rail"
  data-arc-compass-position="0"
>
  …card markup…
</div>
```

The recommended-item id comes from the recommendation, **not** the page’s `arc-compass:item-id` meta tag (which identifies the article the reader is on): each card points at a different item. An element missing any of the three required attributes is **skipped** — the first violation logs a `console.warn`naming the missing attribute(s); later ones log only under `debug: true`.

Four rules keep the data correct:

- **Stamp attributes before the element is inserted.** The binding reads them when the element is discovered and does not watch for later attribute changes.
- **Recreate nodes when the set is replaced.** Registration is once per DOM element: a framework re-render that _reuses_ the same nodes with new attribute values (React reconciliation, for example) keeps the original attribution and will not fire a new exposure. Key cards by recommendation so a new set produces new elements.
- **Pick one path per set.** Elements carrying `data-arc-compass-attribution-id`are tracked automatically — do **not** also pass them to `trackExposure` (or `observeRecommendations`), or every exposure and click is counted twice.
- **Scope or disable the scan** with the `attributionRoot` init option (default `document.body`; a container element or CSS selector narrows it, `false` turns it off). See [Configuration reference](https://dev.arcxp.com/content-recommendations/sdk/api-reference/#configuration-options).

## `trackExposure` — the imperative escape hatch

Hosts that already hold an element reference can register a single element instead of stamping attributes:

```js
ArcCompass.trackExposure(element, {
  itemId: "REC-A", // required
  attributionId: "attr-a", // required
  exposureId: "set-1", // required
  surfaceId: "rail",
  position: 0,
});
```

Despite the name, this arms **both** signals for the element: a `recommendation_exposure` when it becomes viewport-qualified and a `recommendation_click` when it (or a descendant) is clicked — the same semantics as the declarative binding, including the once-per-element rule. The element must live under `attributionRoot` for clicks to resolve. Calls made through the pre-load snippet stub are queued and replayed after the bundle loads, and registering the same element twice is a no-op.

## `observeRecommendations` — batch registration for custom SPAs

Fully client-rendered surfaces (React / Vue) that already hold element references and the attribution data in component state can register a whole set in one call and receive a handle to tear it down:

```js
const handle = ArcCompass.observeRecommendations({
  container, // the element wrapping the rendered set; also the click-delegation root
  items: [
    { element: elA, attribution: { itemId: "REC-A", attributionId: "attr-a", exposureId: "set-1", surfaceId: "rail", position: 0 } },
    { element: elB, attribution: { itemId: "REC-B", attributionId: "attr-b", exposureId: "set-1", surfaceId: "rail", position: 1 } },
  ],
});

// When the set is replaced (re-render, SPA route change, teardown):
handle.disconnect();
```

Prefer the `data-arc-compass-*` binding or `trackExposure` unless you specifically need what this adds: batch registration, and click delegation scoped to the set’s own `container` rather than the global `attributionRoot`. Two things to know:

- **`container` is the click-delegation root, not the visibility root.** Exposure is always measured against the viewport; `container` only scopes which clicks resolve to an observed element.
- **You own the lifecycle.** Always `disconnect()` a replaced set, or the stale detector keeps firing exposures. (The declarative binding avoids this: teardown is implicit when you recreate nodes.) Live detectors are also torn down when the client is disposed.

Registration is once per element, and the call is safe before the bundle finishes loading — the snippet stub queues it and returns a deferred handle that wires to the real detector on replay.

## Attribution fields

Every registration path on this page carries an attribution context. For the `data-arc-compass-*`binding, each field maps from the attribute in the [binding table](#host-rendered-sets-the-data-arc-compass--binding); for `trackExposure` and `observeRecommendations`, you pass it as the `attribution`object; and for a manual `track("recommendation_exposure" | "recommendation_click", …)`call it is the `attributionContext` prop. The Recommender issues these identifiers when it serves a set — **forward them verbatim**.

| Field         | Type           | Required | Description                                                                                                            |
| ------------- | -------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| exposureId    | string         | **Yes**  | Identifier of the rendered set (1–256 chars). **Every per-item exposure from one set MUST share the same exposureId.** |
| attributionId | string         | **Yes**  | Opaque per-item attribution identifier from the Recommender (1–256 chars).                                             |
| surfaceId     | string         | No       | Customer-visible surface where the set was rendered (1–256 chars).                                                     |
| position      | number         | No       | Zero-based position of the item within the set; integer in \[0, 10000\].                                               |
| issuedAt      | Date \| string | No       | When the Recommender issued the context. Pass the ISO-8601 string it emits, or a Date.                                 |
| source        | string         | No       | Attribution origin tag matching ^\[a-z0-9\_-\]{1,64}$. Omit to default to fy.                                          |

`exposureId` and `attributionId` are the load-bearing keys of the Confirmed-CTR join: without `attributionId` a click can never match its exposure, and without `exposureId` the exposure can confirm nothing. The imperative paths also require `itemId` (the recommended item, which the binding reads from `data-arc-compass-item-id`). The SDK refuses to emit attribution events that lack any of these three.

### Value validation

The SDK validates each field against the collector’s constraint **before**sending, so one bad value never `422`s the whole batch it rides in:

- an out-of-range `position` is **clamped** into `[0, 10000]`;
- an empty or over-long id, a `source` that does not match the pattern, or an otherwise invalid value is **dropped** (with a `console.warn` under `debug`) rather than sent.

Forward the Recommender’s values verbatim and they pass through untouched.

## Exposure and click timing

However a recommendation element is registered, the detector applies the same rules:

- **Viewport-qualified exposure.** A `recommendation_exposure` fires when an element is **≥50% visible for ≥1000ms** — not when it renders. An item below the fold is not an exposure until scrolled into view, and each element exposes **once** (a scroll out and back in does not re-fire). The dwell only advances while the page is visible, so a background tab produces no exposures until the reader brings it to the front.
- **Delegated click.** A single listener resolves any click to the nearest registered element and fires `recommendation_click`.
- **Fallback.** Where `IntersectionObserver` is unavailable, exposures are a no-op; delegated click capture still works.

## Consent

Attribution events are ordinary events: they emit through `track()` and respect the **same single consent gate** as all collection. Nothing is sent or persisted before `setConsent(true)`, and the resolved identity is applied at flush. The consent mechanics are not repeated here — see [Consent & Identity](https://dev.arcxp.com/content-recommendations/sdk/consent-identity/).

## See also

- [Compass Web SDK: Events & Reliability](https://dev.arcxp.com/content-recommendations/sdk/events-reliability/)
- [Compass Web SDK: Integration Guide](https://dev.arcxp.com/content-recommendations/sdk/integration-guide/)
- [Compass Web SDK: Consent & Identity](https://dev.arcxp.com/content-recommendations/sdk/consent-identity/)
- [Rendering Recommendations](https://dev.arcxp.com/content-recommendations/content-recommendations-rendering-story-cards/)
