API Reference

You can use our client-side APIs to:

Bring in additional data that Heap does not autocapture, including custom events and properties
Manage user identity across browsers, sessions, and in situations where multiple users are accessing the same device

track

Use this API to send custom events and associated metadata to Heap that we do not automatically capture, such as purchase information, email sent, and more. For best practices and examples of types of events you may want to track, see the Custom Events section of the Enrich Your Dataset Via APIs page of our Setting Up Heap guide.

heap.track('Purchase', {dollars: 50, item: 'Furby'});

Arguments

(required) event name: name of the custom interaction. Limited to 255 characters.
(optional) event properties: a JSON object key-value pairs to be associated with an event. Keys must be a string fewer than 512 characters and values must be a boolean, number or string fewer than 1024 characters.

identify

Use this API to attach a unique identity and maintain user histories across sessions, devices, and browsers under a single profile in Heap. For best practices and use cases for managing identity, see our developer guide on Using Identify.

heap.identify('alice123');

Arguments

(required) identity: a string or number that uniquely identifies a user, such as an email, handle, or username. This means no two users in one environment may share the same identity. Must be fewer than 255 characters.

getIdentity

Use this API to retrieve the current user’s identity, if identified. Use identity to link activity between Heap’s client-side and server-side track APIs.

heap.getIdentity();

resetIdentity

Use this API to reset a user’s identity to an anonymous state after they have logged out. See Using Identify for use cases when managing identity across browsers and devices.

heap.resetIdentity();

addEventProperties

Use this API to send stateful information into Heap as a set of global key-value pairs that get attached to all of a user's subsequent events.

heap.addEventProperties({ 'Logged In': 'true', 'Payment Plan': 'Free' });

Arguments

(required) event properties: a JSON object containing key-value pairs to be associated with every subsequent event. Keys must be a string fewer than 512 characters and values must be a boolean, number or string fewer than 1024 characters.

removeEventProperty

Use this API to stop a single event property from getting attached to all subsequent events. This API is usually called in relation to addEventProperties.

heap.removeEventProperty('Logged In');

Arguments

(required) event property: name of the event property to remove. This stops attaching the property to all subsequent events.

clearEventProperties

Use this API to remove all previously stored event properties from the cookie, which ensures the properties getting added by the next addEventProperties call are always relevant. This API should be called prior to calling the addEventProperties API. It

heap.clearEventProperties();

addUserProperties

Use this API to attach custom properties at the user level, such as user-level info from your database or demographic info.

heap.addUserProperties({ Name: 'Alice Smith', Profession: 'Data Scientist' });

Arguments

(required) user properties: a JSON object containing key-value pairs to be associated with a user. Keys must be a string fewer than 512 characters and values must be a boolean, number or string fewer than 1024 characters.

trackPageview

Use this API to send a new pageview and associated metadata. This api is typically used with the disablePageviewAutocapture configuration. By default, the properties will be pulled from the current page's context. Properties should only be passed when you want to override this data.

var pageviewProperties = {
  title: 'New Title',
  url: 'http://example.com/path/to/home',
  properties: {pageType: 'home', pageVersion: 'v1.0'},
  previous_page: '/path/to/previous-page'
}
heap.trackPageview(pageviewProperties);

Arguments

(optional) properties: a JSON object with optional properties
1. (optional) title accepts a string fewer than 255 characters
2. (optional) urlaccepts a string representing an absolute URL, including a scheme (such as http:// or https://), a domain, a path specifying the location optional query parameters for additional information, and an optional fragment identifier for navigating to specific sections within a webpage
3. (optional) propertiesaccepts a JSON object containing key-value pairs to be associated with a pageview. Keys must be a string fewer than 512 characters and values must be a boolean, number or string fewer than 1024 characters. These properties will override existing pageview properties.
4. (optional) previous_pageaccepts a string represent the path of the previous page (i.e. /path/to/previous-page)

addPageviewProperties

Use this API to attach custom properties at a pageview level. To attach properties to a natural pageview on tag load, you will need to invoke it within an adapter.

heap.addPageviewProperties({pageType: 'productDetail', pageVersion: 'v2.0'});

removePageviewProperty

Use this API to stop a single pageview property from getting attached to all subsequent events. This API is usually called in relation to addPageviewProperties

heap.removePageviewProperty('pageVersion');

clearPageviewProperties

Use this API to remove all previously added pageview properties, which ensures that future events do not retain these properties. It's important to note that pageview properties are automatically cleared upon page refresh or load.

heap.clearPageviewProperties();

onReady

Use this API to define a function that executes once Heap is fully initialized and operational. This serves as a designated entry point for executing tasks or code that depend on the Heap being in a stable and operational state.

function executeOnReady() {
  // This function will be executed when Heap is initialized.
  // You can place your code  here.
  console.log("Heap is now initialized.");
  
  // Example: Make an API call
  // api.doSomething();
  
}

heap.onReady(executeOnReady);

Arguments

(required) callback: function to be executed once Heap loads

getSessionId

Use this API to retrieve the session ID. This API can be used to tie Heap session data to data from external sources.

heap.getSessionId();

getUserId

Use this API to retrieve the current user’s ID.

heap.getUserId();