Report signals

Each track.* records a signal and the SDK sends it for you. It never throws or waits for the network: call it without await, from the click handler.

The methods

All of them take the recommendation (in the API, Decision: the list of products recommended for that moment) or its decision_id. Except for the impression and checkout, they also take the result (or its item_id).

crossup.track.impression(decision);
crossup.track.click(decision, result);
crossup.track.addToCart(decision, result, { quantity: 2 });
crossup.track.removeFromCart(decision, result);
crossup.track.updateQuantity(decision, result, { quantity: 0 });
crossup.track.dismiss(decision, result);
crossup.track.checkoutStarted(decision);

Method	Signal	When, and what matters
`impression`	`impression`	When it enters the screen, not when it’s generated
`click`	`click`	When a product is opened, before navigating. The SDK makes sure it goes out
`addToCart`	`add_to_cart`	`quantity`: the units added, not the total
`removeFromCart`	`remove_from_cart`	When it’s taken out of the cart
`updateQuantity`	`update_quantity`	`quantity`: the units left; 0 removes the line
`checkoutStarted`	`checkout_started`	When heading to checkout, once. It records the moment, not the sale
`dismiss`	`dismiss`	When the offer is closed without taking it. With no result, the first one

Each method returns the signal id, or undefined if it couldn’t be built (onSignalError says why). They accept signalId, your own stable id; cartId, which overrides the instance’s; and occurredAt, now by default.

A purchase isn’t a signal

Your store’s order says a sale closed, not the browser. For CrossUp to tie it to the recommendation, give it the cart id once, when creating the instance; it travels on every request and every signal:

const crossup = createStorefront({
  apiKey: "spk_…",
  connectionId: "cn_…",
  cartId: () => cart?.id, // a function: the cart gets its id with the first product
});

How it’s matched against the order: Signals and attribution.

checkoutStarted and cartId aren’t in the version published on npm yet (0.1.0), which ships a track.purchase the contract no longer accepts. Until the next version, send checkout_started and cart_id through the API.

Every signal carries the visitor and the context on its own, with no personal data: Visitor and context.

Listen to the results

const crossup = createStorefront({
  apiKey: "spk_…",
  connectionId: "cn_…",
  onSignalResult: (result, signal) => {
    // result.status: "accepted" | "duplicate" | "rejected"; result.reason if rejected
  },
  onSignalError: (error) => {
    // couldn't be built or was rejected.
  },
});

In tests, or before closing a shopping session on the server:

await crossup.flush();      // sends what's pending and waits. Never rejects.

If you don’t see it

What happens	What to do
Rejected with `unknown_decision`	Pass the recommendation as you got it, or its exact `decision_id`
`undefined` when calling `track.*`	The signal couldn’t be built: check `onSignalError`
No attributed sales	`cartId` is missing: without it the order can’t be tied to the recommendation

Signals and attribution

When to send each signal and what CrossUp measures with them.

Record signals via the API

The operation, with a playground.

​The methods

​A purchase isn’t a signal

​Listen to the results

​If you don’t see it

Signals and attribution

Record signals via the API

The methods

A purchase isn’t a signal

Listen to the results

If you don’t see it