@crelora/mark 0.2.1 → 0.2.2

package/README.md

@@ -156,8 +156,8 @@ 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`. |
@@ -233,7 +233,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 +250,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: