@crelora/mark 0.2.1 → 0.3.0

package/README.md

@@ -52,6 +52,7 @@ Mark.init({
   cross_domain: { cookie_domain: '.example.com' },
   site_id: 'uuid-...',           // Optional: associate events with a registered site
   site_host: 'shop.example.com', // Optional: site host for audit/debug
+  visitor_id: 'platform_client_id', // Optional: adopt trusted first-party anonymous id when storage is empty
   autocapture: { pageview: true }, // Optional: auto-emit page_view on load and SPA route changes
 });
 
@@ -99,6 +100,7 @@ The Node factory accepts optional custom storage or transport adapters so you ca
 - `track(eventName, payload?)` – records custom events with arbitrary properties (numbers, strings, arrays, objects). Use `site_id` and `site_host` for per-event site overrides.
 - `conversion(eventName, payload?)` – records conversion events (same endpoint path as track, with `is_conversion: true` for backend compatibility).
 - `identify(userId, traits?)` – ties a known user identifier to previous anonymous activity. Recommended traits: `email`, `display_name`, `language`. Custom traits are also supported.
+- `setVisitorId(visitorId)` – adopts or replaces the stored anonymous visitor id with a trusted first-party value (for example a platform client id). Updates storage and cookies immediately on the browser. Use when the id is available after init; theme embeds and pixels should use the same source id.
 - `setConsent(status)` – enforces consent gating; pass `'granted'` or `'denied'`.
 - `getVisitorId()` – returns the current pseudonymous visitor ID when available. On the browser, returns `undefined` until consent is granted when `require_consent` is set. Use it to send the ID to your backend (e.g. in a header or body) for server-side attribution when you don't have an authenticated user ID.
 - `flush()` – flushes queued/persisted delivery items.
@@ -156,12 +158,13 @@ All config options use snake_case. Stored event payloads and database columns ma
 | `batching` | `{ enabled?: boolean, max_size?: number, flush_interval_ms?: number, endpoint_path?: string }` | Optional batch mode (`/events` by default). |
 | `require_consent` | `boolean \| 'auto'` | `true` blocks tracking until consent is granted, `'auto'` requires stored granted consent and treats missing consent as denied, default `false` (`'auto'` recommended for production). |
 | `consent_source` | `{ type: 'tcf', purposes: number[] }` | Optional **IAB TCF v2** integration: the SDK listens for CMP updates and only allows tracking when the listed numeric purpose IDs are consented. Combine with `require_consent` and `setConsent` as your legal team requires. |
-| `autocapture` | `{ pageview?: boolean, click?: boolean \| { selector?: string }, form_submit?: boolean, outbound_link?: boolean, scroll_depth?: boolean, web_vitals?: boolean }` | Auto-capture toggles for page views and optional interaction/perf signals. |
-| `track_route_changes` | `boolean` | When `autocapture.pageview` is true, also emits on SPA route changes (pushState/replaceState/popstate); defaults to `true`. |
+| `autocapture` | `{ pageview?: boolean, click?: boolean \| { selector?: string }, form_submit?: boolean, outbound_link?: boolean, scroll_depth?: boolean, page_engagement?: boolean \| { min_active_ms?: number, use_beacon?: boolean }, web_vitals?: boolean }` | Auto-capture toggles for page views and optional interaction/perf signals. |
+| `track_route_changes` | `boolean` | When page lifecycle autocapture is enabled (`pageview`, `scroll_depth`, or `page_engagement`), also reacts to SPA route changes (pushState/replaceState/popstate); defaults to `true`. |
 | `include_page_context` | `boolean` | When true (default), enriches events with `page`, `title`, `referrer`, `site` (full `url` is only sent if you pass it explicitly in payload). |
 | `cross_domain` | `CrossDomainConfig` | Controls cookie domain, bridge URL, and allowlist for multi-domain attribution. |
 | `site_id` | `string` | Optional UUID for associating events with a registered site. Included in all event payloads as `site_id`. |
 | `site_host` | `string` | Optional site host for audit/debug purposes. Included in all event payloads as `site_host`. If not provided, browser SDK uses `window.location.host`. |
+| `visitor_id` | `string` | Optional trusted first-party anonymous id to adopt when no visitor id is stored yet (ignored if storage already has one). Use `setVisitorId()` when the id arrives after init. |
 | `capture_query_params` | `string[]` | Additional query keys to capture for attribution (merged into the default allowlist). |
 | `capture_all_query_params` | `boolean` | Capture all query params after denylist/limits. Defaults to `false`. |
 | `query_param_denylist` | `string[]` | Query keys that are never captured (exact-key matching; default includes sensitive keys like `email`, `token`, `password`). |
