Reportar sinais

Cada track.* registra um sinal e o SDK o manda sozinho. Nunca lança erro nem espera a rede: chame sem await, no handler do clique.

Os métodos

Todos recebem a recomendação (na API, Decision: a lista de produtos recomendados para aquele momento) ou seu decision_id. Exceto a impressão e o checkout, também o resultado (ou seu 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);

Método	Sinal	Quando, e o que importa
`impression`	`impression`	Quando entra na tela, não quando é gerada
`click`	`click`	Ao abrir um produto, antes de navegar. O SDK garante que saia
`addToCart`	`add_to_cart`	`quantity`: as unidades somadas, não o total
`removeFromCart`	`remove_from_cart`	Ao tirá-lo do carrinho
`updateQuantity`	`update_quantity`	`quantity`: as unidades que ficam; 0 remove a linha
`checkoutStarted`	`checkout_started`	Ao ir para o checkout, uma vez. Registra o momento, não a venda
`dismiss`	`dismiss`	Ao fechar a oferta sem aceitá-la. Sem resultado, vai o primeiro

Cada método devolve o id do sinal, ou undefined se não deu para montá-lo (onSignalError diz por quê). Aceitam signalId, um id próprio e estável; cartId, que substitui o da instância; e occurredAt, por padrão agora.

A compra não é um sinal

Quem diz que uma venda foi fechada é o pedido da sua loja, não o navegador. Para a CrossUp ligá-lo à recomendação, passe o id do carrinho uma vez, ao criar a instância; ele viaja sozinho em cada pedido e cada sinal:

const crossup = createStorefront({
  apiKey: "spk_…",
  connectionId: "cn_…",
  cartId: () => cart?.id, // uma função: o carrinho ganha seu id com o primeiro produto
});

Como ele é cruzado com o pedido: Sinais e atribuição.

checkoutStarted e cartId ainda não estão na versão publicada no npm (0.1.0), que traz um track.purchase que o contrato já não aceita. Até a próxima versão, mande checkout_started e cart_id pela API.

Cada sinal leva sozinho o visitante e o contexto, sem dados pessoais: Visitante e contexto.

Escutar os resultados

const crossup = createStorefront({
  apiKey: "spk_…",
  connectionId: "cn_…",
  onSignalResult: (result, signal) => {
    // result.status: "accepted" | "duplicate" | "rejected"; result.reason se foi rejeitado
  },
  onSignalError: (error) => {
    // não deu para montar ou foi rejeitado.
  },
});

Em testes, ou antes de fechar uma sessão de compra no servidor:

await crossup.flush();      // manda o pendente e espera. Nunca rejeita.

Se você não vê

O que acontece	O que fazer
Rejeitado com `unknown_decision`	Passe a recomendação como veio, ou seu `decision_id` exato
`undefined` ao chamar `track.*`	Não deu para montar o sinal: olhe `onSignalError`
Nenhuma venda atribuída	Falta `cartId`: sem ele o pedido não pode ser ligado à recomendação

Sinais e atribuição

Quando mandar cada sinal e o que a CrossUp mede com eles.

Registrar sinais pela API

A operação, com playground.

​Os métodos

​A compra não é um sinal

​Escutar os resultados

​Se você não vê

Sinais e atribuição

Registrar sinais pela API

Os métodos

A compra não é um sinal

Escutar os resultados

Se você não vê