Marver Web SDK

@chip-hosting/analytics

The Marver Web SDK — a lightweight, first-party browser analytics SDK for Marver, Chip Hosting's analytics platform (formerly Data Workbench). Capture page views, custom events, and user identity, batch them efficiently, and ship them to your own Sensor endpoint. No third-party cookies, consent-aware by design, ~tiny footprint.

• First-party — events go to your endpoint, not a vendor's.
• Batched + resilient — events queue, batch, and retry; flushed on beforeunload/pagehide.
• Consent-aware — every event carries a consent category for server-side enforcement.
• Auto-track plugins — page views (incl. SPA route changes), clicks, and form submits.
• Zero-dependency, ESM + CDN — import it or drop a <script> tag.

Installation

npm install @chip-hosting/analytics

Quick start

ES modules / bundler

import dwb from '@chip-hosting/analytics';

dwb.init({
  endpoint: 'https://sensor.yourcompany.com',
  clientId: 'your-website',
});

dwb.page();                                       // track current page view
dwb.track('button_click', { buttonId: 'signup' }); // custom event
dwb.identify('user123', { email: '[email protected]' });

CDN / script tag

The SDK attaches itself to window.dwb when loaded via a script tag.

<script src="https://cdn.chip-hosting.com/marver/v1/dwb-analytics.min.js"></script>
<script>
  dwb.init({ endpoint: 'https://sensor.yourcompany.com', clientId: 'your-website' });
  dwb.page();
</script>

Configuration

dwb.init(config) accepts:

| Option | Type | Default | Description | |--------|------|---------|-------------| | endpoint | string | required | Sensor endpoint URL, e.g. https://sensor.yourcompany.com. | | clientId | string | required | Client / application identifier. | | cookieDomain | string | — | Cookie domain for the visitor ID, e.g. .yourcompany.com. | | batchSize | number | 5 | Events to batch before sending. | | flushInterval | number | 5000 | Auto-flush interval in ms. | | maxRetries | number | 3 | Max retry attempts for failed requests. | | debug | boolean | false | Enable debug logging. | | useProxy | boolean | false | Route through an Edge Function proxy instead of the Sensor directly. | | proxyEndpoint | string | — | Proxy URL (required when useProxy is true). | | autoCollect | AutoCollectConfig \| boolean | true | Auto-collect browser context per event (see below). | | autoTrack | AutoTrackConfig | { pageView: true, click: false, formSubmit: false } | Auto-track plugin toggles (see below). |

Auto-collected context (autoCollect)

When enabled (default), each event is enriched with context. Pass true/false to toggle all, or an object to enable categories individually: screen, browser, locale, utm, device, performance, network.

dwb.init({
  endpoint: '...',
  clientId: '...',
  autoCollect: { utm: true, device: true, performance: false },
});

Auto-track plugins (autoTrack)

| Plugin | Default | What it does | |--------|---------|--------------| | pageView | true | Tracks the initial page view plus SPA pushState/popstate route changes. | | click | false | Tracks clicks on elements matching selectors.click. | | formSubmit | false | Tracks submits on forms matching selectors.form. |

dwb.init({
  endpoint: '...',
  clientId: '...',
  autoTrack: {
    pageView: true,
    click: true,
    formSubmit: true,
    selectors: { click: '[data-track]', form: 'form.lead' },
  },
});

API

| Method | Description | |--------|-------------| | init(config) | Initialize the SDK. Must be called once before tracking. | | track(event, properties?) | Track a custom event with optional properties. | | page(path?) | Track a page view (defaults to the current path). | | identify(userId, traits?) | Associate the visitor with a known user. Traits: email, customerId, deviceId, phone, plus any custom string fields. | | reset() | Clear user identity (e.g. on logout). | | flush() | Manually flush the queued events. | | getVisitorId() | Current anonymous visitor ID. | | getSessionId() | Current session ID. | | getUserId() | Current identified user ID, if any. | | isInitialized() | Whether init() has run. | | destroy() | Tear down the instance and remove listeners. |

Consent

Events carry a consent category — analytics, marketing, personalization, or functional — so your Sensor can enforce consent server-side. Events default to the analytics category.

Advanced usage

For custom pipelines, the building blocks are exported directly:

import {
  Analytics,
  CookieManager,
  HttpTransport,
  EventQueue,
  ContextCollector,
  ClickTracker,
} from '@chip-hosting/analytics';

Type exports: DataWorkbenchConfig, IdentityTraits, EventProperties, IdentityPayload, AutoCollectConfig, AutoTrackConfig.

License

MIT