Skip to main content

​
Why this exists

The SDK path asks you to render recommendations yourself and then send events back. That is two integrations, a backend to hold your credentials, and a mapping between your product ids and ours. The embed collapses all of it. The widget that draws the recommendations is the widget that reports which ones were seen and clicked, so behavioural data arrives as a by-product of showing recommendations rather than as a prerequisite for getting any.
That is the whole integration.

​
Get a publishable key

1

Open Security

In the console, go to Security and find Embed key.
2

List your origins

Add every origin that will render the widget, including staging. A key with no origins does nothing.
3

Copy the snippet

The console gives you the script tag with your key already in it.
A publishable key (nsl_pk_...) is designed to be readable by anyone who views your page source. It can only read recommendations and report impressions - it can never administer your workspace, read your catalogue, or create credentials. This is not the same kind of secret as your Client Secret, and it is the only NeuronSearchLab credential that belongs in a browser.
Never put a Client Secret or an nsl_ secret key in browser code. Those grant full access to your workspace. Publishable keys exist precisely so you never have to.

​
Placeholders

auto is why no integration code is needed. Your catalogue is keyed on canonical URLs, so the page already knows which item it is - you never map your ids onto ours. Placeholders added after load are picked up automatically, so single-page apps work without re-initialising anything.

​
Styling

The strip renders in a shadow root, so your stylesheet cannot break it and it cannot leak styles into your page. CSS custom properties cross that boundary and are the supported way to restyle it:

​
Which URL to load

Subresource integrity and automatic updates cannot coexist on one URL, so both are offered rather than pretending otherwise. Per-version integrity hashes are published with each release.

​
What it sends

  • A recommendation request with the page’s canonical URL and a random first-party visitor id. Your key travels as a header, never in the URL.
  • Impressions, once a card has been at least 50% visible for two seconds. Scrolling past quickly is not an impression, and scrolling back does not double-count.
  • Clicks, delivered with sendBeacon so they survive the navigation.
The widget never intercepts or delays a click. Your navigation happens exactly as it would without it. No cookies, no third-party storage, no personal data. Visitor and session ids are random values in first-party localStorage and sessionStorage. Where storage is unavailable - private browsing, blocked site data - the widget still works and simply does not remember the visitor between pages.

​
Events it will not send

The embed reports view and click only. purchase carries the highest weight in training and cannot be verified from a browser, so the API rejects it from a publishable key. Send conversions from your server with the Events API, or import them with a backfill. Every event is also checked against the recommendations we actually served, so a key copied from your page source cannot be used to invent engagement for arbitrary items.

​
Quota

Embed traffic is metered separately from API requests, because a recommendation strip makes one request per pageview. When the allowance runs out the widget keeps working and serves cached results, with X-NSL-Quota: exceeded on the response. It does not start failing on your live site.

​
Failure behaviour

Every failure path renders nothing and leaves the page untouched. The script sits in your critical render path, so it never throws, never blocks, and never shows an error to your visitors. It is under 4 kB gzipped.