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:
| Property | Description |
|---|---|
hostname | Hostname of server |
language | Browser language |
referrer | Page referrer |
screen | Screen dimensions (e.g. 1920x1080) |
title | Page title |
url | Page URL |
project | Project 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 Type | Limit |
|---|---|
| Numbers | Max precision of 4. |
| Strings | Max length of 500. |
| Arrays | Converted to a string, max length of 500. |
| Objects | Max 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 browserlocalStorage. Ifreset()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. Callingreset()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.