Skip to main content
The SDK is one script tag. It loads asynchronously, fetches the site’s settings, opens a websocket to the collector, and starts reading how the visitor moves. It sets no cookie on your domain; the visitor id lives in a NextIntent-owned frame.

​
The script tag

Put it in the <head> of every page. YOUR_SITE_ID is the site’s id from the console or from POST /v1/sdk. The bundle is served with long cache headers and the page learns about a new version from the settings response, so you never need to change the tag.

​
Allowed origins

A site has a list of allowed origins (https://www.example.com, https://example.com). The settings call, the cart beacon, the card routes and the collector’s handshake check the request’s Origin against that list, signed into the site’s token. A page on an origin not on the list gets a refusal and the SDK stays inactive. Set the list when creating the site, and change it with PATCH /v1/sdk/{id} (allowed_origins). All origins on one site must share a root domain; a second company’s domain goes on its own site. Staging hosts go on the list like any other origin.

​
What the SDK does on load

  1. GET /YOUR_SITE_ID/settings with the page’s Origin. The answer carries the site token, which captures are on, and the current version. A site that is switched off answers 418 { enabled: false } and the SDK stops there.
  2. Opens the visitor frame from iframe.nextintent.ai, which holds the visitor id in the frame’s own storage. A new browser gets a new random id; a returning one keeps its id.
  3. Connects to the collector with the site token, the visitor id and the page URL.
  4. Streams signals: page, scroll, click, interest (hover that settles), behavioral (stillness), submit, invalid_form, performance, disconnect. Each is small and sent as it happens.

​
Form signals

The SDK watches forms on the page. On submit it sends the field names and hashed values; on a validation message shown by the page it sends invalid_form with the field and the message text. Values are hashed on the page. Forms whose action points at a known tracker (analytics beacons) are ignored. Email fields are read only when the site has visitor identification enabled, which NextIntent for Shopify never does.

​
Confirming it works

  • In the console, the site shows connected once a visit has arrived.
  • GET /v1/sdk/{id}/install-check fetches your page from NextIntent’s side and reports whether the tag is present.
  • Load a page, open the cart, and stand still: a moment appears in GET /v1/sdk/{id}/moments within about 15 seconds.

​
Single-page apps

The SDK follows history changes and reconnects the collector on navigation, so a route change is a new page for the engine. Nothing to do on your side.