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 (
eventandtag, 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
| Arg | Type | Description |
|---|---|---|
granted | boolean | true 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
| Arg | Type | Description |
|---|---|---|
name | string | Event name. Empty names are dropped, names longer than 128 characters are shortened. |
props | object (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; usevalue_numfor 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
| Arg | Type | Description |
|---|---|---|
name | string | Tag 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
| Arg | Type | Description |
|---|---|---|
user | string | object | A 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
identifyagain 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: