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  [...]

Reply via email to