Skip to Content
API ReferenceJavaScript API

JavaScript API Available (v1)

Once the tracking snippet has loaded, it exposes a single global function, visz(...), as a command queue. You call it with a command name and arguments:

visz("event", "add_to_cart", { sku: "SHOE-42", value_num: 49.9 });

The snippet handles batching, transport, consent, and PII masking for you. For most integrations this is the right interface; you almost never call the REST API directly. The commands are consent, event, tag, identify, and shutdown.

How the queue works

The snippet loads with async. Until it has arrived, visz does not exist yet. If you want to call visz(...) earlier, for example above the snippet <script> tag, first set up a small buffer:

window.visz = window.visz || function () { (window.visz.q = window.visz.q || []).push(arguments); };

On start, the snippet reads every call from visz.q and runs them in order.

Consent gate. Nothing is sent before the visitor consents. Calls to visz('event' | 'tag') made before consent are silently dropped (not queued for later). visz('consent', true) is what opens the gate.

Frequency cap. Custom events (event and tag, plus the ones created without code in the dashboard) share a cap of 100 events per session and day. Beyond that, further events are silently discarded. This is a cost-control guard, not an error.


visz('consent', granted)

Grant or withdraw tracking consent. Whether you need this call depends on your website’s consent setting. With Wait for consent, nothing is tracked until consent exists: until you call visz('consent', true), the visitor agrees in the visz.ai cookie banner, or Google Consent Mode v2 grants analytics_storage. With No consent required, tracking starts without this call. Details are in Consent Setup.

Parameters

ArgTypeDescription
grantedbooleantrue grants consent and starts tracking; false withdraws it: the snippet reports the withdrawal one last time, sends pending events, and stops all capture.

Example

// In your cookie-banner "Accept" handler: visz("consent", true); // In your "Reject" / withdraw handler: visz("consent", false);

“Do Not Track” takes precedence: if the browser sends DNT, the snippet stays inert regardless of this call. That only changes if your page explicitly sets window.viszConfig = { dntOverride: true } before the snippet.


visz('event', name, props?)

Record a custom event, that is a named thing that happened such as add_to_cart, signup_completed, or video_played. If visz.ai does not know the name yet, it creates the event when it first arrives; it then shows up under Events & Tags in the dashboard.

Parameters

ArgTypeDescription
namestringEvent name. Empty names are dropped, names longer than 128 characters are shortened.
propsobject (optional)Up to 10 properties. value_num is kept as an unmasked numeric value; numbers and booleans stay unchanged; every string value is PII-masked in the browser and truncated to 200 characters.

Example

visz("event", "add_to_cart", { sku: "SHOE-42", // masked + truncated category: "sneakers", // masked + truncated value_num: 49.9 // kept as a raw number (e.g. for revenue) });

PII defense. Properties are masked in the browser before anything is sent, and once more on the server. The server replaces long, random-looking values with a placeholder. Still, never pass raw PII (emails, names, card numbers) in props; use value_num for amounts and stable, non-identifying labels for everything else.


visz('tag', name)

Sends an event with a reserved flag that marks it as a tag.

Parameters

ArgTypeDescription
namestringTag name. Empty names are dropped, names longer than 128 characters are shortened.

Example

visz("tag", "vip");

In the dashboard, a tag sent this way shows up as an event with that name under Events & Tags, not in the Tags area. You filter recordings by it via Event fired. Tags in the Tags area are set by an automatic rule, see Custom Events & Tags. A tag counts against the same cap of 100 events.


visz('identify', user)

Attaches a pseudonymous user identifier to the following custom events of the current page.

Parameters

ArgTypeDescription
userstring | objectA stable identifier, as a string or as an object with id, user_id, userId, or email. Only a client-side FNV-1a hash of it is computed and attached to subsequent custom events as metadata.uid. The raw value never leaves the browser.

Example

visz("identify", "user_8f31c2");

Pseudonym, not encryption. visz.ai never receives the raw identifier, only the hash. The hash is short and not cryptographic: anyone who knows the possible input values can recompute it. Pass an internal ID rather than an email address. The identifier only applies to the current page; call identify again after every page load.


visz('shutdown')

Immediately stop all tracking for the current page: detaches every capture listener, stops the recording, the survey and feedback widgets and the cookie banner, and sends pending events. Unlike visz('consent', false), shutdown does not report a withdrawal.

Example

visz("shutdown");

Last updated: