Instalar el Storefront SDK

@crossup/storefront es lo único que tu tienda necesita de CrossUp. Pide recomendaciones, lee tu catálogo, lleva un visitante inventado y manda las señales en lotes, sin poder cortar tu página.

npm install @crossup/storefront

pnpm add @crossup/storefront

bun add @crossup/storefront

Corre en el navegador y en el servidor, con tipos y sin dependencias. Está publicado en npm: @crossup/storefront.

Crear la instancia

Una por página. Sólo la clave y la conexión son obligatorias.

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

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

Lo que hace por vos

El visitante: un id inventado, en cada pedido. Se apaga, se deja en memoria o se reemplaza.
El contexto: página, referrer, idioma y pantalla. No identifica a nadie.
La conexión: la configurás una vez, no en cada llamada.
Las señales: se encolan, se agrupan y se reintentan solas.

Todo se cambia con las opciones, y para empezar no hace falta ninguna.

Las garantías

tryGetRecommendations devuelve null si algo falla. Nunca tira.
track.* no tira ni espera la red: llamalo sin await.
Una señal que falla por red se reintenta sola, con el mismo id.
Si el motor no contesta, la recomendación vuelve vacía con motivo, no con error.

Qué vas a ver

// El momento, el lugar y el producto que mira el comprador.
const decision = await crossup.tryGetRecommendations({
  surface: "pdp",
  placementKey: "pdp-related",
  contextItemId: item.id,
});

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

Si no lo ves

Lo que pasa	Qué hacer
`null` y ningún pedido en la pestaña Red	Falta la clave o la conexión en la instancia
`401` en cada pedido	La clave está mal copiada o revocada. Generá otra en el admin
`403` en cada pedido	La conexión es de otra tienda
`onVisitorError` en cada pedido	El navegador no deja guardar (modo privado, cookies bloqueadas). El pedido sale igual, sin visitante

Pedir recomendaciones

El pedido, y qué vuelve.

Visitante y contexto

Qué viaja, qué no, y qué hacer sin consentimiento.

​Crear la instancia

​Lo que hace por vos

​Las garantías

​Qué vas a ver

​Si no lo ves