/ Docs
Contents

Tracking storefront events

Nucleo learns from what shoppers do on your storefront: what they search, which products they view, what they put in the cart and what they buy. An installation connects one storefront to Nucleo. It gives you a public key and a snippet to paste into your theme. For Shopify stores, server-side webhooks add carts, checkouts and orders sent by Shopify itself.

Installations live in Catalog > Settings > Search > Installations. What they send shows up in Signal, in shopper profiles and in Queries. Only Owners and Admins can manage installations.

Note
Nothing is stored until the shopper grants consent. Without consent, no event is written.

Create an installation

Steps

  1. In Nucleo, go to Catalog > Settings > Search > Installations.
  2. Click New installation.
  3. In Name, type a name that says where it will live, such as the name of your store.
  4. In Allowed domains, list the domains the storefront runs on, one per line or separated by commas. Use lowercase hosts without a port; *.example.com is allowed. At least one domain is required.
  5. In Locales, select the languages the installation works in.
  6. Click Create.

The installation appears with its public key and its storefront snippet, ready to install.

Install the snippet on your storefront

Steps

  1. In Nucleo, go to Catalog > Settings > Search > Installations, and find the installation.
  2. In Storefront snippet, copy the code.
  3. In your storefront's theme, paste the code just before the closing </body> tag, and publish the theme.
  4. Check the installation end to end in Test events.

The line under the snippet shows the address the events are sent to. Once events arrive, the installation shows how many were stored, how many were rejected, and when it was last seen.

Note
The public key is visible to anyone who looks at your storefront's code. It only says which shop the events belong to. The allowed domains are what keep it from being used elsewhere.

Change domains, languages and Web Pixel events

In Catalog > Settings > Search > Installations, each installation card has these settings:

SettingWhat it does
Products & pricesThe sales channel the installation reads sellability and prices from. It's shown for information: an installation never has prices of its own.
LocalesThe languages the installation works in. Click a language to add or remove it; changes save at once.
Allowed domainsEvents from other domains are refused. Edit the list, and then click Save domains in the Unsaved changes bar, or Discard to undo. At least one domain is required.
Accept Shopify Web Pixel eventsCheckout pages don't run your theme's code, so the checkout start and purchase events come from a Shopify Web Pixel. Turn this on to accept them; with it off, those two events are refused.

Pause or resume an installation

Pausing stops an installation without removing the snippet from your theme.

Steps

  1. In Nucleo, go to Catalog > Settings > Search > Installations, and find the installation.
  2. Click Pause. The status changes to Paused: the storefront's events are refused and nothing is stored.
  3. To start again, click Resume. The status changes back to Active.

Rotate the public key

Rotate the key if you want to invalidate the one in your theme, for example after moving to a new storefront.

Steps

  1. In Nucleo, go to Catalog > Settings > Search > Installations, and find the installation.
  2. Next to Public key, click Rotate key.
  3. Click Rotate key again to confirm.
  4. Copy the new snippet and paste it into your theme in place of the old one.
Caution
The old key is refused immediately, with no grace period. Every storefront still carrying the old snippet stops sending events until you paste the new one.

Delete an installation

Steps

  1. In Nucleo, go to Catalog > Settings > Search > Installations, and find the installation.
  2. Click the trash icon.
  3. Click Delete installation to confirm.
Caution
The key stops working immediately and the snippet on your storefront stops sending. Events already stored are kept.

Connect Shopify webhooks

A browser script can be blocked or closed before it sends anything. Shopify webhooks can't: Shopify sends carts, checkouts and orders from its own server, signed, as they happen. They're also what ties a visitor to a customer at checkout. The Server-side (Shopify webhooks) panel, at the bottom of the Installations tab, manages them.

Steps

  1. In Nucleo, go to Catalog > Settings > Search > Installations.
  2. In Server-side (Shopify webhooks), check that App secret shows Set and Shopify credentials shows Connected. Both are needed.
  3. Click Register webhooks, and then click Register to confirm.

Nucleo subscribes to the cart, checkout and order topics on your Shopify store, pointing at the Callback URL shown in the panel. Subscriptions already in place are kept, and Shopify starts sending right away. The registration runs in the background: the outcome appears in the panel within a few seconds, and the badge changes to Subscribed with how many topics point at Nucleo.

Part of the panelWhat it shows
Subscriptions on ShopifyEvery webhook subscription on your store, marked Nucleo or Other app. A subscription marked Orphan · old Nucleo address points at an address Nucleo no longer uses. Remove Nucleo webhooks doesn't touch it: ask Nucleo support to remove it.
Received, last 7 daysWhat arrived per topic, when the last one arrived, and how many were processed or failed.

To stop, click Remove Nucleo webhooks and confirm. The removal is queued and its outcome appears in the panel within a few seconds. Only the subscriptions pointing at Nucleo are removed; other apps aren't touched, and what was already received is kept.

Note
If App secret shows Not set, contact Nucleo support: the Nucleo team sets it, and it never goes through this page. Shopify credentials come from your Shopify connection. The compliance webhooks are configured in your Shopify app settings with the same callback URL, because Shopify doesn't let apps register them automatically.

Considerations for event tracking

  • Installations collect events; they don't put Nucleo's search on your storefront. Site search isn't reachable from the storefront yet.
  • If demo mode is on, a Simulated installation appears. It has no key and no snippet, and it disappears when you turn demo mode off. See Preview Signal with demo mode.
  • Use a test code to check your own browsing without writing it into your real data.

Related articles