This is an automated email from the ASF dual-hosted git repository.
sergehuber pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/unomi.git
The following commit(s) were added to refs/heads/master by this push:
new e1bbb6a89 UNOMI-1019: Document how to configure the web tracker for
each Unomi version (#925)
e1bbb6a89 is described below
commit e1bbb6a89d375cdd800b151903330719181f2f2c
Author: Serge Huber <[email protected]>
AuthorDate: Tue Oct 27 10:34:08 2026 +0100
UNOMI-1019: Document how to configure the web tracker for each Unomi
version (#925)
Co-authored-by: Claude Opus 5.5 <[email protected]>
---
manual/src/main/asciidoc/configuration.adoc | 2 +-
.../main/asciidoc/javascript-tracker-guide.adoc | 2 +-
.../asciidoc/migrations/migrate-3.0-to-4.0.adoc | 5 ++-
manual/src/main/asciidoc/tutorial.adoc | 16 ++++----
manual/src/main/asciidoc/web-tracker.adoc | 46 ++++++++++++++++++----
5 files changed, 50 insertions(+), 21 deletions(-)
diff --git a/manual/src/main/asciidoc/configuration.adoc
b/manual/src/main/asciidoc/configuration.adoc
index ddb1408fd..80d7c39dc 100644
--- a/manual/src/main/asciidoc/configuration.adoc
+++ b/manual/src/main/asciidoc/configuration.adoc
@@ -716,7 +716,7 @@ Other behaviour that changed:
===== Tracker without cookies
-A deployment that does not need the visitor cookie can set `sendCredentials:
false` in the tracker's `wemInitConfig` (see <<_unomi_web_tracker_reference,the
web tracker>>). Requests are then sent without cookies and work with the
default settings, but each request starts a new anonymous profile.
+A deployment that does not need the visitor cookie can set `sendCredentials:
false` in the tracker's `wemInitConfig` (tracker 2.0.0 or later, see
<<_unomi_web_tracker_reference,the web tracker>>). Requests are then sent
without cookies and work with the default settings, but each request starts a
new anonymous profile.
=== Scripting security
diff --git a/manual/src/main/asciidoc/javascript-tracker-guide.adoc
b/manual/src/main/asciidoc/javascript-tracker-guide.adoc
index 04ecec077..daca14e82 100644
--- a/manual/src/main/asciidoc/javascript-tracker-guide.adoc
+++ b/manual/src/main/asciidoc/javascript-tracker-guide.adoc
@@ -18,7 +18,7 @@ This guide explains how to implement a basic JavaScript
tracker for Apache Unomi
[NOTE]
====
-Apache Unomi provides an official web tracker (see
<<_unomi_web_tracker_reference,Unomi Web Tracker reference>>) that handles many
of these details automatically. This guide is useful if you need a custom
implementation or want to understand how the tracker works internally.
+Apache Unomi provides an official web tracker (see
<<_unomi_web_tracker_reference,Unomi Web Tracker reference>>) that handles many
of these details automatically, including the API key (see
<<_web_tracker_server_versions,Configuring the tracker for your Unomi
server>>). This guide is useful if you need a custom implementation or want to
understand how the tracker works internally.
====
==== Prerequisites
diff --git a/manual/src/main/asciidoc/migrations/migrate-3.0-to-4.0.adoc
b/manual/src/main/asciidoc/migrations/migrate-3.0-to-4.0.adoc
index 3508ff2b8..de73b7384 100644
--- a/manual/src/main/asciidoc/migrations/migrate-3.0-to-4.0.adoc
+++ b/manual/src/main/asciidoc/migrations/migrate-3.0-to-4.0.adoc
@@ -220,7 +220,7 @@ Anonymous browsing, personas and profile overrides are
otherwise unchanged, and
===== Migrating a client
-* Browser trackers need no change: the browser sends the cookie automatically,
and the response still carries `profileId` and `sessionId`.
+* Browser trackers need no change for this: the browser sends the cookie
automatically, and the response still carries `profileId` and `sessionId`. They
do need the tenant's public API key; for the Unomi web tracker, see
<<_web_tracker_server_versions,Configuring the tracker for your Unomi server>>.
* A backend that named a profile through body `profileId` while authenticating
with a *public* key must switch to a tenant private key, or to system
administrator credentials. Until it does, the server logs a `WARN` naming the
ignored `profileId` on every such request.
* A client that supplied a session id it did not own now finds `sessionId`
absent from the response. Treat that as "start a new session" and generate a
fresh id rather than replaying the old one.
@@ -498,6 +498,7 @@ console (port 8102) is not covered by that check.
===== Migration checklist for client applications
+* Unomi web tracker: update to version 2.0.0 or later and set `apiKey` to the
tenant's public API key (see <<_web_tracker_server_versions,Configuring the
tracker for your Unomi server>>).
* Browser / tracker clients: ensure cookies are sent (`withCredentials` /
same-site setup); list every website origin that calls Unomi from another
origin in `UNOMI_PUBLIC_CORS_ALLOWED_ORIGINS` or in its tenant's
`publicCorsAllowedOrigins` property (and, for another site, use HTTPS with
`SameSite=None`, or serve Unomi from the website's origin); stop treating body
`profileId` as authoritative for public calls.
* Headless or mobile public clients that stored a UUID and posted it only in
the body: switch to sending the profile cookie, or call with a **private key**
when you intentionally bind a profile.
* Login / merge flows: emit merge-triggering events from a trusted server-side
caller after real authentication — not from the public key alone.
@@ -558,7 +559,7 @@ Unomi 4.0 does **not** provide a separate "3.0
compatibility mode" system proper
==== Option 1: Update clients to 4.0 authentication (recommended)
-Adopt tenant public API keys for public endpoints and tenant private keys or
JAAS for administrative work. See <<_multitenancy,Multi-tenancy>> and the
authentication examples in this guide.
+Adopt tenant public API keys for public endpoints and tenant private keys or
JAAS for administrative work. See <<_multitenancy,Multi-tenancy>> and the
authentication examples in this guide. For the Unomi web tracker, set `apiKey`;
see <<_web_tracker_server_versions,Configuring the tracker for your Unomi
server>>.
==== Option 2: single-tenant compatibility mode (2.x clients only)
diff --git a/manual/src/main/asciidoc/tutorial.adoc
b/manual/src/main/asciidoc/tutorial.adoc
index ff0ceb503..73e933336 100644
--- a/manual/src/main/asciidoc/tutorial.adoc
+++ b/manual/src/main/asciidoc/tutorial.adoc
@@ -18,11 +18,7 @@ In this tutorial we will guide through the basic steps of
getting started with a
If you prefer to use existing HTML and Javascript rather than building your
own, all the code we feature in this tutorial is extracted from our tracker
sample which is available here:
https://github.com/apache/unomi/blob/master/extensions/web-tracker/wab/src/main/webapp/index.html
. However you will still need to use the REST API calls to create the scope
and rule to make it all work.
-IMPORTANT: On Unomi **4.0**, `/cxs/context.json` and `/cxs/eventcollector`
require a tenant **public** API key.
-The bundled `unomi-web-tracker` does not yet send `X-Unomi-Api-Key`. For this
tutorial, either:
-
-* Enable <<_v2_compatibility_mode,V2 compatibility mode>> for local learning
(public endpoints work without API keys), **or**
-* Use the NPM tracker / custom fetch wrappers that set `X-Unomi-Api-Key` (see
<<_javascript_tracker_guide,JavaScript tracker guide>>), after creating a
tenant and regenerating keys (see <<_multitenancy,Multi-tenancy>>).
+IMPORTANT: On Unomi **4.0**, `/cxs/context.json` and `/cxs/eventcollector`
require a tenant **public** API key. Set it as `apiKey` in the tracker's
`wemInitConfig`, as in the snippets below (tracker 2.0.0 or later). Remove the
`apiKey` line for Unomi 2.x or 3.x, or if you enable
<<_v2_compatibility_mode,single-tenant compatibility mode>>. See
<<_web_tracker_server_versions,Configuring the tracker for your Unomi server>>.
To obtain the key, create a tenant and regenerate its keys (see <<_ [...]
Create a scope and rules with tenant private-key or JAAS admin authentication
as shown below.
@@ -65,7 +61,6 @@ This will only load the tracker. To initialize it use a
snippet like the followi
"categories": [],
"tags": []
},
- "attributes": {},
"consentTypes": []
},
"events": [],
@@ -75,7 +70,9 @@ This will only load the tracker. To initialize it use a
snippet like the followi
"contextServerCookieName": "context-profile-id",
"activateWem": true,
"trackerSessionIdCookieName":
"unomi-tracker-test-session-id",
- "trackerProfileIdCookieName":
"unomi-tracker-test-profile-id"
+ "trackerProfileIdCookieName":
"unomi-tracker-test-profile-id",
+ // Unomi 4 multi-tenant only: the tenant's public API key
+ "apiKey": "YOUR_PUBLIC_API_KEY"
}
}
@@ -155,7 +152,6 @@ import {useTracker} from "apache-unomi-tracker";
"categories": [],
"tags": []
},
- "attributes": {},
"consentTypes": []
},
"events": [],
@@ -165,7 +161,9 @@ import {useTracker} from "apache-unomi-tracker";
"contextServerCookieName": "context-profile-id",
"activateWem": true,
"trackerSessionIdCookieName": "unomi-tracker-test-session-id",
- "trackerProfileIdCookieName": "unomi-tracker-test-profile-id"
+ "trackerProfileIdCookieName": "unomi-tracker-test-profile-id",
+ // Unomi 4 multi-tenant only: the tenant's public API key
+ "apiKey": "YOUR_PUBLIC_API_KEY"
}
}
diff --git a/manual/src/main/asciidoc/web-tracker.adoc
b/manual/src/main/asciidoc/web-tracker.adoc
index 4c874ece6..80260b4ae 100644
--- a/manual/src/main/asciidoc/web-tracker.adoc
+++ b/manual/src/main/asciidoc/web-tracker.adoc
@@ -16,16 +16,46 @@
In this section of the documentation, more details are provided about the web
tracker provided by Unomi.
-==== Authentication (Unomi 4.0)
+[#_web_tracker_server_versions]
+==== Configuring the tracker for your Unomi server
-Public context and event endpoints require a tenant public API key
(`X-Unomi-Api-Key`) unless <<_v2_compatibility_mode,V2 compatibility mode>> is
enabled.
+The same tracker works with Unomi 2.x, 3.x and 4.x. Only its configuration
changes: on a multi-tenant Unomi 4 server, set `apiKey` in `wemInitConfig` to
the tenant's public API key.
-The built-in WAB tracker sample does **not** currently attach that header. For
production 4.0 deployments:
+[cols="1,1,1",options="header"]
+|===
+|Unomi server
+|`apiKey` in `wemInitConfig`
+|Data goes to
-* Prefer the NPM package / custom integration that can set `X-Unomi-Api-Key`
(see <<_javascript_tracker_guide,JavaScript tracker guide>>), or
-* Enable V2 compatibility mode only as a temporary migration aid.
+|2.x or 3.x
+|Leave it out
+|The server (no tenants)
-Create a tenant and obtain plaintext public/private keys via `POST
/cxs/tenants/{id}/apikeys` before integrating a site. See
<<_multitenancy,Multi-tenancy>> and the <<_unomi_web_tracking_tutorial,web
tracking tutorial>>.
+|4.x in <<_v2_compatibility_mode,single-tenant compatibility mode>>
+|Leave it out (a key is ignored)
+|Tenant `default`
+
+|4.x multi-tenant
+|The tenant's *public* API key
+|That tenant
+|===
+
+[source,javascript]
+----
+ "wemInitConfig": {
+ "contextServerUrl": "https://cdp.example.com";,
+ ...
+ "apiKey": "YOUR_PUBLIC_API_KEY"
+ }
+----
+
+The tracker sends the key in the `X-Unomi-Api-Key` header on `context.json`
and `eventcollector` requests. Without a key, a Unomi 4 server that is not in
compatibility mode answers `401`.
+
+* Use the tenant's *public* key only, never its private key: the page
configuration is visible to every visitor. The public key identifies the
tenant; the tracker does not need a tenant ID.
+* A custom header makes the browser send a CORS preflight request before each
request 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 with them.
+* Create the tenant and obtain its plaintext keys with `POST
/cxs/tenants/{id}/apikeys` before integrating a site. See
<<_multitenancy,Multi-tenancy>>.
+
+`apiKey` and `sendCredentials` need version 2.0.0 or later of the tracker (the
`apache-unomi-tracker` NPM package). Earlier versions of the tracker bundled at
`/tracker/unomi-web-tracker.js` do not send the key; use compatibility mode
with them.
==== Custom events
@@ -196,7 +226,7 @@ In order to track profiles, an identifier must be stored in
the browser so that
Unomi's web tracker uses 3 cookies in the tracker by default:
- server profile ID, called `context-profile-id` by default, that is sent from
the Unomi server
-- web tracker profile ID, called `web-profile-id` by default (this is a copy
of the server profile ID that can be managed by the tracker directly)
+- web tracker profile ID, called `wem-profile-id` by default (this is a copy
of the server profile ID that can be managed by the tracker directly)
- web tracker session ID, called `wem-session-id` by default
It is possible to change the name of these cookie by passing the following
properties to the start's initialization:
@@ -213,7 +243,7 @@ It is possible to change the name of these cookie by
passing the following prope
Please note however that the `contextServerCookieName` will also have to be
changed in the server configuration in order for it to work. See the
<<_configuration,Configuration>> section for details on how to do this.
-The tracker sends requests with cookies. When the website and Unomi are on
different origins, another subdomain included (`www.example.com` and
`cdp.example.com`), list the website origin on the server
(`UNOMI_PUBLIC_CORS_ALLOWED_ORIGINS`) or in the tenant's
`publicCorsAllowedOrigins` property; otherwise the browser blocks the responses
and Unomi does not use the visitor cookie. A website served from the same
origin as Unomi, through a reverse proxy, needs no list. A website on another s
[...]
+The tracker sends requests with cookies. When the website and Unomi are on
different origins, another subdomain included (`www.example.com` and
`cdp.example.com`), list the website origin on the server
(`UNOMI_PUBLIC_CORS_ALLOWED_ORIGINS`) or in the tenant's
`publicCorsAllowedOrigins` property; otherwise the browser blocks the responses
and Unomi does not use the visitor cookie. A website served from the same
origin as Unomi, through a reverse proxy, needs no list. A website on another s
[...]
For session tracking, it is important to provide a value for the cookie
otherwise the tracker will not initialize (a message is displayed in the
console that explains that the session cookie is missing). Here is the code
excerpt from the initialization code used in the tutorial that creates the
initial cookie value.
