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 is not triggered by a pageview, click, change on, or submit event (eg, modal 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

• Impressions
• A/B Test Events
• Video Plays

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 3rd 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 are not 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 3rd party tools that aren’t integrated with Heap