This is an automated email from the ASF dual-hosted git repository. sergehuber pushed a commit to branch UNOMI-1064-tracker-upgrade-docs in repository https://gitbox.apache.org/repos/asf/unomi.git
commit 808c2065e9349a5b877a36548d99df049b1e638d Author: Serge Huber <[email protected]> AuthorDate: Fri Nov 13 08:21:59 2026 +0100 UNOMI-1064: Explain the web tracker upgrade in the manual Sites upgrading can miss that tracker 1.x cannot send the API key, and that an npm install or a copied file is not updated with the server. --- .../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 [...]
