@datalyr/web 1.7.5 → 1.7.8

package/README.md

@@ -1,28 +1,33 @@
 # @datalyr/web
 
-Browser SDK for event tracking, user identity, and attribution. Version 1.7.0.
+Browser SDK for event tracking, user identity, and attribution. Version 1.7.8.
 
-## Table of Contents
+Full reference: [Web SDK](https://docs.datalyr.com/sdk-reference/web).
+
+## Table of contents
 
 - [Installation](#installation)
-- [Quick Start](#quick-start)
-- [How It Works](#how-it-works)
+- [Quick start](#quick-start)
+- [What the SDK tracks without your code](#what-the-sdk-tracks-without-your-code)
+- [Events the SDK sends for you](#events-the-sdk-sends-for-you)
+- [Identity](#identity)
 - [Configuration](#configuration)
-- [API Reference](#api-reference)
-  - [Event Tracking](#event-tracking)
-  - [User Identity](#user-identity)
-  - [Session](#session)
-  - [Attribution](#attribution)
-  - [Super Properties](#super-properties)
-  - [Privacy and Consent](#privacy-and-consent)
-  - [Queue and Network](#queue-and-network)
-  - [Container Scripts](#container-scripts)
-  - [Debugging](#debugging)
-  - [Lifecycle](#lifecycle)
-- [Web-to-App Attribution](#web-to-app-attribution)
-- [SPA Support](#spa-support)
-- [Framework Integration](#framework-integration)
+- [Remote configuration](#remote-configuration)
+- [Complete method list](#complete-method-list)
+- [Event tracking](#event-tracking)
+- [Attribution](#attribution)
+- [Checkout metadata](#checkout-metadata)
+- [Super properties](#super-properties)
+- [Privacy and consent](#privacy-and-consent)
+- [Queue, network, and limits](#queue-network-and-limits)
+- [Storage](#storage)
+- [Container scripts](#container-scripts)
+- [Debugging](#debugging)
+- [Web-to-app attribution](#web-to-app-attribution)
+- [SPA support](#spa-support)
+- [Framework integration](#framework-integration)
 - [TypeScript](#typescript)
+- [Verify the install](#verify-the-install)
 - [Troubleshooting](#troubleshooting)
 - [License](#license)
 
@@ -30,419 +35,457 @@ Browser SDK for event tracking, user identity, and attribution. Version 1.7.0.
 
 ## Installation
 
-### NPM
+Choose one method.
 
-```bash
-npm install @datalyr/web
-```
+> **Never load the script tag and the npm package together.** Two instances issue two
+> `visitor_id` values for one person and split the journey.
 
-### Script Tag
+### Script tag
 
 ```html
 <script defer src="https://track.datalyr.com/dl.js"
         data-workspace-id="YOUR_WORKSPACE_ID"></script>
 ```
 
-The script tag loads externally (zero bundle size) and auto-initializes. Access the SDK via `window.datalyr`.
+The script tag loads externally and initializes on its own. Reach the SDK at
+`window.datalyr`.
+
+The script tag reads these attributes:
 
-Choose one installation method. Using both causes conflicts.
+| Attribute | Required | Effect |
+| --- | --- | --- |
+| `data-workspace-id` | Yes | The workspace that receives events. |
+| `data-endpoint` | No | Overrides the ingest URL. |
+| `data-tracked-params` | No | More URL parameters to capture. Comma-separated. |
+| `data-debug` | No | `true` turns on console logging. |
+| `data-auto-identify` | No | `true` or `false`. |
+| `data-platform` | No | `shopify`, `checkoutchamp`, or `generic`. |
+| `data-checkout-champ-domains` | No | Comma-separated domains. |
+| `data-stripe-payment-links` | No | `false` turns off Stripe link decoration. |
+| `data-stripe-link-domains` | No | Comma-separated extra Stripe domains. |
+
+### npm
+
+```bash
+npm install @datalyr/web
+```
 
-| Feature | Script Tag | NPM |
-|---------|-----------|-----|
-| Bundle Size | 0 (external) | ~15KB |
-| TypeScript | No | Yes |
-| Access | `window.datalyr` | `import datalyr` |
+| Property | Script tag | npm |
+| --- | --- | --- |
+| Bundle cost | 0, loaded externally | 88 KB minified, 24 KB gzipped |
+| TypeScript types | No | Yes |
+| Access | `window.datalyr` | `import datalyr from '@datalyr/web'` |
 | Initialize | Automatic | `datalyr.init()` |
 
 ---
 
-## Quick Start
+## Quick start
 
 ```javascript
 import datalyr from '@datalyr/web';
 
-datalyr.init({
-  workspaceId: 'YOUR_WORKSPACE_ID'
-});
+datalyr.init({ workspaceId: 'YOUR_WORKSPACE_ID' });
 
-// Wait for async initialization (encryption, container, initial page view)
+// Wait for encryption keys, container scripts, and the first page view
 await datalyr.ready();
 
-// Track events
 datalyr.track('button_clicked', { button: 'signup' });
 
-// Identify users
 datalyr.identify('user_123', { email: 'user@example.com' });
 
-// Track page views (page name goes in properties)
 datalyr.page({ title: 'Pricing', variant: 'A' });
 ```
 
+`init()` throws `Error('[Datalyr] workspaceId is required')` when `workspaceId` is
+missing. A second `init()` call logs a warning and returns. Any tracking method called
+before `init()` logs a warning and returns.
+
+---
+
+## What the SDK tracks without your code
+
+Two triggers fire on their own.
+
+| Trigger | Event name | Turn it off with |
+| --- | --- | --- |
+| First page view after load | `pageview` | `trackPageViews: false` |
+| SPA route change — `pushState`, `replaceState`, `popstate`, `hashchange` | `pageview` | `trackSPA: false` |
+
+Nothing else is automatic. The SDK records no clicks, scrolls, form submits, outbound
+links, or errors. There is no session-start event. Session data rides on every event.
+Call `track()` for everything else.
+
 ---
 
-## How It Works
+## Events the SDK sends for you
 
-1. Events are created with `track()`, `page()`, `identify()`, etc.
-2. Each event includes device context, session data, and attribution parameters.
-3. Events are queued locally and sent in batches.
-4. If the browser is offline, events are stored and sent when connectivity returns.
-5. Events are processed server-side for analytics and attribution reporting.
+These names are reserved. Never send one through `track()` yourself.
 
-### Event Payload
+| Method you call | Event name sent |
+| --- | --- |
+| `identify()` | `$identify` |
+| `group()` | `$group` |
+| `alias()` | `$alias` |
+| `screen()` | `pageview`, with a `screen` property |
+| `trackAppDownloadClick()` | `$app_download_click` |
+| Auto-identify email capture | `$auto_identify`, then `$identify` |
 
-Every event includes:
+### Event payload
 
 ```javascript
 {
   event_name: 'purchase',
-  event_data: { ... },           // Custom + attribution + session properties
+  event_data: { /* your properties, plus attribution, session, and context fields */ },
 
   // Identity
-  anonymous_id: 'anon_xxxxx',    // Persistent browser ID
-  distinct_id: 'user_123',       // user_id if identified, else anonymous_id
-  user_id: 'user_123',           // Set after identify()
-  session_id: 'sess_xxxxx',      // Current session
+  visitor_id: 'anon_3d5cf66d-203f-4009-8bb0-f3714da152a4',
+  distinct_id: 'user_123',
+  user_id: 'user_123',
+  session_id: 'sess_9f2c1b40-1c2e-4d55-9a0b-6a4f7f1d2e33',
 
-  // Context (in event_data)
+  // Context, inside event_data
   url: 'https://example.com/pricing',
   title: 'Pricing',
   referrer: 'https://google.com',
 
-  // Attribution (in event_data, if captured)
+  // Attribution, inside event_data
   utm_source: 'facebook',
   fbclid: 'abc123',
 
   // Metadata
   workspace_id: 'wk_xxxxx',
   source: 'web',
-  timestamp: '2024-01-15T10:30:00Z',
-  sdk_version: '1.7.0',
+  timestamp: '2026-07-25T10:30:00Z',
+  sdk_version: '1.7.8',
   sdk_name: 'datalyr-web-sdk'
 }
 ```
 
 ---
 
-## Configuration
-
-All properties of `DatalyrConfig`:
-
-```typescript
-datalyr.init({
-  // Required
-  workspaceId: string,
-
-  // Endpoint
-  endpoint?: string,                        // Default: 'https://ingest.datalyr.com'
-  fallbackEndpoints?: string[],             // Default: [] - Additional endpoints to try on failure
-
-  // Debugging
-  debug?: boolean,                          // Default: false - Enable console logging
-
-  // Batching
-  batchSize?: number,                       // Default: 10 - Events per batch
-  flushInterval?: number,                   // Default: 5000 - Flush interval in ms
-  flushAt?: number,                         // Default: 10 - Flush when N events queued
-
-  // Priority events (bypass normal batching)
-  criticalEvents?: string[],               // Default: undefined (disabled). Events flushed immediately.
-  highPriorityEvents?: string[],           // Default: undefined (disabled). Events given queue priority.
-
-  // Session
-  sessionTimeout?: number,                  // Default: 3600000 (60 min)
-  trackSessions?: boolean,                  // Default: true
-
-  // Attribution
-  attributionWindow?: number,               // Default: 7776000000 (90 days)
-  trackedParams?: string[],                 // Default: [] - Additional URL params to capture
-
-  // Privacy
-  respectDoNotTrack?: boolean,              // Default: false - Honor browser DNT header
-  respectGlobalPrivacyControl?: boolean,    // Default: true - Honor GPC signal
-  privacyMode?: 'standard' | 'strict',     // Default: 'standard' - 'strict' limits data collection
-
-  // Cookies / Storage
-  cookieDomain?: string | 'auto',           // Default: 'auto'
-  cookieExpires?: number,                   // Default: 365 (days)
-  secureCookie?: boolean | 'auto',          // Default: 'auto'
-  sameSite?: 'Strict' | 'Lax' | 'None',    // Default: 'Lax'
-  cookiePrefix?: string,                    // Default: '__dl_'
-
-  // Performance
-  enablePerformanceTracking?: boolean,      // Default: true - Collect navigation timing metrics
-  enableFingerprinting?: boolean,           // Default: true - Minimal device fingerprinting (standard mode only)
-
-  // Retry / Offline
-  maxRetries?: number,                      // Default: 5
-  retryDelay?: number,                      // Default: 1000 (ms)
-  maxOfflineQueueSize?: number,             // Default: 100
-
-  // SPA
-  trackSPA?: boolean,                       // Default: true - Auto-track route changes
-  trackPageViews?: boolean,                 // Default: true - Auto-track initial page view
-
-  // Container scripts
-  enableContainer?: boolean,                // Default: true - Load third-party scripts from dashboard
-
-  // Auto-Identify (opt-in)
-  autoIdentify?: boolean,                   // Default: false - Automatically identify users
-  autoIdentifyForms?: boolean,              // Default: true - Capture email from forms (when autoIdentify enabled)
-  autoIdentifyAPI?: boolean,                // Default: false - Capture email from API responses (off: same-origin scan can mis-identify; opt in explicitly)
-  autoIdentifyShopify?: boolean,            // Default: true - Capture email from Shopify endpoints (when autoIdentify enabled)
-  autoIdentifyTrustedDomains?: string[],    // Default: [] - Additional domains to trust for API capture
-
-  // Plugins
-  plugins?: DatalyrPlugin[],                // Default: [] - Custom plugin instances
-});
-```
+## Identity
 
----
+Four identifiers ship on every event. They are not alternatives to each other.
 
-## Remote config (Identity Bridge)
+| Wire field | Value |
+| --- | --- |
+| `visitor_id` | The anonymous browser ID, format `anon_<uuid>`. Stays anonymous even after `identify()`. |
+| `user_id` | The ID you pass to `identify()`. `null` until then. |
+| `distinct_id` | The `user_id` when identified. The `visitor_id` before that. |
+| `session_id` | Format `sess_<uuid>`. New after 60 minutes idle. |
 
-These options can be controlled from the dashboard (**Settings → Identity & Attribution**) with **no code change** — they're delivered to the SDK at runtime in the `/container-scripts` response and merged in:
+Use `visitor_id` in server-side and webhook work. Stripe, Whop, and Shopify all key off
+it. Use `distinct_id` when you reason about event-level identity.
 
-- `autoIdentify`, `autoIdentifyForms`, `autoIdentifyAPI`, `autoIdentifyShopify`
-- `shopifyCartAttributes`
-- `checkoutChampDomains`
-- `respectGlobalPrivacyControl`, `respectDoNotTrack`, `privacyMode`
+The **Events** and **Conversions** tables label this column `distinct id`. For an
+unidentified visitor it shows the `visitor_id`.
 
-**Precedence, per key:** built-in default ← dashboard ← explicit `init()`. An explicit value in `init()` always wins, so you can pin a value in code and still manage everything else from the dashboard. Changes propagate in ~5 minutes (edge-cached). An older worker that doesn't send the `config` envelope is a no-op — built-in defaults stand.
+### Identity methods
 
-> `platform` is **not** remote-configurable — set it at install time via the `data-platform` attribute. The CheckoutChamp behaviors run before the remote config loads, so a dashboard-set platform wouldn't drive them.
-
----
+| Method | Returns |
+| --- | --- |
+| `getVisitorId(): string` | The anonymous browser ID. Same value as `getAnonymousId()`. |
+| `getAnonymousId(): string` | The anonymous browser ID. |
+| `getUserId(): string \| null` | The identified user ID, or `null`. |
+| `getDistinctId(): string` | The user ID when identified, otherwise the anonymous browser ID. |
+| `getSessionId(): string` | The current session ID. |
+| `getSessionData(): SessionData \| null` | The full session record. |
+| `startNewSession(): string` | Ends the current session and returns a new session ID. |
+| `getWorkspaceId(): string \| null` | The workspace ID passed to `init()`. |
 
-## API Reference
-
-### Event Tracking
-
-#### `track(eventName, properties?)`
+```typescript
+interface SessionData {
+  id: string;
+  startTime: number;
+  lastActivity: number;
+  pageViews: number;
+  events: number;
+  duration: number;
+  isActive: boolean;
+}
+```
 
-Track a custom event.
+### identify()
 
 ```typescript
-track(eventName: string, properties?: EventProperties): void
+identify(userId: string, traits?: UserTraits): void
 ```
 
 ```javascript
-datalyr.track('signup_started');
-
-datalyr.track('product_viewed', {
-  product_id: 'SKU123',
-  product_name: 'Blue Shirt',
-  price: 29.99,
-  currency: 'USD',
-  category: 'Apparel',
+datalyr.identify('user_123', {
+  email: 'user@example.com',
+  name: 'John Doe',
+  plan: 'premium',
 });
 ```
 
-#### `page(properties?)`
-
-Track a page view. The page `title`, `url`, `path`, `search`, and `referrer` are captured automatically. Pass `properties` to add or override values.
+Call `identify()` after sign-in. Traits are encrypted with AES-GCM before storage.
+Passing a different `user_id` runs `reset()` first, so two people on one browser do not
+merge. `identify()` does not rotate the session ID.
 
-```typescript
-page(properties?: PageProperties): void
-```
+### reset()
 
 ```javascript
-// Track current page (all properties auto-captured)
-datalyr.page();
-
-// Override title, add custom properties
-datalyr.page({ title: 'Pricing', variant: 'A' });
-
-// Add custom properties
-datalyr.page({ product_id: 'SKU123', source: 'search' });
+datalyr.reset();
 ```
 
-Note: `page()` does not accept a name string as the first argument. To set the page name, pass it as `title` in the properties object.
+> **Do not call `reset()` on every page load.** It issues a **new** `visitor_id`, which
+> breaks the link between the campaign visit and the later conversion.
 
-#### `screen(screenName, properties?)`
+Call `reset()` on logout. It clears `user_id`, traits, super properties, the captured
+email, the journey, and both touchpoints, then issues a new `visitor_id` and a new
+session. It leaves the Meta `_fbc` and `_fbp` cookies in place.
 
-Track a screen view. Intended for SPAs or hybrid apps.
+### alias()
 
 ```typescript
-screen(screenName: string, properties?: Record<string, any>): void
+alias(userId: string, previousId?: string): void
 ```
 
 ```javascript
-datalyr.screen('Dashboard');
-datalyr.screen('Product Details', { product_id: 'SKU123' });
+datalyr.alias('user_123');
 ```
 
-Internally fires a `pageview` event with the `screen` property set.
-
-#### `trackAppDownloadClick(options)`
+> **`previousId` accepts only the current anonymous ID.** Any other value logs
+> `alias() only accepts the current anonymous ID as previousId` and does nothing. Omit the
+> argument to use the current anonymous ID.
 
-Track an app download click, then redirect to the app store. Fires a `$app_download_click` event with full attribution, flushes via `sendBeacon`, and redirects.
+### group()
 
 ```typescript
-trackAppDownloadClick(options: {
-  targetPlatform: 'ios' | 'android';
-  appStoreUrl: string;
-}): void
+group(groupId: string, traits?: Record<string, any>): void
 ```
 
 ```javascript
-datalyr.trackAppDownloadClick({
-  targetPlatform: 'ios',
-  appStoreUrl: 'https://apps.apple.com/app/your-app/id123456789',
-});
+datalyr.group('company_abc', { name: 'Acme Inc', plan: 'enterprise' });
 ```
 
-For Android Play Store URLs, attribution parameters are automatically encoded into the `referrer` query parameter for deterministic install attribution.
-
 ---
 
-### User Identity
-
-#### `identify(userId, traits?)`
+## Configuration
 
-Link the anonymous visitor to a known user. Rotates the session ID on call (prevents session fixation). User traits are encrypted at rest.
+Only `workspaceId` is required.
 
-```typescript
-identify(userId: string, traits?: UserTraits): void
-```
+> **`sessionTimeout` and `attributionWindow` are milliseconds, not minutes or days.**
+> Setting `sessionTimeout: 60` expires the session after 60 milliseconds and starts a new
+> session on every event.
 
 ```javascript
-datalyr.identify('user_123', {
-  email: 'user@example.com',
-  name: 'John Doe',
-  plan: 'premium',
-  company: 'Acme Inc',
+datalyr.init({
+  workspaceId: 'YOUR_WORKSPACE_ID',
+  sessionTimeout: 3600000,      // 60 minutes, in milliseconds
+  attributionWindow: 7776000000, // 90 days, in milliseconds
+  debug: true,
 });
 ```
 
-#### `alias(userId, previousId?)`
-
-Create an alias linking one user ID to another. If `previousId` is omitted, the current anonymous ID is used.
-
-```typescript
-alias(userId: string, previousId?: string): void
-```
-
-```javascript
-datalyr.alias('user_123', 'temp_user_456');
-```
+| Option | Type | Default |
+| --- | --- | --- |
+| `workspaceId` | `string` | Required. Throws when missing. |
+| `endpoint` | `string` | `'https://ingest.datalyr.com'` |
+| `fallbackEndpoints` | `string[]` | `[]`. Tried in order after the primary endpoint fails. |
+| `debug` | `boolean` | `false` |
+| `batchSize` | `number` events | `10`, clamped 1–1000 |
+| `flushInterval` | `number` ms | `5000`, clamped 250–3600000 |
+| `criticalEvents` | `string[]` | `['purchase', 'signup', 'subscribe', 'lead', 'conversion']`. Flushed immediately. |
+| `highPriorityEvents` | `string[]` | `['add_to_cart', 'begin_checkout', 'view_item', 'search']`. Flushed after 1000 ms. |
+| `sessionTimeout` | `number` ms | `3600000` — 60 minutes |
+| `attributionWindow` | `number` ms | `7776000000` — 90 days |
+| `trackedParams` | `string[]` | `[]`, merged onto the default list |
+| `respectDoNotTrack` | `boolean` | `false` |
+| `respectGlobalPrivacyControl` | `boolean` | `true` |
+| `privacyMode` | `'standard' \| 'strict'` | `'standard'` |
+| `cookieDomain` | `string \| 'auto'` | `'auto'` |
+| `cookieExpires` | `number` days | `365` |
+| `secureCookie` | `boolean \| 'auto'` | `'auto'` |
+| `sameSite` | `'Strict' \| 'Lax' \| 'None'` | `'Lax'` |
+| `cookiePrefix` | `string` | `'__dl_'` |
+| `enablePerformanceTracking` | `boolean` | `true` |
+| `enableFingerprinting` | `boolean` | `true`. Off in `strict` privacy mode. |
+| `maxRetries` | `number` | `5`, clamped 0–20 |
+| `retryDelay` | `number` ms | `1000`, clamped 0–60000 |
+| `maxOfflineQueueSize` | `number` events | `100`, clamped 1–100000 |
+| `trackSPA` | `boolean` | `true` |
+| `trackPageViews` | `boolean` | `true` |
+| `enableContainer` | `boolean` | `true`. Set `false` to skip dashboard-configured pixels. |
+| `autoIdentify` | `boolean` | `false`. Forced `false` when `privacyMode` is `'strict'`. |
+| `autoIdentifyForms` | `boolean` | `true`, applied only when `autoIdentify` is `true` |
+| `autoIdentifyAPI` | `boolean` | `false`. A same-origin response scan can mis-identify. |
+| `autoIdentifyShopify` | `boolean` | `true`, applied only when `autoIdentify` is `true` |
+| `autoIdentifyTrustedDomains` | `string[]` | `[]` |
+| `shopifyCartAttributes` | `boolean` | `false`. Becomes `true` when `platform` is `'shopify'`. |
+| `platform` | `'shopify' \| 'checkoutchamp' \| 'generic'` | Unset |
+| `checkoutChampDomains` | `string[]` | Unset |
+| `stripePaymentLinks` | `boolean` | `true` |
+| `stripeLinkDomains` | `string[]` | `[]` |
+| `plugins` | `DatalyrPlugin[]` | `[]` |
+
+### Options that do nothing
+
+`DatalyrConfig` declares two options that no code reads. Setting either changes no
+behavior.
+
+| Option | Status |
+| --- | --- |
+| `flushAt` | Declared and given a default of `10`. Never read. Use `batchSize`. |
+| `trackSessions` | Declared and given a default of `true`. Never read. Sessions are always tracked. |
 
-#### `group(groupId, traits?)`
+---
 
-Associate the current user with a group or account.
+## Remote configuration
 
-```typescript
-group(groupId: string, traits?: Record<string, any>): void
-```
+Datalyr can set these nine options from the dashboard, under **Settings → Identity &
+Attribution**, with no code change. The SDK receives them at runtime in the
+`/container-scripts` response.
 
-```javascript
-datalyr.group('company_abc', { name: 'Acme Inc', plan: 'enterprise' });
-```
+`autoIdentify`, `autoIdentifyForms`, `autoIdentifyAPI`, `autoIdentifyShopify`,
+`shopifyCartAttributes`, `checkoutChampDomains`, `respectGlobalPrivacyControl`,
+`respectDoNotTrack`, `privacyMode`.
 
-#### `reset()`
+Precedence per key: built-in default, then the dashboard value, then the explicit
+`init()` value. A value you pass to `init()` always wins. Changes propagate within about
+5 minutes because the response is edge-cached.
 
-Clear user identity and start a new session. The anonymous ID is preserved.
+`platform` is not remote-configurable. Set it at install time with the `data-platform`
+attribute. The CheckoutChamp behaviors run before the remote config arrives.
 
-```javascript
-datalyr.reset();
-```
-
-#### `getAnonymousId()`
+---
 
-Returns the persistent anonymous ID assigned on first visit.
+## Complete method list
+
+| Method | Signature |
+| --- | --- |
+| `init` | `(config: DatalyrConfig) => void` |
+| `ready` | `() => Promise<void>` |
+| `track` | `(eventName: string, properties?: EventProperties) => void` |
+| `identify` | `(userId: string, traits?: UserTraits) => void` |
+| `page` | `(properties?: PageProperties) => void` |
+| `screen` | `(screenName: string, properties?: Record<string, any>) => void` |
+| `group` | `(groupId: string, traits?: Record<string, any>) => void` |
+| `alias` | `(userId: string, previousId?: string) => void` |
+| `reset` | `() => void` |
+| `flush` | `() => Promise<void>` |
+| `destroy` | `() => void` |
+| `getWorkspaceId` | `() => string \| null` |
+| `getVisitorId` | `() => string` |
+| `getAnonymousId` | `() => string` |
+| `getUserId` | `() => string \| null` |
+| `getDistinctId` | `() => string` |
+| `getSessionId` | `() => string` |
+| `getSessionData` | `() => SessionData \| null` |
+| `startNewSession` | `() => string` |
+| `getAttribution` | `() => Attribution` |
+| `getJourney` | `() => TouchPoint[]` |
+| `setAttribution` | `(attribution: Partial<Attribution>) => void` |
+| `getStripeMetadata` | `() => { client_reference_id: string; metadata: { visitor_id: string } }` |
+| `getWhopCheckoutMetadata` | `() => { visitor_id: string }` |
+| `trackAppDownloadClick` | `(options: { targetPlatform: 'ios' \| 'android'; appStoreUrl: string }) => Promise<void>` |
+| `setConsent` | `(consent: ConsentConfig) => void` |
+| `optOut` | `() => void` |
+| `optIn` | `() => void` |
+| `isOptedOut` | `() => boolean` |
+| `setSuperProperties` | `(properties: Record<string, any>) => void` |
+| `unsetSuperProperty` | `(propertyName: string) => void` |
+| `getSuperProperties` | `() => Record<string, any>` |
+| `getErrors` | `() => ErrorInfo[]` |
+| `getNetworkStatus` | `() => NetworkStatus` |
+| `loadScript` | `(scriptId: string) => void` |
+| `getLoadedScripts` | `() => string[]` |
+
+The default export and `window.datalyr` are one shared singleton.
+`createDatalyrInstance()` returns a second independent instance.
+
+`trackImmediate()` and `forceFlush()` are not public methods. Names in the bootstrap stub
+that resemble them do not resolve to anything callable. Use `track()` and `flush()`.
 
-```typescript
-getAnonymousId(): string
-```
+---
 
-#### `getUserId()`
+## Event tracking
 
-Returns the current user ID set by `identify()`, or `null` if not identified.
+### track()
 
 ```typescript
-getUserId(): string | null
+track(eventName: string, properties?: EventProperties): void
 ```
 
-#### `getDistinctId()`
-
-Returns the distinct ID. This is `userId` if identified, otherwise `anonymousId`.
+```javascript
+datalyr.track('signup_started');
 
-```typescript
-getDistinctId(): string
+datalyr.track('product_viewed', {
+  product_id: 'SKU123',
+  product_name: 'Blue Shirt',
+  price: 29.99,
+  currency: 'USD',
+  category: 'Apparel',
+});
 ```
 
----
-
-### Session
-
-#### `getSessionId()`
-
-Returns the current session ID.
+### page()
 
 ```typescript
-getSessionId(): string
+page(properties?: PageProperties): void
 ```
 
-#### `startNewSession()`
-
-Force-start a new session. Returns the new session ID.
-
-```typescript
-startNewSession(): string
-```
+The SDK captures `title`, `url`, `path`, `search`, and `referrer` on its own. Pass
+`properties` to add or override values.
 
 ```javascript
-const newSessionId = datalyr.startNewSession();
+datalyr.page();
+datalyr.page({ title: 'Pricing', variant: 'A' });
 ```
 
-#### `getSessionData()`
+`page()` does not accept a name string as its first argument. Pass the page name as
+`title` inside the properties object.
+
+Use `page()` only when automatic tracking is off, or for a second view on one URL.
 
-Returns the current session metadata, or `null` if no active session.
+### screen()
 
 ```typescript
-getSessionData(): SessionData | null
+screen(screenName: string, properties?: Record<string, any>): void
 ```
 
-```typescript
-interface SessionData {
-  id: string;
-  startTime: number;
-  lastActivity: number;
-  pageViews: number;
-  events: number;
-  duration: number;
-  isActive: boolean;
-}
+```javascript
+datalyr.screen('Dashboard');
+datalyr.screen('Product Details', { product_id: 'SKU123' });
 ```
 
-#### `ready()`
+`screen()` sends a `pageview` event with the `screen` property set.
 
-Returns a promise that resolves when async initialization is complete (encryption, container loading, initial page view).
+### ready()
 
 ```typescript
 ready(): Promise<void>
 ```
 
+`init()` returns synchronously. Encryption setup, container loading, and the first page
+view finish asynchronously. Await `ready()` when you need all three complete.
+
 ```javascript
 datalyr.init({ workspaceId: 'YOUR_WORKSPACE_ID' });
 await datalyr.ready();
-// Encryption is initialized, container is loaded, safe to track
+datalyr.track('post_init_event');
 ```
 
 ---
 
-### Attribution
-
-#### `getAttribution()`
-
-Returns the current captured attribution data.
+## Attribution
 
 ```typescript
 getAttribution(): Attribution
+setAttribution(attribution: Partial<Attribution>): void
+getJourney(): TouchPoint[]
 ```
 
 ```javascript
 const attribution = datalyr.getAttribution();
 console.log(attribution.source, attribution.medium, attribution.campaign);
+
+datalyr.setAttribution({
+  source: 'partner',
+  medium: 'referral',
+  campaign: 'spring_promo',
+});
 ```
 
 ```typescript
@@ -453,51 +496,15 @@ interface Attribution {
   term?: string | null;
   content?: string | null;
   clickId?: string | null;
-  clickIdType?: string | null;   // 'fbclid', 'gclid', 'oppref', etc.
+  clickIdType?: string | null;   // 'fbclid', 'gclid', 'ttclid', and the rest of the 15 below
   referrer?: string | null;
   referrerHost?: string | null;
   landingPage?: string | null;
   landingPath?: string | null;
   timestamp?: number;
-  [key: string]: any;            // Custom tracked params
+  [key: string]: any;            // Your trackedParams
 }
-```
-
-Captured automatically from URLs:
-
-| Type | Parameters |
-|------|------------|
-| UTM | `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term` |
-| Click IDs | `fbclid`, `gclid`, `ttclid`, `oppref`, `twclid`, `li_fat_id`, `msclkid` |
-| Referrer | `referrer`, `landing_page` |
-
-Attribution supports first-touch (90-day window), last-touch, and journey tracking.
-
-#### `setAttribution(attribution)`
-
-Manually set or override attribution data.
-
-```typescript
-setAttribution(attribution: Partial<Attribution>): void
-```
 
-```javascript
-datalyr.setAttribution({
-  source: 'partner',
-  medium: 'referral',
-  campaign: 'spring_promo',
-});
-```
-
-#### `getJourney()`
-
-Returns the customer journey as an array of touchpoints (up to 30).
-
-```typescript
-getJourney(): TouchPoint[]
-```
-
-```typescript
 interface TouchPoint {
   timestamp: number;
   source?: string;
@@ -507,75 +514,130 @@ interface TouchPoint {
 }
 ```
 
----
+First touch and last touch persist for `attributionWindow`, 90 days by default. The
+journey keeps the last 30 touchpoints.
 
-### Super Properties
+### Click IDs captured
 
-Super properties are included with every subsequent event.
+The SDK reads these 16 parameters from the URL. Matching is **case-sensitive**.
+They are listed in precedence order, down the left column then down the right.
 
-#### `setSuperProperties(properties)`
+| Parameter | Platform | Parameter | Platform |
+| --- | --- | --- | --- |
+| `fbclid` | Meta | `li_fat_id` | LinkedIn |
+| `gclid` | Google Ads | `sclid` | Snapchat |
+| `gbraid` | Google Ads, iOS | `dclid` | Google Display |
+| `wbraid` | Google Ads, web | `epik` | Pinterest |
+| `ttclid` | TikTok | `rdt_cid` | Reddit |
+| `oppref` | OpenAI Ads | `obclid` | Outbrain |
+| `msclkid` | Microsoft | `irclid` | Impact |
+| `twclid` | X | `ko_click_id` | Klaviyo |
 
-Merge properties into the super properties store.
+Two parameters are normalized to a canonical name:
 
-```typescript
-setSuperProperties(properties: Record<string, any>): void
-```
+| In the URL | Stored as |
+| --- | --- |
+| `ScCid`, `sccid` | `sclid` |
+| `irclickid` | `irclid` |
 
-```javascript
-datalyr.setSuperProperties({ app_version: '2.1.0', environment: 'production' });
-```
+A URL carrying several click IDs sends all of them. `clickIdType` takes the first match in
+the order of the table above. Any click ID forces `medium` to `cpc`.
 
-#### `unsetSuperProperty(propertyName)`
+`oppref` (OpenAI Ads) is captured **as of 1.7.8**. Earlier versions did not, so OpenAI Ads
+web conversions from 1.7.7 and below delivered with `attribution_type: none` unless the
+value was passed by hand. It is ordered after the Google click IDs, matching the iOS and
+React Native SDKs, so it never outranks `fbclid` or `gclid` on a URL carrying both.
 
-Remove a single super property by key.
+### Campaign parameters captured
 
-```typescript
-unsetSuperProperty(propertyName: string): void
-```
+| Group | Parameters |
+| --- | --- |
+| UTM | `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content` |
+| Always captured | `lyr`, `ref`, `source`, `campaign`, `medium`, `gad_source` |
+| Your `trackedParams` | Added to the rows above, never replacing them |
 
-```javascript
-datalyr.unsetSuperProperty('environment');
-```
+Each UTM is sent twice, under its full name and its stripped alias. `utm_source` also
+arrives as `source`.
 
-#### `getSuperProperties()`
+### Ad platform cookies read
 
-Returns a copy of the current super properties.
+| Platform | Cookies | Survives a marketing decline |
+| --- | --- | --- |
+| Meta | `_fbp`, `_fbc` | No |
+| Google Ads | `_gcl_aw`, `_gcl_dc`, `_gcl_gb`, `_gcl_ha`, `_gac` | No |
+| Google Analytics | `_ga`, `_gid` | Yes |
+| TikTok | `_ttp`, `_ttc` | No |
+| Snapchat | `_scid` | No |
 
-```typescript
-getSuperProperties(): Record<string, any>
-```
+Campaign parameters survive a marketing decline.
+
+The SDK writes `_fbc` and `_fbp` itself when an `fbclid` arrives and Meta has not set
+them. Both last 90 days.
 
 ---
 
-### Privacy and Consent
+## Checkout metadata
 
-#### `optOut()`
+```javascript
+const stripe = datalyr.getStripeMetadata();
+// { client_reference_id: 'anon_...', metadata: { visitor_id: 'anon_...' } }
 
-Opt the user out of all tracking. Clears the event queue and persists the preference in a cookie.
+const whop = datalyr.getWhopCheckoutMetadata();
+// { visitor_id: 'anon_...' }
+```
+
+Pass `getStripeMetadata()` into the Stripe object your server creates.
 
 ```javascript
-datalyr.optOut();
+// Server receives this from the browser, then creates the PaymentIntent
+stripe.paymentIntents.create({
+  amount: 4999,
+  currency: 'usd',
+  metadata: datalyrStripeMetadata.metadata,
+});
 ```
 
-#### `optIn()`
+The Datalyr Stripe webhook reads `client_reference_id` on a Checkout Session and
+`metadata.visitor_id` on every other Stripe object.
 
-Opt the user back in.
+### Automatic Stripe link decoration
 
-```javascript
-datalyr.optIn();
-```
+With `stripePaymentLinks: true`, the default, the SDK stamps:
 
-#### `isOptedOut()`
+| Surface | Receives |
+| --- | --- |
+| `<a>` links to `buy.stripe.com`, plus any host in `stripeLinkDomains` | `client_reference_id`, and `prefilled_email` when an email is known |
+| `<stripe-pricing-table>`, `<stripe-buy-button>` | The `client-reference-id` attribute only, never an email |
 
-Returns `true` if the user has opted out.
+The SDK skips `prefilled_email` when `prefilled_email` or `locked_prefilled_email` is
+already present, or when `privacyMode` is `'strict'`. It re-stamps on click and watches
+the DOM for new links, debounced at 150 ms.
+
+> **The SDK never decorates `checkout.stripe.com` URLs.** Stripe ignores these parameters
+> on an already-created Checkout Session. The SDK also cannot reach links opened with
+> `window.open()`, links inside an iframe, or links in shadow DOM. Call `getVisitorId()`
+> and pass the value yourself in those cases.
+
+---
+
+## Super properties
+
+Super properties attach to every later event. `reset()` clears them.
 
 ```typescript
-isOptedOut(): boolean
+setSuperProperties(properties: Record<string, any>): void
+unsetSuperProperty(propertyName: string): void
+getSuperProperties(): Record<string, any>
 ```
 
-#### `setConsent(consent)`
+```javascript
+datalyr.setSuperProperties({ app_version: '2.1.0', environment: 'production' });
+datalyr.unsetSuperProperty('environment');
+```
 
-Set granular consent preferences.
+---
+
+## Privacy and consent
 
 ```typescript
 setConsent(consent: ConsentConfig): void
@@ -586,7 +648,7 @@ datalyr.setConsent({
   analytics: true,
   marketing: false,
   preferences: true,
-  sale: false       // CCPA "Do Not Sell"
+  sale: false,       // CCPA "Do Not Sell"
 });
 ```
 
@@ -599,42 +661,36 @@ interface ConsentConfig {
 }
 ```
 
-#### Privacy Modes
+`setConsent()` is safe to call before `init()`. The SDK persists the choice and applies it
+at initialization.
 
-```javascript
-// Standard mode (default) - normal fingerprinting + tracking
-datalyr.init({ workspaceId: '...', privacyMode: 'standard' });
+| Method | Effect |
+| --- | --- |
+| `optOut()` | Stops all tracking. Clears the queue. Writes the `__dl_opt_out` cookie. Stops Stripe link decoration. |
+| `optIn()` | Resumes tracking. |
+| `isOptedOut(): boolean` | The current opt-out state. |
 
-// Strict mode - minimal data collection, no fingerprinting
-datalyr.init({ workspaceId: '...', privacyMode: 'strict' });
-```
+`privacyMode: 'strict'` forces `autoIdentify` off, turns off fingerprinting, and stops
+email prefill on Stripe links. The SDK honors Global Privacy Control by default. It
+ignores Do Not Track unless `respectDoNotTrack` is `true`.
 
-The SDK also respects `respectDoNotTrack` and `respectGlobalPrivacyControl` config flags.
+```javascript
+datalyr.init({ workspaceId: 'YOUR_WORKSPACE_ID', privacyMode: 'strict' });
+```
 
 ---
 
-### Queue and Network
-
-#### `flush()`
-
-Manually flush the event queue. Returns a promise that resolves when all queued events are sent.
+## Queue, network, and limits
 
 ```typescript
 flush(): Promise<void>
+getNetworkStatus(): NetworkStatus
 ```
 
 ```javascript
 await datalyr.flush();
 ```
 
-#### `getNetworkStatus()`
-
-Returns the current network status as tracked by the SDK.
-
-```typescript
-getNetworkStatus(): NetworkStatus
-```
-
 ```typescript
 interface NetworkStatus {
   isOnline: boolean;
@@ -643,48 +699,75 @@ interface NetworkStatus {
 }
 ```
 
-Events are automatically stored when offline and sent when connectivity returns.
+The SDK stores events while the browser is offline and sends them when connectivity
+returns.
 
----
+| Limit | Value |
+| --- | --- |
+| Events per batch | 10, configurable to 1000 through `batchSize` |
+| Flush interval | 5000 ms |
+| High-priority flush | 1000 ms |
+| Retries per batch | 5 |
+| Offline queue | 100 events. The oldest is dropped first. |
+| `keepalive` request body | 60000 bytes |
+| `sendBeacon` chunk | 60000 bytes |
+| Duplicate suppression | The last 1000 event hashes |
+| Journey length | 30 touchpoints |
+| Property nesting depth | 5 |
+| Error buffer | 50 |
+| Container script fetch | 3000 ms timeout |
 
-### Container Scripts
+There is no per-event size limit. Only the transport limits above apply.
 
-Container scripts manage third-party tracking pixels (Meta, Google, TikTok) configured in your Datalyr dashboard.
+### How failed requests behave
 
-#### `loadScript(scriptId)`
+| Response | Behavior |
+| --- | --- |
+| `429` | The SDK waits for `Retry-After`, default 60 seconds. The batch moves to the offline queue. |
+| `403` | The SDK backs off for 5 minutes and parks the batch in the offline queue. Origin configuration changes, so the batch is not discarded. |
+| Other `4xx`, except `408` | Dropped permanently. Never retried. This is what a wrong `workspaceId` produces. |
+| `5xx`, `408`, network failure | Retried with exponential backoff, up to `maxRetries`, then tried against each `fallbackEndpoints` host. |
 
-Trigger a container script by ID.
+---
 
-```typescript
-loadScript(scriptId: string): void
-```
+## Storage
 
-```javascript
-datalyr.loadScript('custom-script-id');
-```
+| Cookie | Value | Lifetime |
+| --- | --- | --- |
+| `__dl_visitor_id` | The `visitor_id` | 365 days |
+| `__dl_opt_out` | `true` or `false` | `cookieExpires` |
+
+The SDK writes `__dl_visitor_id` on the root domain with `SameSite=Lax`, and `Secure` on
+HTTPS. A failed root-domain write falls back to a host-only cookie.
+
+State lives in `localStorage` under a double `dl_dl_` prefix: `dl_dl_anonymous_id`,
+`dl_dl_user_id`, `dl_dl_journey`, `dl_dl_first_touch`, `dl_dl_last_touch`,
+`dl_dl_offline_queue`. Traits and the captured email are encrypted with AES-GCM.
+
+---
 
-#### `getLoadedScripts()`
+## Container scripts
 
-Returns an array of loaded script IDs.
+Container scripts are the third-party pixels you configure in the Datalyr dashboard. The
+container is built into `dl.js` and into the npm package. It loads on init. There is no
+separate container snippet to install.
 
 ```typescript
+loadScript(scriptId: string): void
 getLoadedScripts(): string[]
 ```
 
-The container is built into the `dl.js` tag — it loads your dashboard-configured pixels on init, so there's no separate container script to install:
-
-```html
-<script defer src="https://track.datalyr.com/dl.js"
-        data-workspace-id="YOUR_WORKSPACE_ID"></script>
+```javascript
+datalyr.loadScript('custom-script-id');
+console.log(datalyr.getLoadedScripts());
 ```
 
----
-
-### Debugging
+The SDK skips the container when `enableContainer` is `false`, when the visitor opted
+out, when `privacyMode` is `'strict'`, or when marketing consent is declined.
 
-#### `getErrors()`
+---
 
-Returns an array of SDK errors (up to 50 most recent).
+## Debugging
 
 ```typescript
 getErrors(): ErrorInfo[]
@@ -704,40 +787,32 @@ interface ErrorInfo {
 console.log(datalyr.getErrors());
 ```
 
-Enable `debug: true` in config to log all SDK activity to the console.
-
----
-
-### Lifecycle
-
-#### `destroy()`
+`getErrors()` returns the 50 most recent SDK errors. Set `debug: true` to log all SDK
+activity to the console.
 
-Tear down the SDK instance. Restores patched `history.pushState` / `replaceState`, removes event listeners, cleans up the queue, session, container iframes, auto-identify listeners, and encryption keys. Resets all in-memory state.
+### destroy()
 
 ```typescript
 destroy(): void
 ```
 
-```javascript
-datalyr.destroy();
-```
+`destroy()` restores the patched `history.pushState` and `history.replaceState`, removes
+every listener, and clears the queue, the session, container iframes, auto-identify
+listeners, and encryption keys. Use it only when you tear the integration down for good.
 
 ---
 
-## Web-to-App Attribution
-
-Track users who click a "Download App" button on your website and attribute their app install back to the original web session.
-
-### Flow
+## Web-to-app attribution
 
-1. User clicks an ad and lands on your page (web SDK captures `fbclid`, UTMs, etc.)
-2. User clicks "Download App" -- `trackAppDownloadClick()` fires with full attribution
-3. User installs from App Store / Play Store
-4. First app open -- mobile SDK recovers the web attribution:
-   - **Android**: Deterministic match via Play Store `referrer` parameter (~95% accuracy)
-   - **iOS**: IP-based match against recent web events within 24 hours (~90%+ accuracy)
+```typescript
+trackAppDownloadClick(options: {
+  targetPlatform: 'ios' | 'android';
+  appStoreUrl: string;
+}): Promise<void>
+```
 
-### Usage
+`trackAppDownloadClick()` fires a `$app_download_click` event with full attribution,
+flushes through `sendBeacon`, then redirects to the store URL.
 
 ```javascript
 document.querySelector('#download-btn').addEventListener('click', () => {
@@ -749,39 +824,45 @@ document.querySelector('#download-btn').addEventListener('click', () => {
 ```
 
 ```javascript
-// Android - attribution params auto-encoded into Play Store referrer
 datalyr.trackAppDownloadClick({
   targetPlatform: 'android',
   appStoreUrl: 'https://play.google.com/store/apps/details?id=com.yourapp',
 });
 ```
 
-### Requirements
+For an Android Play Store URL, the SDK encodes the attribution parameters into the
+`referrer` query parameter.
 
-- Web SDK initialized on the prelander page
-- Mobile SDK (`@datalyr/react-native` or `@datalyr/swift`) installed in the app
-- Attribution is recovered automatically on first app launch
+The mobile SDK recovers the web attribution on first app open:
+
+| Platform | Match |
+| --- | --- |
+| Android | Deterministic, through the Play Store `referrer` parameter |
+| iOS | IP-based, against web events from the last 24 hours |
+
+This flow needs the Web SDK on the prelander page, and `@datalyr/react-native` or
+`@datalyr/swift` in the app.
 
 ---
 
-## SPA Support
+## SPA support
 
-Route changes are tracked automatically when `trackSPA: true` (the default). The SDK patches `history.pushState`, `history.replaceState`, and listens for `popstate` and `hashchange` events. Attribution cache is cleared on each navigation so new URL parameters are captured.
+The SDK tracks route changes while `trackSPA` is `true`, the default. It patches
+`history.pushState` and `history.replaceState`, and listens for `popstate` and
+`hashchange`. It clears the attribution cache on each navigation, so new URL parameters
+are captured.
 
 ```javascript
 datalyr.init({
   workspaceId: 'YOUR_WORKSPACE_ID',
-  trackSPA: true,        // default
-  trackPageViews: true,  // auto-track initial page view, default
+  trackSPA: true,
+  trackPageViews: true,
 });
-
-// Manual page tracking
-datalyr.page({ title: 'Product Details', product_id: 'SKU-123' });
 ```
 
 ---
 
-## Framework Integration
+## Framework integration
 
 ### React
 
@@ -825,6 +906,9 @@ const trackClick = () => {
 
 ### Next.js
 
+SDK methods run in the browser only. Call them inside `useEffect` or another client-side
+hook.
+
 ```tsx
 // app/providers.tsx
 'use client';
@@ -842,7 +926,9 @@ export function AnalyticsProvider({ children }: { children: React.ReactNode }) {
 
   return <>{children}</>;
 }
+```
 
+```tsx
 // app/layout.tsx
 import { AnalyticsProvider } from './providers';
 
@@ -861,8 +947,6 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 
 ## TypeScript
 
-All types are exported from the package:
-
 ```typescript
 import datalyr from '@datalyr/web';
 import type {
@@ -882,9 +966,7 @@ import type {
   ErrorInfo,
   PerformanceMetrics,
 } from '@datalyr/web';
-```
 
-```typescript
 const properties: EventProperties = {
   product_id: 'SKU-123',
   price: 99.99,
@@ -900,7 +982,7 @@ const traits: UserTraits = {
 datalyr.identify('user_123', traits);
 ```
 
-### Plugin Interface
+### Plugin interface
 
 ```typescript
 interface DatalyrPlugin {
@@ -915,56 +997,40 @@ interface DatalyrPlugin {
 
 ---
 
-## Troubleshooting
+## Verify the install
 
-### Events not appearing
+1. Open your published site in a private window.
+2. Open **Events** in Datalyr.
+3. Confirm a `pageview` arrives with your URL, within 30 seconds.
 
-1. Verify `workspaceId` is correct.
-2. Set `debug: true` and check the console.
-3. Confirm `datalyr.getAnonymousId()` returns a value.
-4. Check the Network tab for requests to `ingest.datalyr.com`.
-5. Disable ad blockers or privacy extensions.
+When nothing arrives, set `debug: true`, then call `getErrors()` and `getNetworkStatus()`.
+
+---
+
+## Troubleshooting
 
-### SDK not initialized
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| No events, network tab shows a `4xx` | Wrong `workspaceId`. The batch is dropped with no retry. | Copy the ID from **Settings → Tracking → Install** |
+| No events, no network request | `init()` never ran, or the visitor opted out | Call `datalyr.getWorkspaceId()` and `datalyr.isOptedOut()` |
+| No events, requests blocked | An ad blocker or a privacy extension | Test in a clean private window |
+| A session expires on every event | `sessionTimeout` was set in minutes | Set it in milliseconds: `3600000` for 60 minutes |
+| Attribution disappears after a few days | `attributionWindow` was set in days | Set it in milliseconds: `7776000000` for 90 days |
+| Two `visitor_id` values for one person | The script tag and the npm package both loaded | Remove one |
+| Conversions do not link to the visit | `reset()` runs on page load | Call `reset()` on logout only |
+| A Snapchat or Impact click is not attributed | Uppercase or alias parameter | The SDK maps `ScCid`, `sccid`, and `irclickid` on its own. Confirm the parameter reaches the landing URL. |
+| Stripe conversions are unattributed | A `checkout.stripe.com` link | Pass `getStripeMetadata()` from your server, or use a `buy.stripe.com` link |
+| `undefined` from every getter | `init()` never ran | Call `datalyr.init()` first |
 
 ```javascript
-console.log('Anonymous ID:', datalyr.getAnonymousId());
+console.log('Workspace:', datalyr.getWorkspaceId());
+console.log('Visitor ID:', datalyr.getVisitorId());
 console.log('Session ID:', datalyr.getSessionId());
 console.log('User ID:', datalyr.getUserId());
 console.log('Network:', datalyr.getNetworkStatus());
 console.log('Errors:', datalyr.getErrors());
 ```
 
-If these return `undefined`, the SDK is not initialized. Call `datalyr.init()` first.
-
-### Async initialization
-
-`init()` returns synchronously, but encryption and container loading happen asynchronously. If you need to ensure everything is ready before tracking:
-
-```javascript
-datalyr.init({ workspaceId: '...' });
-await datalyr.ready();
-datalyr.track('post_init_event');
-```
-
-### Next.js SSR
-
-SDK methods only work in the browser. Always call them inside `useEffect` or other client-side hooks:
-
-```jsx
-'use client';
-import { useEffect } from 'react';
-import datalyr from '@datalyr/web';
-
-useEffect(() => {
-  datalyr.init({ workspaceId: '...' });
-}, []);
-```
-
-### Script tag vs NPM
-
-Use one installation method, not both. Using both creates duplicate instances.
-
 ---
 
 ## License