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.