@@ -194,7 +197,21 @@ When you don't have an authenticated user ID, you can pass the SDK's visitor ID
 
 **Browser:** Call `Mark.getVisitorId()` after init. If you use `require_consent: true` or `'auto'`, it returns `undefined` until consent is granted. Once available, send it in a header or request body to your API and use it as the `visitor_id` when calling the Node SDK or your ingestion.
 
-**Node:** Call `mark.getVisitorId()` to read the visitor ID from the storage you passed to `createNodeMark` (e.g. from `storageDefaults.visitor_id`). Use it to associate server events with the same visitor.
+**Adopting an external anonymous id:** When your platform already provides a stable first-party anonymous key (for example a Shopify client id), pass it at init or call `Mark.setVisitorId()` once it is available:
+
+```ts
+Mark.init({
+  key: 'pk_xxxxx',
+  visitor_id: platformClientId, // only adopted when storage is empty
+});
+
+// Or when the id arrives asynchronously:
+Mark.setVisitorId(platformClientId);
+```
+
+Use this for trusted first-party ids only — not email addresses, order ids, or values from unvalidated URL parameters. `identify()` sets `user_id` (known person), not `visitor_id` (anonymous device/browser key). After `Mark.reset()`, the SDK rotates to a fresh generated visitor id.
+
+**Node:** Call `mark.getVisitorId()` to read the visitor ID from the storage you passed to `createNodeMark` (e.g. from `storageDefaults.visitor_id` or `Mark.init`-equivalent config `visitor_id`). Use `mark.setVisitorId()` to update the id for the current server-side client instance.
 
 The visitor ID is a pseudonymous, SDK-scoped identifier. Do not use it as a cross-site or long-term user identity; use it only for joining browser and server events within your attribution flow.
 
@@ -233,7 +250,8 @@ All of the following are **opt-in** under `autocapture`. They respect the same c
 | `click` | `data-mark-event` value, or `click` | Listens for clicks. **Default:** only elements matching `[data-mark-event]`; set `click: { selector: '.my-tracked' }` to use a custom selector. Sends `element_id`, `element_classes`, truncated `text`, and `href` when applicable. |
 | `form_submit` | `form_submit` | Listens for `submit`; sends `form_id`, `form_name`, `action`. |
 | `outbound_link` | `outbound_link_click` | On click, if the link target is another origin, sends `href`. Uses `preferBeacon: true` so the event is more likely to fire before navigation. |
-| `scroll_depth` | `scroll_depth` | Fires at **25%, 50%, 75%, and 100%** of vertical scroll depth (once each per page load). Payload includes `percent`. |
+| `scroll_depth` | `scroll_depth` | Fires at **25%, 50%, 75%, and 100%** of vertical scroll depth (once each per **logical page**; resets on SPA route changes when route tracking is enabled). Payload includes `percent`. |
+| `page_engagement` | `page_engagement` | One summary per **logical page** when the user navigates away or unloads (not on tab background alone). Emits if accumulated **visible** active time is at least `min_active_ms` (default **10000**). Tab hide/show pauses the clock. Payload includes `page`, `active_time_ms`, `total_time_ms`, and `max_scroll_percent`. Uses `sendBeacon` on exit by default. |
 | `web_vitals` | `web_vital` | Lazy-loads the `web-vitals` dependency and reports **LCP, CLS, INP, and TTFB** with `metric`, `value`, optional `rating`, and `metric_id`. If the module fails to load, only `debug: true` logs a warning. |
 
 Example:
@@ -249,11 +267,16 @@ Mark.init({
     form_submit: true,
     outbound_link: true,
     scroll_depth: true,
+    page_engagement: true,
     web_vitals: true,
   },
 });
 ```
 
+## Session fields on events
+
+Every tracked event includes `session_id` when a session exists. Events also include `session_started_at` (ISO timestamp) and `session_elapsed_ms` (milliseconds since that session started). The same session fields are included on `identify` payloads after the first tracked activity in a session. Session rotation uses `session_timeout_ms` (default 30 minutes of inactivity) and UTC day boundaries; the event that triggers rotation keeps the **previous** session identifiers. Session duration for reporting is typically derived server-side from the event stream (`max(occurred_at) - session_started_at` per `session_id`).
+
 ## Flagging internal traffic
 
 Use the `is_internal` marker to keep QA sessions, staff testing, or automated smoke tests out of customer-facing reports without dropping them on the client. The SDK supports it in two complementary ways: