Send storefront events

The Collector receives what shoppers do on your storefront — page and product views, searches, cart changes, checkout and purchase — and turns it into the signals Nucleo Catalog uses for search ranking, recommendations and the Shoppers section. It only stores events of shoppers who granted consent.

1. In Nucleo, go to Settings > Catalog > Search > Installations (owners and admins).
2. Create an installation and add the domains your storefront runs on (for example shop.acme.example; *.acme.example covers every subdomain).
3. Copy the snippet with your public key and paste it into your theme.

The hosted script nucleo.js sends page and product views, searches and cart changes on its own, waits for consent and batches events. On Shopify it reads consent from the store's own privacy banner, and the checkout Web Pixel adds checkout and purchase events when you enable it on the installation. A visitor whose browser sends Global Privacy Control is always treated as denied.

To check that everything is wired, call the configuration endpoint from your storefront's domain:

curl "https://api-catalog.nucleoplatform.com/api/collect/v1/config?key=$NUCLEO_COLLECTOR_KEY" \
  -H "Origin: https://shop.acme.example"

Nothing is written without consent. Every batch carries the visitor's consent state, and changes are reported to POST /consent:

• granted — events are stored; the purposes you pass (analytics, personalisation…) decide what they are used for.
• denied or revoked — Nucleo deletes what it knows about that visitor and keeps only a hashed tombstone for 30 days.
• pending — nothing is written or counted.

Outside Shopify, wire your consent banner to the script, so that every change reaches Nucleo:

// when the shopper accepts
nucleo.consent("granted", ["analytics", "personalisation"]);

// when the shopper refuses or withdraws consent
nucleo.consent("denied");

// calls made before nucleo.js has loaded are queued
window.nucleoq = window.nucleoq || [];
nucleoq.push(["consent", "granted", ["analytics"]]);

The script also exposes nucleo.track(kind, data) for events it cannot see on its own, nucleo.search(query, results) and nucleo.flush().

Wire it so that every change reaches Nucleo. A shopper's identity (to link events to a customer) is accepted only as a reference signed by your store, and only when the shopper granted personalisation.

Headless storefronts and apps can call the Collector directly. Browsers must send the body as text/plain with the key in the body: that makes the call a CORS simple request, without a preflight.

navigator.sendBeacon(
  "https://api-catalog.nucleoplatform.com/api/collect/v1/events",
  new Blob(
    [
      JSON.stringify({
        key: "pk_3f9a1c7e5b2d4f60a8c1e9b7d3f5a2c4",
        v: 1,
        sentAt: new Date().toISOString(),
        visitor: { id: visitorId, consent: "granted", purposes: ["analytics"] },
        events: [
          { uid: crypto.randomUUID().slice(0, 12), kind: "product_view", product: { sku: "TEE-BLK-M" } },
        ],
      }),
    ],
    { type: "text/plain" },
  ),
);

• Up to 50 events and 64 KB per batch.
• Give each event a random uid: resending it is harmless, it is counted as a duplicate.
• Events can be up to 7 days old; Nucleo corrects the browser's clock if sentAt is set.
• The seven kinds and the fields each accepts are in the events reference.

In Nucleo, go to Catalog > Shoppers > Test events to get a test code. Add it as test to a batch: Nucleo validates everything and answers as usual, but writes nothing.