Manually track events
In addition to Heap’s powerful autocapture capabilities, you can also add custom event tracking into your applications to enhance your dataset.
Tracking Custom Events
Custom events can be tracked using the client-side track
API, available in all Heap client SDKs.
Heap.track("custom_event_name")
Heap.track("custom_event_name");
Heap.shared.track("custom_event_name")
[Heap.sharedInstance track:@"custom_event_name"];
Heap.Track("custom_event_name")
heap.track("custom_event_name")
It doesn't matter what you call your event, there are ways in Heap to cross-track events regardless of name. See our guide on combo events to learn more.
Adding Properties to Custom Events
Custom events can be enhanced with a set of properties that will correspond to the tracked event when passed into the track
API call. On most platforms, custom event property values can be of any primitive value or string type. Event property keys are always string types.
Heap.track(
"custom_event_with_properties",
mapOf(
"property1" to "sample value",
"property2" to 10,
"property3" to false
)
)
HashMap<String, Object> properties = new HashMap<>();
properties.put("property1", "sample value");
properties.put("property2", 10);
properties.put("property3", false);
Heap.track(
"custom_event_with_properties",
properties
);
Heap.shared.track("custom_event_with_properties", properties: [
"property1": "sample value",
"property2": 10,
"property3": false,
])
[Heap.sharedInstance track:@"custom_event_with_properties" properties: @{
@"property1": @"sample value",
@"property2": @10,
@"property3": @NO
}];
Heap.Track(
"custom_event_with_properties",
new Dictionary<string, string>
{
{ "property1", "sample value" },
{ "property2", "10" },
{ "property3", "false" },
}
);
heap.track(
"custom_event_with_properties",
{
"property1": "sample value",
"property2": 10,
"property3": false,
}
)
Adding Properties to All Events
In some cases, you might want to add a property, or a collection of properties, to all events tracked by Heap. Adding a global event property can be accomplished using Heap’s addEventProperties
API.
Heap.addEventProperties(
mapOf(
"property1" to "sample value",
"property2" to 10,
"property3" to false
)
)
HashMap<String, Object> properties = new HashMap<>();
properties.put("property1", "sample value");
properties.put("property2", 10);
properties.put("property3", false);
Heap.addEventProperties(properties);
Heap.shared.addEventProperties([
"property1": "sample value",
"property2": 10,
"property3": false,
])
[Heap.sharedInstance addEventProperties:@{
@"property1": @"sample value",
@"property2": @10,
@"property3": @NO
}];
Heap.addEventProperties(
new Dictionary<string, string>
{
{ "property1", "sample value" },
{ "property2", "10" },
{ "property3", "false" },
}
);
heap.addEventProperties(
{
"property1": "sample value",
"property2": 10,
"property3": false,
}
)
Properties that are added using the addEventProperties
API will be attached to all events tracked by Heap, including any events that are automatically tracked by a Heap autocapture SDK.
Once a property is no longer needed in the global collection, Heap’s removeEventProperty
API can be used to remove properties one at a time.
Heap.removeEventProperty("property1")
Heap.removeEventProperty("property1");
Heap.shared.removeEventProperty("property1")
[Heap.sharedInstance removeEventProperty:@"property1"];
Heap.RemoveEventProperty("property1");
heap.removeEventProperty("property1")
What Next?
Using Heap with one of our native mobile SDKs? Check out how to add complex object data to events on Android or iOS.
Updated 4 months ago