Sinais e atribuição

Cada venda que a CrossUp gera é comprovada por duas coisas: o que o comprador adicionou a partir de uma recomendação, que chega como sinal, e o pedido que a sua loja fechou. O navegador nunca diz que houve compra: quem diz é o pedido.

O que conta como venda atribuída

É o valor dos produtos que o comprador adicionou a partir de uma recomendação e de fato comprou. A atribuição é feita pedido a pedido. Não contam:

o produto que o comprador já tinha escolhido;
as recomendações recusadas;
os pedidos sem uma recomendação aceita.

Os sete sinais

Sinal	O que aconteceu
`impression`	A recomendação foi mostrada
`click`	O comprador abriu um produto recomendado
`add_to_cart`	Adicionou unidades desse produto ao carrinho
`remove_from_cart`	Tirou o produto do carrinho
`update_quantity`	Mudou as unidades; zero é tirá-lo
`checkout_started`	Foi para o checkout. Registra o momento, não a venda
`dismiss`	Fechou a oferta sem aceitá-la

Cada sinal leva a sua própria mudança, nunca o carrinho inteiro. Não existe um sinal de compra.

Como a venda é ligada

A sua loja envia o id do carrinho (cart_id) ao pedir a recomendação e nos sinais. Com o SDK, uma vez só: a opção cartId.
Os sinais de carrinho dizem o que o comprador adicionou a partir de cada recomendação.
O pedido chega da sua plataforma —o app da CrossUp ou o seu conector— com esse mesmo id como external_id. A CrossUp cruza o pedido com o que foi adicionado e atribui as linhas compradas.

Sem cart_id a recomendação funciona igual, mas essa decisão não pode ser ligada a nenhum pedido. Como o pedido tem que vir: O modelo canônico.

Quando avisar cada um

impression quando a recomendação entra na tela, não quando é gerada.
click no clique, antes de navegar; o SDK o manda mesmo que a página mude.
add_to_cart com a quantidade adicionada, não o total da linha.
checkout_started quando o comprador vai para o checkout, uma vez.

Como eles são enviados

Você avisa e segue: o SDK junta, manda e tenta de novo sem travar a página. Cada track.* recebe a recomendação que você mostrou (na API, Decision: a lista de produtos recomendados para aquele momento).

const crossup = createStorefront({
  apiKey: "spk_…",
  connectionId: "cn_…",
  cartId: () => cart?.id,                         // o id do carrinho na sua loja
});

crossup.track.impression(decision);              // foi mostrada
crossup.track.click(decision, result);           // abriu um produto
crossup.track.addToCart(decision, result, { quantity: 2 }); // adicionou duas unidades
crossup.track.checkoutStarted(decision);         // foi para o checkout

// De um servidor. Até 50 sinais por envio.
batch := map[string]any{"signals": []map[string]any{{
    "signal_id":   newID(),       // sig_…, estável: tentar de novo não duplica
    "type":        "add_to_cart",
    "decision_id": decisionID,    // a decisão que foi mostrada
    "item_id":     itemID,
    "quantity":    2,             // as unidades adicionadas
    "cart_id":     cartID,        // o id do carrinho na sua loja
    "occurred_at": now,           // RFC 3339, em UTC
}}}
// POST {base}/v1/connections/{cn}/storefront-signals · Authorization: Bearer spk_…

Tentar de novo é seguro: cada sinal tem um id estável e o repetido não duplica. Cada um é respondido sozinho, então um sinal malformado não derruba o envio.

O que você vai ver

Uma resposta por sinal: aceito, repetido ou recusado com motivo. No SDK, elas chegam em onSignalResult.

O que nunca viaja

O visitante é um id inventado pelo SDK: nunca um e-mail, um telefone nem o id de cliente da plataforma.

Se você não vê

O que acontece	O que significa	O que fazer
Recusado com `unknown_decision`	A recomendação não é desta loja	Mande a recomendação como você a recebeu
Erro “lote grande demais”	Mais de 50 sinais num envio	Com a API, divida; o SDK já faz isso
Nenhuma venda atribuída	Falta o `cart_id`, ou o pedido não chega com esse id	Mande `cart_id` e confira que o pedido traga o mesmo como `external_id`

Reportar sinais com o SDK

track.*: os sete sinais e quando mandar cada um.

Registrar sinais pela API

A operação, com playground.

Começar

Operar

Sinais e atribuição

O que conta como venda atribuída

Os sete sinais

Como a venda é ligada

Quando avisar cada um

Como eles são enviados

O que você vai ver

O que nunca viaja

Se você não vê

Reportar sinais com o SDK

Registrar sinais pela API

​O que conta como venda atribuída

​Os sete sinais

​Como a venda é ligada

​Quando avisar cada um

​Como eles são enviados

​O que você vai ver

​O que nunca viaja

​Se você não vê

Reportar sinais com o SDK

Registrar sinais pela API

O que conta como venda atribuída

Os sete sinais

Como a venda é ligada

Quando avisar cada um

Como eles são enviados

O que você vai ver

O que nunca viaja

Se você não vê