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, 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);

// On the purchase page: the decision's products that made it into the order.
crossup.track.purchase(decision, { orderExternalId: order.id, items: [{ result, quantity: 2 }] });

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
`purchase`	`purchase`	`orderExternalId` (the order id in your store) and `items[]`
`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, and occurredAt, now by default. 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`

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

​Listen to the results

​If you don’t see it

Signals and attribution

Record signals via the API

The methods

Listen to the results

If you don’t see it