@crelora/mark 0.2.2 → 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.
@@ -162,6 +164,7 @@ All config options use snake_case. Stored event payloads and database columns ma
 | `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.