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 compliance 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.
Industry Recommendations
Click the industry tabs below to see recommendations for your business type.
APIs
As a baseline, we recommend configuring the following APIs to enrich your dataset. See our API Reference page for a complete list of our APIs along with use cases.
| API | Use Case |
|---|---|
| Server-side Track | Send purchase server-side data such as when the payment is processed, what was purchased, the shipping status, type, speed, cost, and other important values. |
| identify | Track purchase patterns across platforms and browsers to get a holistic picture of engagement and purchases. You can use this info to create segments of users by activity, like tracking power purchasers. |
| addEventProperties | Send additional info about a user attached to an event, such as if the user was logged in when clicking a promo, what their payment plan type was when they made a purchase, and more. |
| addUserProperties | Send additional info about a user, such as profile info (name, age range, profession). |
Custom Events
We recommend creating the following events and associated properties to enrich your dataset. More information on events and properties can be found in Step 5 of this guide. Note that you’ll need to have the identify API set up to define these events.
| Event | Trigger | Properties |
|---|---|---|
| Completed Order | When the user completes a purchase from the cart and the transaction is successfully processed | revenue order Total order ItemCount orderShipping orderTax orderDiscount |
| Purchased Product | Every line item triggers a unique event (so if 5 items are purchased on an order, then 5 events are generated) | itemId itemName itemPrice itemSku itemCategory |
Custom Event Properties
We also recommend defining the following custom event properties to enrich your dataset. More information on events and properties can be found in Step 5 of this guide.
| Property | Description |
|---|---|
| createdAt | The datetime of when the user signed up, aka when their account was created. |
| accountType | The type of account of the user, such as free or paid. |
| firstPurchaseDate | The date of the user’s very first purchase. |
| purchaseCount | The total amount of purchases they have made in their account history. |
| purchaseTotalValue | The total value of a single purchase, i.e. if the user is buying multiple items at once, how much that adds up to. |
| birthdate | The birthday of the user. |
| gender | The gender of the user. |
APIs
As a baseline, we recommend configuring the following APIs to enrich your dataset. See our API Reference page for a complete list of our APIs along with use cases.
| API | Use Case |
|---|---|
| Server-side Track | Track when and how much users pay, including automatic payments. |
| identify | Track purchase patterns across platforms and browsers to get a holistic picture of product usage. You can use this info to create segments of users by activity, like tracking subscribers by logins. |
| addEventProperties | Send additional info about a user attached to an event, such as their region when activating a key feature, their age range when upgrading to a subscription, and more. |
| addUserProperties | Send additional info about a user, such as profile info (name, age range, profession). |
Custom Events
We recommend creating the following events and associated properties to enrich your dataset. More information on events and properties can be found in Step 5 of this guide. Note that you’ll need to have the identify API set up to define these events.
| Event | Trigger | Properties |
|---|---|---|
| Created Account | When a user successfully creates an account with a unique user ID. | appType authType planType |
| Started Membership | When a user successfully completes all steps to start or begin a purchase/product/policy or otherwise purchase a product/subscription/plan. | membershipId itemId itemName itemPrice itemType itemDiscount |
| Purchased | When the payment has been processed and funds have been transferred. | transactionId membershipId revenue subTotal |
| Logged In | When a user logs into their account. | id |
| Logged Out | When a user logs out of their account. | id |
| Started Trial | When a trial is successfully activated. | trialStartDate trialEndDate |
| Ended Trial | When a user cancels their free trial and does not convert to a paid membership. | trialStartDate trialEndDate |
| Renewed Membership | When a user successfully completes a renewal of an existing purchase/product/policy or otherwise purchases another term of their product/subscription/plan. | membershipId itemId itemName itemPrice itemType itemDiscount |
Custom Event Properties
We also recommend defining the following custom event properties to enrich your dataset. More information on events and properties can be found in Step 5 of this guide.
| Property | Description |
|---|---|
| accountType | The type of account of the user, such as free or paid. |
| lastAccountType | The most recent type of account or membership that the user had, i.e. tiers of a paid subscription service. |
| birthdate | The birthday of the user. |
| gender | The gender of the user. |
APIs
As a baseline, we recommend configuring the following APIs to enrich your dataset. See our API Reference page for a complete list of our APIs along with use cases.
| API | Use Case |
|---|---|
| Server-side Track | Track when and how much users pay, including automatic payments. |
| identify | Track purchase patterns across platforms and browsers to get a holistic picture of engagement. You can use this info to create segments of users by activity, like tracking engagement by age group. |
| addEventProperties | Send additional info about a user attached to an event, such as what type of account they chose when signing up, what age range they were in when completing a key conversion step, and more. |
| addUserProperties | Send additional info about a user, such as profile info (name, age range, profession). |
Custom Events
We recommend creating the following events and associated properties to enrich your dataset. More information on events and properties can be found in Step 5 of this guide. Note that you’ll need to have the identify API set up to define these events.
| Event | Trigger | Properties |
|---|---|---|
| Created Account | When a user successfully creates an account with a unique user ID. | appType authType planType |
| Started Membership | When a user successfully completes all steps to start or begin a purchase/product/policy or otherwise purchase a product/subscription/plan. | membershipId itemId itemName itemPrice itemType itemDiscount |
| Purchased | When the payment has been processed and funds have been transferred. | transactionId membershipId revenue subTotal |
| Logged In | When a user logs into their account. | id |
| Logged Out | When a user logs out of their account. | id |
| Started Trial | When a trial is successfully activated. | trialStartDate trialEndDate |
| Ended Trial | When a user cancels their free trial and does not convert to a paid membership. | trialStartDate trialEndDate |
| Renewed Membership | When a user successfully completes a renewal of an existing purchase/product/policy or otherwise purchases another term of their product/subscription/plan. | membershipId itemId itemName itemPrice itemType itemDiscount |
Custom Event Properties
We also recommend defining the following custom event properties to enrich your dataset. More information on events and properties can be found in Step 5 of this guide.
| Property | Description |
|---|---|
| createdAt | The datetime of when the user signed up, aka when their account was created. |
| accountType | The type of account of the user, such as free or paid. |
| lastAccountType | The most recent type of account or membership that the user had, i.e. tiers of a paid subscription service. |
| firstPurchaseDate | The date of the user’s very first purchase. |
| birthdate | The birthdate of the user. |
| gender | The gender of the user. |