Tracker functions

The Vision tracker exposes a function that you can call on your website if you want more control over your tracking. By default everything is automatically collected, but you can disable this using data-auto-track="false" and sending the data yourself. See Tracker configuration.

Functions

// Tracks the current page
vision.track();

// Custom payload
vision.track(payload: object);

// Custom event
vision.track(event_name: string);

// Custom event with data
vision.track(event_name: string, data: object);

// Identify user with a unique user ID
vision.identify(user_id: string);

// Identify user with traits/properties
vision.identify(user_id: string, data: object);

// User traits without ID
vision.identify(data: object);

// Reset user identity on logout
vision.reset();

Pageviews

Track a page view.

vision.track();

By default the tracker automatically collects the following properties:

PropertyDescription
hostnameHostname of server
languageBrowser language
referrerPage referrer
screenScreen dimensions (e.g. 1920x1080)
titlePage title
urlPage URL
projectProject ID (required)

If you wish to send your own custom payload, pass in an object to the function:

vision.track({
  project: "e676c9b4-11e4-4ef1-a4d7-87001773e9f2",
  url: "/home",
  title: "Home page",
});

The above will only send the properties project, url and title. If you want to include existing properties, pass in a function:

vision.track((props) => ({ ...props, url: "/home", title: "Home page" }));

Events

Track an event with a given name.

vision.track("signup-button");

Event Data

Track an event with dynamic data.

vision.track("signup-button", { plan: "newsletter", id: 123 });

When tracking events, the default properties are included in the payload. This is equivalent to running:

vision.track((props) => ({
  ...props,
  name: "signup-button",
  data: {
    plan: "newsletter",
    id: 123,
  },
}));

Event Data Limits

Event Data can work with any JSON data. There are a few rules in place to maintain performance.

Data TypeLimit
NumbersMax precision of 4.
StringsMax length of 500.
ArraysConverted to a string, max length of 500.
ObjectsMax of 50 properties. Arrays are considered 1 property.

Overriding Event Timestamps

You can override the event timestamp by adding a UNIX timestamp in seconds to the payload:

vision.track((props) => ({
  ...props,
  name: "signup-button",
  timestamp: 1771523787, // new Date().getTime() / 1000
}));

Identify Users

Pass in your own ID to identify a user across visits and sessions.

vision.identify("user_id");

User Traits and Properties

Save profile data and traits about the user (e.g. name, email, plan).

vision.identify("user_id", { name: "Bob", email: "bob@aol.com" });

To save custom traits without a unique ID, pass in only a JSON object:

vision.identify({ name: "Bob", email: "bob@aol.com" });

Reset Identity

[!IMPORTANT] We strongly recommend calling reset() whenever a user logs out.
Vision persists the user's identity in browser localStorage. If reset() is not called when a user logs out, subsequent browsing activity on the device or browser tab will continue to be attributed to the previous user. Calling reset() clears the stored identity and transitions the tracker back to a clean anonymous state.

HTML Script Tag (<script>)

// Call upon user logout
window.vision.reset();

JavaScript / TypeScript SDK (@vision/browser)

import { reset } from "@vision/browser";

// Call upon user logout
reset();

See Autocapture & Identity for full details on identity resolution and session lifecycle.