track

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())
)

Arguments

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

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.

Leverage properties with custom events

We recommend naming custom events broadly and using properties to distinguish between different types of events. This makes analysis in Heap easier, and additional events can be labeled in Heap to create subsets of any broader events.

✅ For example, if you want to send error events into Heap, we recommend:

heap.track('Error', {message: 'Authentication Failed'});

heap.track('Error', {message: 'Field Validation'});

❌ Instead of:

heap.track('Error: Authentication Failed');

heap.track('Error: Field Validation');

🚧
heap.track calls cannot be named click, change,pageview, submit because those names clash 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?