Send user ids for known users

Known users let Insights Orbit follow a signed-in person across days and devices, for funnels across days and for retention. They come with the Enterprise plan, and an Admin switches them on per site under Site settings, Known users. Ids sent to a site without it are dropped. See Known users for what it means for your organisation.

From the browser

Add data-known-users to the script tag. Without it, insights.identify does nothing:

<script defer data-site="SITE_KEY" data-known-users src="https://api.bifrostorbit.com/insights/v1/script.js"></script>

Once someone has signed in, pass their id:

window.insights?.identify('customer-1042');

Every page view and event after that carries the id. Call identify(null) when they sign out.

• The script keeps the id in memory only, never in the browser's storage, so call identify on every page load while the person is signed in. On a website that changes pages without reloading, once per load is enough.
• Ids can be up to 128 characters. Use an id that means nothing outside your systems, such as a customer number, never an email address.
• If your code may run before the script has loaded, queue the call: window.insights = window.insights || { q: [] }; window.insights.q.push(['identify', 'customer-1042']).

CmsInsights in the CMS Orbit SDKs has no option for data-known-users. Use your own script tag on websites that send user ids.

From a server

Add userId to each event you send to the server API:

{ "site": "SITE_KEY", "events": [{ "id": "order-1042", "name": "Order paid", "userId": "customer-1042", "revenue": 1240, "currency": "EUR" }] }

A funnel counted by known users can then start with a page view in the browser and end with a payment your server confirmed.

What is stored

Insights Orbit never stores the id. It keeps person, a scrambled form made with a key that belongs to your organisation, the same for every event of that person. The raw event API, GraphQL and the S3 export give person, never the id.

Admins can download or erase one person's events under Known users, by the id your website sends.