SDK reference

b.js sends its first page view straight away, then asks the collector for the project’s settings. r.js and s.js load only once those settings arrive and allow them. If the request fails, neither loads.

A page can only turn replay and page captures off. Whether they run at all is decided by the project, never by the page.

The package exports init(options), track(name, props), consent(granted) and flush(). flush() sends queued events straight away instead of waiting for the next batch.

• The first page view is recorded as soon as the tracker starts.
• Single-page apps are covered: history.pushState, history.replaceState and the back and forward buttons each record a page view for the new route.
• A page view is recorded only when the page changes. By default that means the path plus any UTM parameters. Turn on data-query to count every query change, and data-hash to count hash changes. Either way, the address that is sent keeps only the path and UTM parameters.
• The referrer is sent with the first page view of a page load only, so moving around inside your app is not reported as a referral.
• Scroll depth is the deepest point reached on each page, in steps of 10%.
• Form submissions are described by the element’s structure (tag, id, classes and position). A click on a button, link, tab, menu item, toggle or option also carries the kind of control and its label, so reports name what was clicked. A label never comes from a form field or a masked element: see click labels.
• Events are sent in batches: every five seconds, at 50 events, and when the visitor leaves or hides the page.

Send an event when something happens that a page view cannot show, such as a completed sign-up.

window.webmetric.track("signup_completed", { plan: "growth", seats: 3 });

import { track } from "@webmetric/sdk";

track("signup_completed", { plan: "growth", seats: 3 });

• The name is trimmed and lower-cased, then must be 1 to 64 characters of a to z, 0 to 9, underscore, dot, colon and hyphen. A name that still does not fit is dropped, with one warning in the console.
• Properties are optional. Up to 10 are kept, with keys of up to 40 characters. Numbers and booleans become strings, values are cut to 200 characters, and anything else is left out.
• Never put personal data, such as an email address or a name, in an event name or a property.
• A custom event never counts as a page view. It counts as one event towards your plan.

Custom events are listed on the Events page and can be exported as CSV. Funnel steps match page views, clicks and form submissions.

The script tag loads with defer, so window.webmetric does not exist until it has run. To call it earlier, for example from inline code, add this stub before the script tag. Calls made through it are sent once the tracker starts.

<script>
  window.webmetric = window.webmetric || {
    q: [],
    track: function () { this.q.push(arguments); },
    consent: function (granted) { this.c = granted; },
  };
</script>

With the npm package, calls to track() before init() are kept, up to 50, and sent once it runs.

• Nothing is stored on the visitor’s device: no cookies and no browser storage.
• A browser that sends Do Not Track or Global Privacy Control sends nothing at all.
• Replay masks every form input in the browser, before anything is sent. Page captures mask all of the page’s text as well.
• A click label is the visible name of a button or link, never text from a form field or a masked element, with email addresses and long numbers removed.
• Page addresses are sent without the part after a # or any query parameter other than utm_*, and referrers as origin and path.
• The write key is public by design. It ships in your page source, and it can only write, only to its own project.

The details are in privacy and data collection.