Apache Unomi tracker
A JavaScript tracker library for Apache Unomi.
Installation
yarn add apache-unomi-tracker
Unomi also ships this tracker, repackaged, at /tracker/unomi-web-tracker.min.js on the server.
A page can also load the browser build (dist/apache-unomi-tracker.umd.js) directly; it defines
window['apache-unomi-tracker'] and needs no polyfill.
Usage
import { useTracker } from 'apache-unomi-tracker';
const tracker = useTracker();
const digitalData = {
scope: 'my-site',
site: { siteInfo: { siteID: 'my-site' } },
page: {
pageInfo: {
pageID: 'home',
pageName: document.title,
pagePath: document.location.pathname,
destinationURL: document.location.origin + document.location.pathname,
language: 'en',
categories: [],
tags: []
},
consentTypes: []
},
events: [],
wemInitConfig: {
contextServerUrl: 'https://cdp.example.com',
timeoutInMilliseconds: 1500,
contextServerCookieName: 'context-profile-id',
activateWem: true,
trackerSessionIdCookieName: 'wem-session-id',
trackerProfileIdCookieName: 'wem-profile-id'
// apiKey: 'YOUR_PUBLIC_API_KEY' // Unomi 4 multi-tenant only, see below
}
};
// The tracker does not start without a session ID cookie
if (tracker.getCookie(digitalData.wemInitConfig.trackerSessionIdCookieName) == null) {
tracker.setCookie(digitalData.wemInitConfig.trackerSessionIdCookieName, tracker.generateGuid(), 1);
}
tracker.initTracker(digitalData);
tracker.startTracker();
Configuring for your Unomi server
The same tracker works with every Unomi version. Only the configuration changes.
| Unomi server | apiKey | Data goes to |
|---|
| 2.x or 3.x | Leave it out | The server (no tenants) |
| 4.x in single-tenant compatibility mode | Leave it out (a key is ignored) | The default tenant |
| 4.x multi-tenant | The tenant's public API key | That tenant |
Without a key, a Unomi 4 server that is not in compatibility mode answers 401 Unauthorized.
Things to know when you set apiKey:
- Use the tenant's public key only, never its private key. The page configuration is visible to every visitor.
- The tracker sends the key in the
X-Unomi-Api-Key header. A custom header makes the browser send a CORS preflight request before the real one when Unomi is on another origin.
- Unomi 2.x and 3.x servers accept the header and ignore it, so a page that sets a key still works against them.
apiKey and sendCredentials need tracker 2.0.0 or later.
Cookies when Unomi is on another origin
By default the tracker sends its requests with cookies, so that Unomi can recognise a returning visitor. When the website and Unomi are on different origins (another subdomain counts), the Unomi server must list the website origin, or the browser blocks the answers:
- Unomi 4: in
UNOMI_PUBLIC_CORS_ALLOWED_ORIGINS, or in the tenant's publicCorsAllowedOrigins property.
- Unomi 2.x and 3.x: the public endpoints accept cookies from any origin.
If the site does not need to recognise visitors, set sendCredentials: false. Requests are then sent without cookies and work with the default server settings, but Unomi no longer sees the profile cookie:
- Unomi 4 creates a new anonymous profile on every request.
- Unomi 2.x and 3.x find the profile through the session only, so it lasts for the session.
See the web tracker reference in the Unomi manual for details.
Deploying the website and Unomi
Unomi recognises a returning visitor by its profile cookie (context-profile-id), which it sets on its own host. Whether browsers keep that cookie depends on where Unomi is, compared with the website:
| Setup | Example | Profile cookie |
|---|
| Same host, Unomi behind a reverse proxy | contextServerUrl: 'https://www.example.com/unomi' | First-party: kept by all browsers. Recommended |
| Another host on the same domain | www.example.com and cdp.example.com | Same site: kept by all browsers. Unomi 4 must list the website origin, see above |
| Another domain | www.example.com and unomi.example.net | Third-party: blocked by Safari, and by Chrome in private windows or when the user blocks third-party cookies. Firefox keeps a separate one for each website |
When the browser blocks the profile cookie, Unomi sees the visitor as with sendCredentials: false (see above): a new profile on each request with Unomi 4, a profile for the session only with Unomi 2.x and 3.x. The tracker cannot keep the profile itself yet: it copies the profile ID into its own cookie (trackerProfileIdCookieName), on the website's host, but does not send it to Unomi (UNOMI-733).
Configuration options
Options in wemInitConfig:
This is the beginning of the README. Read the rest at the original. Read the full README ↗
