@ventiveiq/js

Core JavaScript and TypeScript SDK for sending page views, custom events, and user identity data to VentiveIQ. It supports ES modules, CommonJS, browser script tags, browser privacy signals, and persistent consent controls.

Installation

npm install @ventiveiq/js

Create an analytics instance

import { createVentiveIQ } from "@ventiveiq/js";

const analytics = createVentiveIQ({
  host: "https://api.ventiveiq.com",
  writeKey: "key:secret",
  siteKey: "my-site",
});

host is required. Creating an instance does not automatically send a page event when the package is imported as a module; call page() when appropriate.

Send events

Page views

await analytics.page();

await analytics.page({
  title: "Pricing",
  path: "/pricing",
  section: "marketing",
});

In a browser, the SDK automatically enriches events with available page, referrer, screen, locale, campaign, Facebook, and GA4 context.

Custom events

await analytics.track("signup_clicked", {
  plan: "pro",
  placement: "pricing-page",
});

Identify users

await analytics.identify("user-123", {
  email: "[email protected]",
  name: "Example User",
  plan: "pro",
});

The user ID and traits are persisted and attached to later page and track events. Clear them when the user signs out:

analytics.reset();

You can inspect the current identity with:

const anonymousId = analytics.getAnonymousId();
const userId = analytics.getUserId();

Browser script tag

The browser bundle initializes itself, exposes an instance on window, and sends an initial page view unless data-init-only is enabled.

<script
  src="https://cdn.ventiveiq.com/v1/ventiveiq.js"
  data-host="https://api.ventiveiq.com"
  data-write-key="key:secret"
  data-site-key="my-site"
></script>

<script>
  window.ventiveiq.track("signup_clicked", { plan: "pro" });
</script>

Queue calls before the script loads

<script>
  window.ventiveiqQ = window.ventiveiqQ || [];
  window.ventiveiqQ.push(function (analytics) {
    analytics.identify("user-123", { plan: "pro" });
  });
</script>

<script
  async
  src="https://cdn.ventiveiq.com/v1/ventiveiq.js"
  data-host="https://api.ventiveiq.com"
></script>

Queued entries must be functions that receive the initialized analytics instance. After initialization, new queue entries execute immediately.

Script attributes

| Attribute | Default | Description | | --- | --- | --- | | data-host | Script origin | VentiveIQ API base URL. | | data-write-key | — | Authentication key in key:secret format. | | data-site-key | — | Site or source identifier. | | data-debug | false | Enables SDK debug logging. | | data-init-only | false | Prevents the automatic initial page event. | | data-cookie-domain | Detected | Overrides the persistent cookie domain. | | data-namespace | ventiveiq | Changes the global instance and queue names. | | data-respect-dnt | true | Honors browser Do Not Track. | | data-respect-gpc | true | Honors Global Privacy Control. | | data-consent-analytics | Unset | Initial analytics consent. | | data-consent-marketing | Unset | Initial marketing consent. | | data-consent-advertising | Unset | Initial advertising consent. |

Boolean attributes accept true, 1, or yes; other non-empty values are treated as false.

Privacy and consent

DNT and GPC are respected by default. Configure initial consent when creating the instance:

const analytics = createVentiveIQ({
  host: "https://api.ventiveiq.com",
  privacy: {
    respectDnt: true,
    respectGpc: true,
    consent: {
      analytics: true,
      marketing: true,
      advertising: false,
    },
  },
});

If any configured consent category is false, event delivery is blocked. Consent changes are persisted in a cookie:

analytics.setConsent({
  analytics: true,
  marketing: false,
  advertising: false,
});

console.log(analytics.getConsent());
console.log(analytics.isBlocked());

Use the full opt-out controls when a user disables all tracking:

analytics.optOut();
analytics.isBlocked(); // true

analytics.optIn();

optIn() clears the explicit opt-out, but it does not override DNT, GPC, or a denied consent category.

Configuration

import type { VentiveIQConfig } from "@ventiveiq/js";

const config: VentiveIQConfig = {
  host: "https://api.ventiveiq.com",
  writeKey: "key:secret",
  siteKey: "my-site",
  debug: false,
  cookieDomain: ".example.com",
  fetch: globalThis.fetch,
  privacy: {
    respectDnt: true,
    respectGpc: true,
    userOptedOut: false,
    consent: {
      analytics: true,
      marketing: true,
      advertising: true,
    },
  },
};

| Option | Required | Description | | --- | --- | --- | | host | Yes | Base URL of the VentiveIQ API. | | writeKey | No | Authentication value sent in the X-Write-Key header. | | siteKey | No | Site or source identifier included with events. | | debug | No | Logs configuration and request information. | | cookieDomain | No | Cookie domain used for identity and privacy persistence. | | fetch | No | Custom Fetch-compatible function, useful in server runtimes. | | privacy | No | DNT, GPC, opt-out, and consent configuration. | | initOnly | No | Used by the browser entry point to skip its initial page event. |

Avoid ending host with /; endpoint paths are appended to this value.

Node.js and server runtimes

The SDK uses memory storage when browser APIs are unavailable. Provide a Fetch implementation if the runtime does not expose globalThis.fetch:

const analytics = createVentiveIQ({
  host: "https://api.ventiveiq.com",
  fetch: customFetch,
});

await analytics.track("server_event", { source: "worker" });

Memory-backed identity lasts only for the lifetime of that analytics instance. Browser page context and cookies are not available in server runtimes.

Failure behavior

Network failures and non-successful HTTP responses are logged and events are dropped. They do not reject page, track, or identify, so an unavailable analytics host does not stop the host application. Enable debug while troubleshooting request configuration.

Disabled or fallback mode

emptyAnalytics implements the complete SDK interface without sending events:

import { createVentiveIQ, emptyAnalytics } from "@ventiveiq/js";

const analytics = analyticsEnabled
  ? createVentiveIQ({ host: "https://api.ventiveiq.com" })
  : emptyAnalytics;

await analytics.track("safe_noop_when_disabled");

Standalone privacy plugin

The privacy layer can also be used with the analytics package directly:

import Analytics from "analytics";
import { privacyPlugin } from "@ventiveiq/js";

const analytics = Analytics({
  app: "my-app",
  plugins: [
    privacyPlugin({
      respectDnt: true,
      respectGpc: true,
      consent: { analytics: true },
    }),
  ],
});

List the privacy plugin before provider plugins so blocked events are aborted before a provider receives them.

API summary

| Export | Purpose | | --- | --- | | createVentiveIQ | Creates a configured analytics instance. | | emptyAnalytics | No-op implementation for disabled or fallback states. | | privacyPlugin | Standalone privacy plugin for analytics. | | ventiveiqPlugin | Low-level VentiveIQ provider plugin. | | VentiveIQConfig | SDK configuration type. | | VentiveIQInstance | Public instance interface. | | ConsentPreferences | Consent-category type. | | PrivacyConfig | Privacy configuration type. | | VentiveIQEvent | Outbound event-envelope type. | | EventContext | Enriched event-context type. |