Overview
Heap automatically captures a wealth of client-side interactions out-of-the-box, including clicks, pageviews, form submissions, and change events. For a review of everything Heap autocaptures, see Autocaptured Data.
To track additional user activities, our client and server-side track APIs can be used to bring in this data as custom events.
This guide covers types of custom events you may wish to capture via Heap’s client and server-side APIs and recommended use cases for doing so.
Common Use Cases for Custom Events
Typical use cases for tracking custom events via API include:
- The event isn't triggered by a pageview, click, change on, or submit event (eg, pop-up displays)
- Where you need an exact number of events counted, and any volume of event loss from ad blockers is unacceptable
- Server-side events related to users but not to user actions (eg, application status update)
- Events where you need to attach custom properties that live in your internal database only, ex. a purchase event with properties such as total, subtotal, shipping, SKU, coupon code, and more
Capturing Custom Events
Now that you’re familiar with these use cases, here are some important considerations when deciding whether to capture these custom events client-side or server-side.
Client-Side
Benefits
- Client-side events paired with Heap’s autocapture functionality can be enriched with these autocaptured properties
- You can conduct session analysis on client-side events, such as analyzing custom A/B test events after a user has interacted with your test during a session
- Client-side data appears in Heap almost instantly, allowing you to quickly spot and act on results
Drawbacks
- Because of ad blockers and cookie restrictions, this data may not be as accurate as server-side data
Popular client-side custom events
Server-Side
Benefits
- Server-side events that are more precise since there’s no interference from ad blockers or cookie restrictions, ex. for mission-critical events that count towards your KPIs
- You can track data from non-client side sources, including data from third party tools like Shopify, Intercom, Salesforce, and more
Drawbacks
- May require more engineering resources to implement
- You can only send server-side events to identified users
- They aren't sessionized with client-side events
Popular server-side custom events
- Purchase data - this guide also covers how to track this data client-side if you prefer
- Important events from third party tools that aren’t integrated with Heap
Viewing custom events
To see custom events, navigate to Data > Labeled events and select Custom under the Source filter.
If you just created your event, there is an expected latency, which is typically less than 1 hour, between when you'll first see the event appear in Live data feed and when you will see it on your Labeled events page and in charts. After this expected latency period, the event will be available for use in analysis and on the Labeled events page.