Instalar o Storefront SDK

@crossup/storefront é a única coisa que a sua loja precisa da CrossUp. Ele pede recomendações, lê o seu catálogo, leva um visitante inventado e manda os sinais em lotes, sem poder quebrar a sua página.

npm install @crossup/storefront

pnpm add @crossup/storefront

bun add @crossup/storefront

Roda no navegador e no servidor, com tipos e sem dependências. Está publicado no npm: @crossup/storefront.

Criar a instância

Uma por página. Só a chave e a conexão são obrigatórias.

import { createStorefront } from "@crossup/storefront";

export const crossup = createStorefront({
  apiKey: "spk_…",
  connectionId: "cn_…",
});

O que ele faz por você

O visitante: um id inventado, em cada requisição. Pode ser desligado, ficar só na memória ou ser substituído.
O contexto: página, referrer, idioma e tela. Não identifica ninguém.
A conexão: você configura uma vez, não em cada chamada.
Os sinais: entram na fila, são agrupados e reenviados sozinhos.

Tudo muda com as opções, e para começar não é preciso nenhuma.

As garantias

tryGetRecommendations devolve null se algo falhar. Nunca lança erro.
track.* não lança erro nem espera a rede: chame sem await.
Um sinal que falha por rede é reenviado sozinho, com o mesmo id.
Se o motor não responde, a recomendação volta vazia com motivo, não com erro.

O que você vai ver

// O momento, o lugar e o produto que o comprador está vendo.
const decision = await crossup.tryGetRecommendations({
  surface: "pdp",
  placementKey: "pdp-related",
  contextItemId: item.id,
});

console.log(decision?.decision_id, decision?.results.length);
// dec_… 3

Se você não vê

O que acontece	O que fazer
`null` e nenhuma requisição na aba Rede	Falta a chave ou a conexão na instância
`401` em cada requisição	A chave está mal copiada ou revogada. Gere outra no admin
`403` `forbidden_connection` em cada requisição	A conexão é de outra loja
`403` `forbidden_origin`	A chave não foi emitida para o domínio desta página. Gere outra em API & Agentes com o domínio da loja; desde `localhost` e sem navegador passa igual
`onVisitorError` em cada requisição	O navegador não deixa salvar (modo privado, cookies bloqueados). A requisição sai mesmo assim, sem visitante

Pedir recomendações

A requisição, e o que volta.

Visitante e contexto

O que viaja, o que não, e o que fazer sem consentimento.

​Criar a instância

​O que ele faz por você

​As garantias

​O que você vai ver

​Se você não vê