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 6b14cdd4f [UNOMI-1064] Explain the web tracker upgrade in the manual
(#962)
6b14cdd4f is described below
commit 6b14cdd4fbef1667ae6e49ce0733db8fcbc5988f
Author: Serge Huber <[email protected]>
AuthorDate: Fri Nov 13 19:21:48 2026 +0100
[UNOMI-1064] Explain the web tracker upgrade in the manual (#962)
---
.../asciidoc/migrations/migrate-3.0-to-4.0.adoc | 8 +++--
.../asciidoc/migrations/v2-compatibility-mode.adoc | 4 ++-
manual/src/main/asciidoc/tutorial.adoc | 2 +-
manual/src/main/asciidoc/web-tracker.adoc | 36 ++++++++++++++++++++--
manual/src/main/asciidoc/whats-new.adoc | 9 ++++++
5 files changed, 52 insertions(+), 7 deletions(-)
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 96c6c75cf..40885bdc5 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
@@ -237,7 +237,7 @@ Anonymous browsing, personas and profile overrides are
otherwise unchanged, and
===== Migrating a client
-* 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>>.
+* Browser trackers need no change for the profile cookie: the browser sends
it, and the response still carries `profileId` and `sessionId`. They do need
the tenant's public API key once you leave compatibility mode. The Unomi web
tracker sends that key from version 2.0.0. Tracker 1.x cannot. See
<<_upgrading_the_web_tracker,Upgrading the tracker from 1.x to 2.0>> and
<<_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.
@@ -531,7 +531,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>>).
+* Unomi web tracker: use version 2.0.0 or later. On a multi-tenant server, set
`apiKey` to the tenant's public API key. Tracker 1.x cannot send that key, so
leave <<_v2_compatibility_mode,single-tenant compatibility mode>> on until the
page is updated. The same configuration still works on Unomi 2.x, 3.x, and on
Unomi 4 in that mode. After the upgrade, clicks that 1.x missed are recorded,
and the page's own click handlers run once per click. See
<<_upgrading_the_web_tracker,Upgrading the [...]
* 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.
@@ -566,6 +566,7 @@ The sections above cover authentication and client-facing
hardening. The lists b
* Creating a profile without an `itemId` is refused.
* Condition validation failures on REST return a generic `badRequest`
response. Detailed messages stay in the server log. See
<<_condition_validation,Condition validation>>.
* Public endpoints need a tenant public API key unless
<<_v2_compatibility_mode,single-tenant compatibility mode>> is on (for clients
written for Unomi 2 or Unomi 3). See
<<_updating_applications_consuming_unomi,Updating applications consuming
Unomi>> and the client-facing hardening notes above.
+* The Unomi web tracker 1.x cannot call a multi-tenant server. Use tracker
2.0.0 or later and set `apiKey`, or keep compatibility mode on. The script
served at `/tracker/` is updated with the server. An npm install or a copied
file is not. See <<_upgrading_the_web_tracker,Upgrading the tracker from 1.x to
2.0>>.
* Websites on another origin must be listed for the visitor cookie; see
<<_public_tracker_origins,Websites on other origins>>.
==== Plugin developers
@@ -584,6 +585,7 @@ Before starting the migration, please ensure that:
- You are currently running Apache Unomi 3.0 (or a later 3.0.x version)
- You understand the multi-tenancy impact on your data model
- You have a plan to update client applications to tenant API keys (or
temporary <<_v2_compatibility_mode,single-tenant compatibility mode>> for Unomi
2 or Unomi 3 clients)
+- You have a plan for the web tracker: version 2.0.0 or later with `apiKey` on
a multi-tenant server, or compatibility mode while tracker 1.x is still on the
page (see <<_upgrading_the_web_tracker,Upgrading the tracker from 1.x to 2.0>>)
- You have reviewed the <<_breaking_changes_3_0_to_4_0,breaking changes>> and
<<_client_facing_hardening_4_0,client-facing hardening>> notes
- You know how to obtain plaintext API keys after upgrade (regenerate via
`/cxs/tenants/{id}/apikeys`; create responses expose masked keys only; the
migration also writes a key file under `data/migration/secrets/`)
- Your recurrent import and export `file` endpoints resolve under
`{baseDir}/{tenantId}`, or the router's base-directory properties point at the
directories already in use (see above)
@@ -620,7 +622,7 @@ Use one of the following approaches while migrating clients:
==== 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. For the Unomi web tracker, set `apiKey`;
see <<_web_tracker_server_versions,Configuring the tracker for your Unomi
server>>.
+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, upgrade to
2.0.0 or later and set `apiKey`. See <<_upgrading_the_web_tracker,Upgrading the
tracker from 1.x to 2.0>>.
==== Option 2: single-tenant compatibility mode (Unomi 2 and Unomi 3 clients)
diff --git a/manual/src/main/asciidoc/migrations/v2-compatibility-mode.adoc
b/manual/src/main/asciidoc/migrations/v2-compatibility-mode.adoc
index 8da500ef1..c94acc4ed 100644
--- a/manual/src/main/asciidoc/migrations/v2-compatibility-mode.adoc
+++ b/manual/src/main/asciidoc/migrations/v2-compatibility-mode.adoc
@@ -47,7 +47,9 @@ When single-tenant compatibility mode is enabled:
served from Unomi's own origin needs no change. See
<<_public_tracker_compatibility,Compatibility with Unomi 2.x and 3.x>>.
This allows Unomi 2 and Unomi 3 clients to work with Unomi 4.0 immediately
after migration, giving you time to update
-applications to tenant API keys.
+applications to tenant API keys. Tracker 1.x is one of those clients: it keeps
working while this mode is on, because
+it cannot send an API key. When you turn the mode off, those pages need
tracker 2.0.0 or later and `apiKey`. See
+<<_upgrading_the_web_tracker,Upgrading the tracker from 1.x to 2.0>>.
Unomi 2 and Unomi 3 clients behave the same way in this mode. Third-party /
peer servers keep using `X-Unomi-Peer` and
`etc/org.apache.unomi.thirdparty.cfg` while the mode is on; that path is not
used in normal multi-tenant mode, where the
diff --git a/manual/src/main/asciidoc/tutorial.adoc
b/manual/src/main/asciidoc/tutorial.adoc
index 20088e1f2..916338bde 100644
--- a/manual/src/main/asciidoc/tutorial.adoc
+++ b/manual/src/main/asciidoc/tutorial.adoc
@@ -18,7 +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. 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 <<_ [...]
+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.
diff --git a/manual/src/main/asciidoc/web-tracker.adoc
b/manual/src/main/asciidoc/web-tracker.adoc
index 80260b4ae..88781fbff 100644
--- a/manual/src/main/asciidoc/web-tracker.adoc
+++ b/manual/src/main/asciidoc/web-tracker.adoc
@@ -55,7 +55,35 @@ The tracker sends the key in the `X-Unomi-Api-Key` header on
`context.json` and
* 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.
+`apiKey` and `sendCredentials` need version 2.0.0 or later of the tracker (the
`apache-unomi-tracker` NPM package). Earlier versions do not send the key. Keep
<<_v2_compatibility_mode,single-tenant compatibility mode>> on until those
pages use tracker 2.0. See <<_upgrading_the_web_tracker,Upgrading the tracker
from 1.x to 2.0>>.
+
+[#_upgrading_the_web_tracker]
+==== Upgrading the tracker from 1.x to 2.0
+
+Tracker 2.0 replaces tracker 1.x. It works with Unomi 2.x, 3.x and 4.x.
+
+A page that already works keeps the same configuration, on the same Unomi
server. Unomi 2.x, Unomi 3.x, and Unomi 4 in
<<_v2_compatibility_mode,single-tenant compatibility mode>> need no new
setting. A multi-tenant Unomi 4 server needs tracker 2.0.0 or later and
`apiKey`, as described above. Tracker 1.x cannot send that key, so the server
answers `401`.
+
+Where the script comes from matters:
+
+* The copy Unomi serves at `/tracker/unomi-web-tracker.js` is updated when you
upgrade the server. Unomi 4 serves tracker 2.0.
+* A site that installed the `apache-unomi-tracker` package must upgrade that
package itself (`apache-unomi-tracker@2`).
+* A file copied from an older Unomi stays on tracker 1.x until you replace it.
Leave compatibility mode on until you do.
+
+What a site may notice comes from fixes. The configuration does not change:
+
+* An empty page `attributes` object is no longer sent. Unomi 2.4 and later
rejected those events, so page views and clicks from older examples are stored
again. Attributes that contain values are still sent.
+* Every click on a tracked element is sent, including a click on an image, an
icon or some text inside it. Tracker 1.x sent only the first click on each
element, and often nothing for a click on a child.
+* The page's own click handlers run once per click. They ran twice.
+* A link or a form still works when Unomi cannot be reached, when it never
answers, and when tracking is turned off. A tracked form is submitted with the
button that was used, including a button named `submit`.
+* A missing, blank or zero `timeoutInMilliseconds` uses 1.5 seconds. With
tracker 1.x every request failed at once.
+
+`apiKey` and `sendCredentials` are new and optional. `sendCredentials` is
described under <<_web_tracker_cookies,Cookie/session handling>>.
+
+The tracker project has the full list and the configuration for each Unomi
version:
+
+*
link:https://github.com/apache/unomi-tracker/blob/main/README.md#upgrading-from-1x[Upgrading
from 1.x]
+* link:https://github.com/apache/unomi-tracker/blob/main/CHANGES.md[Release
notes]
==== Custom events
@@ -219,6 +247,8 @@ Integrating with tag managers such as Google Tag Manager is
an important part of
Personalization scripts should however be modified to check for the existence
of the tracker object in the page because tag managers might deactivate scripts
based on conditions such as GDPR approval, cookie preferences, ...
+[#_web_tracker_cookies]
+[[_cookiesession_handling]]
==== Cookie/session handling
In order to track profiles, an identifier must be stored in the browser so
that subsequent requests can keep a reference to the visitor's profile. Also, a
session identifier must be generated to group the current visitor interactions.
@@ -259,6 +289,8 @@ Note that this is just an example, you could very well
customize this code to cr
==== JavaScript API
-The JavaScript API for the web tracker is directly provided in the source code
of the web tracker. You can find it here:
https://github.com/apache/unomi-tracker/blob/main/src/apache-unomi-tracker.js
+The JavaScript API for the web tracker is in the tracker source:
https://github.com/apache/unomi-tracker/blob/main/src/apache-unomi-tracker.js
+
+How to install it, how to configure it for each Unomi version, and what
changed in 2.0 are in the tracker project:
link:https://github.com/apache/unomi-tracker/blob/main/README.md[README]. The
short version for an existing site is <<_upgrading_the_web_tracker,Upgrading
the tracker from 1.x to 2.0>> above.
Please note that only the functions that do NOT start with an underscore
should be used. The ones that start with an underscore are not considered part
of the public API and could change or even be removed at any point in the
future.
\ No newline at end of file
diff --git a/manual/src/main/asciidoc/whats-new.adoc
b/manual/src/main/asciidoc/whats-new.adoc
index 65fa44f40..776a4b3ac 100644
--- a/manual/src/main/asciidoc/whats-new.adoc
+++ b/manual/src/main/asciidoc/whats-new.adoc
@@ -35,6 +35,15 @@ Unomi 4.0 requires explicit admin and health-check passwords
at startup, treats
* Profile tracking contract: <<_how_profile_tracking_works,How profile
tracking works>>
* Jira: https://issues.apache.org/jira/browse/UNOMI-972[UNOMI-972]
+==== Web tracker 2.0
+
+Unomi 4 serves web tracker 2.0 at `/tracker/unomi-web-tracker.js`. A page that
loads that URL gets the new tracker with the server. A page that installed the
`apache-unomi-tracker` package, or that uses a copied older file, stays on
tracker 1.x until that copy is upgraded.
+
+Tracker 1.x cannot send the tenant public API key. On a multi-tenant server,
use tracker 2.0.0 or later and set `apiKey`, or keep
<<_v2_compatibility_mode,single-tenant compatibility mode>> on. The same
configuration still works on Unomi 2.x, 3.x, and on Unomi 4 in that mode. After
the upgrade, clicks that 1.x missed are recorded, and the page's own click
handlers run once per click.
+
+* <<_upgrading_the_web_tracker,Upgrading the tracker from 1.x to 2.0>>
+* <<_web_tracker_server_versions,Configuring the tracker for your Unomi
server>>
+
==== Visitor cookie across websites
The public tracker endpoints answer any origin, but only listed websites and
Unomi's own origin may use the visitor cookie. Websites are listed by the
operator for every tenant (`UNOMI_PUBLIC_CORS_ALLOWED_ORIGINS`, empty by
default) or by each tenant for itself (its `publicCorsAllowedOrigins`
property). `SameSite` is configurable (`UNOMI_PROFILE_COOKIE_SAMESITE`), and
`None` requires HTTPS. Websites on another subdomain that used the cookie with
Unomi 2.x or 3.x must be listed; websites [...]