@nvisiondata/sdk-web

Browser SDK for NvisionData. Cookieless-by-default, consent-aware. Default bundle (core + 14 auto-collection plugins) is ~8 KB gzipped / 24 KB raw; see Bundle size for how to ship the ~4 KB core-only build. See SPEC.md § 6, § 7 for the underlying data model.

Install

pnpm add @nvisiondata/sdk-web

Or via CDN. Always use defer + a preconnect hint — without those, the script tag is parser-blocking and costs 100–300 ms FCP/LCP on first load. Both fixes are zero-code-change wins:

<link rel="preconnect" href="https://ingest.nvisiondata.com" crossorigin />
<script defer src="https://cdn.nvisiondata.com/sdk-web/v0/nvisiondata.min.js"></script>
<script defer>
  // `defer` scripts execute in document order AFTER HTML parsing
  // finishes, so this inline init runs once the SDK above is ready.
  // (We use `defer` rather than `async` because `async` doesn't
  // preserve order — a `_nvq` queue pattern is on the roadmap for
  // when we want true `async` loading; until then `defer` gives the
  // perf win without that complexity.)
  NvisionData.init({ propertyId: 'prop_1' });
</script>

The preconnect to ingest.nvisiondata.com lets the browser open the DNS + TLS connection in parallel with bundle download, so the first /collect request races the warm path instead of paying it cold.

Bundle size

The default IIFE bundle (core transport + 14 auto-collection plugins) measures ~8 KB gzipped / ~24 KB raw as of v0.1. A core-only build (transport + consent + page_view, no plugins) is on the roadmap and targets ≤4 KB gzipped — track via S5-013 in the analytics-prod prd.

Usage

import { nvisiondata } from '@nvisiondata/sdk-web';

nvisiondata.init({
  propertyId: 'prop_1',
  endpoint: 'https://ingest.nvisiondata.com/collect',
  // Start denied — flip to granted after the CMP runs.
  consent: { analytics_storage: false, ad_storage: false },
});

// Later, after consent:
nvisiondata.setConsent({ analytics_storage: true, ad_storage: true });

// Track:
nvisiondata.track('add_to_cart', { product_id: 'sku_42' }, { category: 'ecommerce' });
nvisiondata.track('purchase', { order_id: 'ord_9001' }, { revenue: 49.99, currency: 'USD' });

Consent semantics

The SDK mirrors Google Consent Mode v2 signals — four booleans, default denied. Events are sent regardless; the server records the consent vector and downstream activation/reporting respects it. That's the difference between "no data" and "no personalized data" — we aim for the latter.

Privacy

• No canvas / font / audio fingerprinting.
• No third-party cookies.
• anon_id lives in localStorage only when analytics_storage is granted. Otherwise the collector derives a daily-rotating pseudonym from (masked_ip, ua_class, date, tenant_salt).
• Respects DNT and GPC — set respectDoNotTrack: false to override.