Señales y atribución

Cada venta que CrossUp genera se prueba con dos cosas: lo que el comprador sumó desde una recomendación, que llega como señal, y la orden que cerró tu tienda. El navegador nunca dice que hubo compra: lo dice la orden.

Qué cuenta como venta atribuida

Es el valor de los productos que el comprador agregó desde una recomendación y efectivamente compró. La atribución se hace orden por orden. No cuentan:

el producto que el comprador ya había elegido;
las recomendaciones rechazadas;
las órdenes sin una recomendación aceptada.

Las siete señales

Señal	Qué pasó
`impression`	La recomendación se mostró
`click`	El comprador abrió un producto recomendado
`add_to_cart`	Sumó unidades de ese producto a su carrito
`remove_from_cart`	Lo sacó del carrito
`update_quantity`	Cambió las unidades; cero es sacarlo
`checkout_started`	Se fue al checkout. Registra el momento, no la venta
`dismiss`	Cerró la oferta sin tomarla

Cada señal lleva su propio cambio, nunca el carrito entero. No hay una señal de compra.

Cómo se ata la venta

Tu tienda manda su id de carrito (cart_id) al pedir la recomendación y en las señales. Con el SDK, una sola vez: la opción cartId.
Las señales de carrito dicen qué sumó el comprador desde cada recomendación.
La orden llega desde tu plataforma —la app de CrossUp o tu conector— con ese mismo id como external_id. CrossUp cruza la orden con lo sumado y atribuye las líneas que se compraron.

Sin cart_id la recomendación funciona igual, pero esa decisión no se puede atar a ninguna orden. Cómo tiene que venir la orden: El modelo canónico.

Cuándo avisar cada una

impression cuando la recomendación entra en pantalla, no cuando se genera.
click en el clic, antes de navegar; el SDK la manda aunque la página cambie.
add_to_cart con la cantidad que se sumó, no el total de la línea.
checkout_started cuando el comprador se va al checkout, una vez.

Cómo se mandan

Vos avisás y seguís: el SDK junta, manda y reintenta sin frenar la página. Cada track.* recibe la recomendación que mostraste (en la API, Decision: la lista de productos recomendados para ese momento).

const crossup = createStorefront({
  apiKey: "spk_…",
  connectionId: "cn_…",
  cartId: () => cart?.id,                         // el id del carrito de tu tienda
});

crossup.track.impression(decision);              // se mostró
crossup.track.click(decision, result);           // abrió un producto
crossup.track.addToCart(decision, result, { quantity: 2 }); // sumó dos unidades
crossup.track.checkoutStarted(decision);         // se fue al checkout

// Desde un servidor. Hasta 50 señales por envío.
batch := map[string]any{"signals": []map[string]any{{
    "signal_id":   newID(),       // sig_…, estable: reintentar no duplica
    "type":        "add_to_cart",
    "decision_id": decisionID,    // la decisión que se mostró
    "item_id":     itemID,
    "quantity":    2,             // las unidades que se sumaron
    "cart_id":     cartID,        // el id del carrito en tu tienda
    "occurred_at": now,           // RFC 3339, en UTC
}}}
// POST {base}/v1/connections/{cn}/storefront-signals · Authorization: Bearer spk_…

Reintentar es seguro: cada señal tiene un id estable y la repetida no se duplica. Cada una se responde sola, así que una mal armada no voltea el envío.

Qué vas a ver

Una respuesta por señal: aceptada, repetida o rechazada con motivo. En el SDK llegan a onSignalResult.

Lo que nunca viaja

El visitante es un id inventado por el SDK: nunca un mail, un teléfono ni el id de cliente de la plataforma.

Si no lo ves

Lo que pasa	Qué significa	Qué hacer
Rechazada con `unknown_decision`	La recomendación no es de esta tienda	Mandá la recomendación tal como la recibiste
Error «lote demasiado grande»	Más de 50 señales en un envío	Con la API, partilo; el SDK ya lo hace
Ninguna venta atribuida	Falta el `cart_id`, o la orden no llega con ese id	Mandá `cart_id` y revisá que la orden traiga el mismo como `external_id`

Reportar señales con el SDK

track.*: las siete señales y cuándo mandar cada una.

Registrar señales por API

La operación, con playground.

Empezar

Operar

Señales y atribución

Qué cuenta como venta atribuida

Las siete señales

Cómo se ata la venta

Cuándo avisar cada una

Cómo se mandan

Qué vas a ver

Lo que nunca viaja

Si no lo ves

Reportar señales con el SDK

Registrar señales por API

​Qué cuenta como venta atribuida

​Las siete señales

​Cómo se ata la venta

​Cuándo avisar cada una

​Cómo se mandan

​Qué vas a ver

​Lo que nunca viaja

​Si no lo ves

Reportar señales con el SDK

Registrar señales por API

Qué cuenta como venta atribuida

Las siete señales

Cómo se ata la venta

Cuándo avisar cada una

Cómo se mandan

Qué vas a ver

Lo que nunca viaja

Si no lo ves