For many customers, the base Heap implementation is enough to quickly get up and running with a comprehensive set of autocaptured data.
Depending on your business needs, you may wish to have your developer implement our APIs and enrich your autocaptured dataset by sending in user identities and data unique to your organization. Read on for an overview and use cases for each of these APIs and links for your developers to get started.
To understand your user’s journey across web and mobile devices, it is important that identity is set up for both web and mobile, and is called the same way.
API Types
User Identity
Until someone is identified in Heap, they are an anonymous user, which can really limit your dataset. Heap assigns a user ID to these anonymous users based on browser type, device type, and domain.
Identifying users via the Identify API allows you to retroactively tie together user behavior across platforms, browsers, and devices into a single user profile in Heap. An identity can be any piece of user information that is uniquely identifiable. It should be something stable about the user that is not likely to change.
To send this data to Heap, have your developer implement a heap.identify() call whenever the person is no longer anonymous. A best practice is to call this API as early as possible in the user journey, and at all key points in the user journey, such as when a user signs up, logs in, or makes a purchase.
Our comprehensive developer guide on Using Identify provides examples and best practices for making the most of this API to manage identity in Heap. Once this information is in Heap, it can be used in your analysis to understand customer behaviors across multiple devices, platforms, and domains.
Custom User Properties
Our Looker Actions integration allows you to quickly import user and account property data into Heap. See the Looker Actions Integration guide to learn more.
In addition to using our identify API to manage identity in Heap, you can also use our addUserProperties API to send additional custom user-level data. Custom user properties can be thought of as any data about a person, such as a name or a property that describes their current state (ex. as a current payment plan).
Some questions you might want to consider when considering what user-level properties to track:
- How do you group or cohort users when you describe them?
- Do you assign roles or user types to your users?
- Do you segment by demographic data?
- Do some of your users belong to an organization, company, or group?
You can send this information to Heap at any point in the user journey where the property values are available. You’ll often send this data at the same time that you identify an individual. Heap will create a new property if it doesn’t exist and will overwrite the previous value if one already exists.
Is your user data stored in a CRM? If so, we offer multiple integrations to enable you to automatically send in this user data.
Account Properties
If you want to analyze your customer based by account, you can do so by implementing our addAccountProperties API. An account can be defined as a collection of users. This is particularly beneficial for SaaS companies whose customers are companies themselves, and other businesses who serve organizations in addition to individuals.
To get started with account analysis, you’ll need to configure the Account ID setting on the Features page of your account. Instructions to complete this step and all of the other steps to pull in and analyze account data are available in Account Health Analysis.
Our Looker Actions integration allows you to quickly import user and account property data into Heap. See the Looker Actions Integration guide to learn more.
Custom Event Properties
Some information about a user isn’t static and changes often. For instance, you may want to analyze the state of a user based on certain types of behavior, like whether they were logged in or not. Similarly, if your product follows a freemium model, you may want to understand the difference between a user’s free behavior and paid behavior.
You can leverage our addEventProperties API to send stateful information to Heap. When you set a property value via this API, we’ll store this information in a cookie on the client side, and attach this property value to every event going forward until it’s updated or cleared. For this reason, this API is only available on the client-side.
As a best practice, we recommend calling clearEventProperties before addEventProperties on every page. This removes all previous event properties from the cookie, which ensures the properties getting added by the next addEventProperties call are always relevant.
Note that the addEventProperties API may not work well with Single Page Applications, which have a tendency to change state in a way that impacts the timing of the cookie being sent to the API. For questions about this, reach out to support@heap.io.
Custom Events
Heap captures most web and mobile behavior automatically. You can analyze any type of data that can be modeled as a person (user) who does something (events).
On the web, there are several notable events that Heap won’t capture out-of-the-box, such as:
If you want to capture any of these events, or if you have any mission-critical data, such as a successful sign-up or a completed order transaction, you’ll want to manually send this to Heap via our track API. Similarly, if you have events that need to match your backend, you’ll want to use the server-side Track API.
When sending custom event data to Heap, we recommend sending event data in a generic way and adding any specifics by attaching the property. For instance, if you’re tracking video data, we recommend sending a ‘Video Interaction’ event with custom properties that describe what video is involved and the type of interaction (play, pause, etc.). Once in Heap, you can define specific events based on this data.
What types of events can I custom track?
- Events that are not autocaptured. Example: pop-ups that haven’t been explicitly triggered by a pageview or some type of user interaction.
- Events with a lot of custom metadata. For example, for a ‘Purchase’ event, you may want to also bring in ‘Subtotal’, ‘Quantity’, ‘Color’, ‘Shipping Type’ as properties of that event. You can also use Snapshots to capture this data; however, using the Track API makes it less susceptible to changes on your website.
- Events that are mission-critical. This is typically any key conversion event, e.g. ‘Membership Started’, where you need the data in Heap to match your backend exactly. In this case, you should use the server-side API.
- Events that happen offline or somewhere Heap is not installed but is stored somewhere you have access to. In this case, you should use the server-side API.
Heap does not support sessionization of client-side and server-side data in the UI.
Data Privacy APIs
As referenced in our Pre-Install guide, If you need to meet GDPR, HIPAA, or COPPA compliancy standards with your implementation of Heap, we recommend sharing our FAQs on Data Privacy with your developer, which reference configurations that can be set up to block the collection of certain types of data under specific circumstances.