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'});
heap.track('Purchase', { dollars: 50, item: 'Furby' });
[Heap track:@"Open Album" withProperties:@{@"gallery": @"Picnic Photos", @"pictureCount": @50}];
Heap.track("Open Album", withProperties: ["gallery": "Picnic Photos", "pictureCount": 50])
Map<String, String> props = new HashMap<>();
props.put("gallery", "Picnic Photos");
props.put("pictureCount", String.valueOf(50));
Heap.track("Open Album", props);
Heap.track("Open Album", mutableMapOf(
    "gallery" to "picnic photos",
    "pictureCount" to 50.toString())
  1. (required) event name: name of the custom interaction. Limited to 255 characters.
  2. (optional) event properties: a JSON object, NSDictionary, or Map containing key-value pairs to be associated with an event. Keys must be strings, while values may be a number or a string.

For Android, the properties map may be null to track an event with no properties. The property map keys and values must be converted to strings, but they can be analyzed as numbers in Heap.

Custom event properties can be analyzed in the same fashion as any other event property.


Currently, heap.track calls cannot be named click, change, submit as it clashes with internal variables.

For instructions on setting up common custom events, including tracking impressions, field validation errors, page load time, and hover events, see our developer guides on custom event tracking.

Did you find what you were looking for?
Thumb up Thumb down