Install the web SDK

The web SDK is one file, about 6 KB with gzip, served by datacub. Add it with a script tag; it works with any site or framework.

It collects page views (including single page app routes), page leaves with foreground time and scroll depth, clicks on buttons and links, form submit attempts, and the events you track, with the context listed in what the SDK collects. It starts at the first page view, with no consent step. If you want to wait for your visitors' consent, see asking for consent.

Not on npm. Do not install @datacub/web, or anything else under @datacub, from npm: that npm name does not belong to datacub.

Script tag

For a site without a build step, paste this before </head>. data-key starts the SDK as soon as the file loads.

<script src="https://ingest.datacub.example/v1/sdk/datacub-0.4.0.min.js" data-key="pk_live_YOUR_PROJECT_KEY" defer></script>

Add data-api-host to send through your own proxy.

In an app

In React, Vue, Next.js and other apps with a build step, paste this in the HTML <head> instead. It defines the global datacub at once, so your code can call it before the file has loaded: calls wait in order and run when it arrives. Where the head is in each framework.

<script>
  (function (w, d, src) {
    var q = (w.datacub = w.datacub || [])
    ;['init', 'track', 'identify', 'reset'].forEach(function (n) {
      q[n] = function () { q.push([n].concat([].slice.call(arguments))) }
    })
    var s = d.createElement('script'); s.async = true; s.src = src; d.head.appendChild(s)
  })(window, document, 'https://ingest.datacub.example/v1/sdk/datacub-0.4.0.min.js')
  datacub.init('pk_live_YOUR_PROJECT_KEY')
</script>

Then use the global datacub anywhere in client code, for example datacub.track('signup_completed'). Call it in event handlers and effects, not in code that runs on the server, where x does not exist.

TypeScript

Save the type definitions in your project. They type the global datacub and export the option types (import type { InitOptions } from './x'):

curl -o src/datacub.d.ts https://ingest.datacub.example/v1/sdk/datacub-0.4.0.d.ts

Options

Pass them to datacub.init in the snippet:

OptionDefaultWhat it does
apiHosthttps://ingest.datacub.examplewhere events go: datacub's ingestion host or your proxy. Must be https (or http://localhost)
hashRoutingfalsetreat #/route fragments as pages, for hash routers
autocapturetrueclicks and form submits. Page views and page leaves are always on
releasenoneyour app version or deployment ID, sent with every event
datacub.init('pk_live_YOUR_PROJECT_KEY', { release: '2026.11.1', hashRouting: false })

init runs once; later calls are ignored.

First-party proxy

Some blockers drop requests to analytics hosts. Forward POST /v1/batch from a path on your own domain to datacub's ingestion host, then point the SDK at it:

datacub.init('pk_live_YOUR_PROJECT_KEY', { apiHost: 'https://www.example.sa/datacub' })

The SDK then posts to https://www.example.sa/datacub/v1/batch. Pass the body through unchanged.

What the SDK collects

Besides page views, page leaves and clicks, version 0.2.0 collects the context that explains them:

  • Text of clicked buttons and links: the element's own visible text, at most 100 characters, with emails, phone numbers, IDs and tokens removed. Never text typed into inputs, text areas, selects or editable regions. When a button has no short text, its aria-label, title or image alt is used.
  • Page titles, scrubbed, at most 200 characters.
  • URL query values that read as codes your site put in a link, such as ?sort=price_desc or ?category=shoes. Never what someone typed: searches, names, addresses and messages, anything with a space or over 40 characters, sensitive keys such as token, code, key, secret, password, otp, state and session, and any value a detector flags keep the key with an empty value. ID-like values become :id.
  • JavaScript errors: the message (scrubbed), the top 5 stack frames, with URLs reduced to origin and path.
  • Failed and slow (3 seconds or more) fetch and XHR requests: method, origin and templated path, status and duration. Never the query, headers or bodies.
  • Form interaction details: which fields were started, touched or invalid, and time in each field. Never values, lengths or keystrokes.
  • Device and browser context, once per batch: screen size, pixel ratio, time zone, CPU cores, device memory, touch, pointer, colour scheme, reduced motion and connection. On Chromium also the device model and OS version.
  • Web Vitals, long tasks and resource totals, through the insights module.

Never collected: values typed into forms, passwords, payment data, credentials. Device traits are never used to identify a visitor: the visitor ID stays random. Raw IP addresses are never stored. List these categories in your own privacy notice.

To keep a region out entirely, add data-datacub-no-capture to any element (the datacub-no-capture class also works): nothing inside it is captured.

Choose what is collected

In Settings, Data capture a project has six switches, all on by default: Button and link text, Page titles, URL query values, JavaScript errors, Failed network requests, Form interaction details. When one is off, datacub drops those fields at capture, even from a site that still sends them.

A site can also stop its own SDK from sending them with the capture init option: set any of text, title, query, errors, network and forms to false, for example datacub.init('pk_live_YOUR_PROJECT_KEY', { capture: { text: false, query: false } }). The script tag has no attribute for this; use datacub.init.

insights: false does not load the insights module at all (Web Vitals, long tasks, resource totals, form field details and device model).

Content Security Policy

If your site sets a Content Security Policy, script-src must allow your ingestion host for both datacub-0.4.0.min.js and insights-0.2.0.min.js (the module loads from https://ingest.datacub.example/v1/sdk/insights-0.2.0.min.js), and connect-src must allow the same host.

What the SDK never sends

Field values, passwords, payment data, credentials, URL fragments and anything inside an element with class="datacub-no-capture" or data-datacub-no-capture. IDs in paths are replaced (/orders/1234 becomes /orders/:id). Values that look like emails, phone numbers, national IDs, card numbers or tokens are redacted on the device and again on the server. Details: privacy.