Crelora Mark SDK

Mark is Crelora's lightweight attribution SDK for capturing user journeys, conversions, and consent across browsers and server-side runtimes. The npm package includes both browser and Node entry points so you can send consistent data from any surface.

Installation

npm install @crelora/mark
# or
yarn add @crelora/mark

CDN / Script Tag Usage

You can also drop the SDK directly into your browser applications via a script tag. This exposes the global window.Mark object.

<!-- Use a CDN like unpkg or jsdelivr -->
<script src="https://unpkg.com/@crelora/mark@latest/dist/browser.umd.js"></script>

<script>
  // Mark is available globally
  Mark.init({
    key: 'pub_xxxxx',
    // ... configuration
  });

  Mark.track('Page View');
</script>

Browser Quickstart

import { Mark } from '@crelora/mark';

Mark.init({
  key: 'pub_xxxxx',
  requireConsent: 'auto',
  crossDomain: { cookieDomain: '.example.com' },
  siteId: 'uuid-...',           // Optional: associate events with a registered site
  siteHost: 'shop.example.com', // Optional: site host for audit/debug
});

Mark.identify('user_123', { 
  email: '[email protected]',
  display_name: 'John Doe',
  language: 'en-US'
});
Mark.track('Checkout Started', { value: 12900, currency: 'usd' });
Mark.setConsent('granted');

// Per-event site overrides (optional)
Mark.track('Conversion', {
  site_id: 'different-site-uuid',  // Overrides init config for this event
  site_host: 'other.example.com',
  value: 5000,
});

Mark.init should be called once during app bootstrap. Subsequent calls to track, identify, or setConsent reuse the same client instance.

Node / Server Usage

import { createNodeMark } from '@crelora/mark/node';

const mark = createNodeMark({
  key: process.env.MARK_SECRET_KEY!,
  siteId: process.env.MARK_SITE_ID,     // Optional: associate events with a registered site
  siteHost: process.env.MARK_SITE_HOST, // Optional: site host for audit/debug
});

await mark.track('Server Conversion', {
  visitor_id: 'vis_abc',
  order_id: 'ord_789',
  value: 19900,
});

The Node factory accepts optional custom storage or transport adapters so you can plug the SDK into queues or serverless environments.

Available Methods

• Mark.init(config) / createNodeMark(config) – bootstraps the client with your publishable or secret key.
• track(eventName, payload?) – records custom events with arbitrary properties (numbers, strings, arrays, objects). The payload can include site_id and site_host to override the values set in init().
• conversion(eventName, payload?) – records conversion events. Currently behaves like track but tags the event with is_conversion: true.
• identify(userId, traits?) – ties a known user identifier to previous anonymous activity. Recommended traits: email, display_name, language. Custom traits are also supported.
• setConsent(status) – enforces consent gating; pass 'granted' or 'denied'.

Automatic Attribution Tracking

The SDK automatically captures and persists the following URL parameters when present on any page load:

• utm_source, utm_medium, utm_campaign, utm_term, utm_content
• ref, referral, affiliate_id (stored as ref)
• click_id, ch_click_id, campaign_id

These parameters are included in every tracked event to ensure proper attribution.

Configuration Reference

| Option | Type | Description | | --- | --- | --- | | key | string | Publishable (browser) or secret (server) key issued in the Crelora dashboard. | | debug | boolean | Enables verbose console logging to help with integration tests. | | requireConsent | boolean \| 'auto' | true blocks tracking until consent is granted, 'auto' honors stored consent, default false. | | autoPageview | boolean | When true, automatically sends page_view on init; defaults to false. | | trackRouteChanges | boolean | When autoPageview is true, also emits on SPA route changes; defaults to true. | | includePageContext | boolean | When true (default), enriches events with url, page, title, referrer, site. | | crossDomain | CrossDomainConfig | Controls cookie domain, bridge URL, and allowlist for multi-domain attribution. | | siteId | string | Optional UUID for associating events with a registered site. Included in all event payloads as site_id. | | siteHost | 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. |

Server runtimes can also pass storage, storageDefaults, or transport via createNodeMark to fully control persistence and delivery.

Consent & Privacy

• Call setConsent('denied') to immediately halt tracking when visitors opt out.
• Use requireConsent: true (or 'auto') to make the SDK wait until a positive consent signal is received.
• Cross-domain mode supports first-party iframe bridges so identifiers remain in your control.
• IP/Geo: IP is never taken from the browser; it is captured server-side, hashed, and used to derive coarse geo (country/region/city, coarse lat/lon) when allowed by consent/tenant settings.

User Identification

The identify() method links anonymous visitors to known users. Recommended traits:

• email (string) - User's email address. Will be hashed server-side for privacy.
• display_name (string) - User's display name or full name.
• language (string) - User's preferred language code (e.g., 'en', 'en-US', 'fr').
• phone (string) - User's phone number. Will be hashed server-side for privacy.

You can also include any custom traits as key-value pairs. All traits are stored in the user profile and can be used for segmentation and personalization.

Mark.identify('user_123', {
  email: '[email protected]',
  display_name: 'John Doe',
  language: 'en-US',
  plan: 'premium',
  signup_date: '2024-01-15',
});

Page Views

• Event name: page_view (canonical). Use display names in your product UI if you prefer human-readable labels.
• Auto-pageview (optional): set autoPageview: true (and optionally trackRouteChanges: true) to emit on first load and SPA route changes. Manual Mark.track('page_view', ...) is always available.

Support

Need help? Reach out through your Crelora account team or file a ticket via the dashboard. Please include the SDK version, runtime (browser or Node), and any reproduction steps so we can assist quickly.