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 to enrich your autocaptured dataset.
In general, we’ve seen that the Heap autocaptured dataset covers 90% of use cases, whereas the last 10% can be brought in via the APIs and integration options listed below.
What is an API?
API stands for Application Programming Interface. Your developer should be familiar with this term and understand how they work.
Read on for an overview and use cases for each of these APIs and links for your developers to get started.
To understand your users’ 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 drastically limit your dataset. Identifying users allows you to retroactively tie together user behavior across platforms, browsers, and devices into a single user profile in Heap.
At this stage, you should have a conversation with your developer about the best choice of identifier for you. Some key considerations:
- It should be something stable about the user that won’t change, such as an internal user ID.
- It should be entirely unique for each user with no room for potential duplicates, such as an alphanumeric string.
- It should remain the same across all platforms that your users may be active on.
For these reasons, we highly recommend choosing a uniquely generated internal ID instead of something like email or phone number which may change over time or vary between platforms.
To generate and send this unique identifier to Heap, have your developer implement a heap.identify() call whenever the person is no longer anonymous. This API will assign a unique user ID to these anonymous users based on browser type, device type, and domain.
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.
What about the identity API?
Our identity API has a very similar name, but it does something different! Once you’re identifying your users, you can use the identity API to find a specific user’s identity.
Custom User Properties
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. paying customer).
Some questions you might want to consider when deciding which 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.
User properties are stateless, which means a new value will overwrite an existing value. To learn more, see Stateful vs. stateless properties.
Is your user data stored in a CRM? If so, we offer multiple integrations to enable you to automatically send in this user data.
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.
Account Properties
If you want to analyze your customer based on account-level information, you can do so by implementing our addAccountProperties API. This API is particularly beneficial for SaaS companies whose customers are companies themselves, and other businesses that 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 this 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 (SPAs), which tend to change state in a way that impacts the timing of the cookie being sent to the API. To learn more, see our article about how to use Heap with Single Page Applications.
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 send this manually 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. You can learn more about this in Client-side vs. Server-side Tracking.
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 label 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 still accessible. 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 sending in the following events and associated properties to enrich your dataset. Note that you’ll need to have the identify API set up to send these events into Heap.
| Event | Trigger | Properties |
|---|---|---|
Add to Cart* | Clicked on Add to Cart Button | product ID price quantity category currency |
| 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 Promo Code Used SKU Payment Method |
| 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 orderNumber |
| Refund | Completed last step of refund funnel | Product ID Category refund amount refund reason |
| Search Bar* | Click enter on Search bar | Search Term |
| Product Review Published | User submits review of product | Rating Time of Purchase category |
*Autocaptured event with custom properties through snapshot
**Events may be captured client or server-side
Custom Event Properties
We recommend sending in the following custom event properties to enrich your dataset. More information on events and properties can be found in Step 5 of the Getting Started 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 |
Custom Account Properties
We recommend sending in the following custom account properties to enrich your dataset. More information on properties can be found in Step 5 of the Getting Started guide.
| Property | Description |
|---|---|
| Account Tier | How the account is tiered based on your organization’s CRM – additional related properties could include company size and/or account revenue |
| Account Category | What category of goods the account sells |
| Order Schedule | How often the account gets goods delivered |
| Total Lifetime Orders | How many orders the account has made since becoming a customer |
| Deal Close Date | The date that the contract was signed |
| Account Location | Region/city the account is based in |
Custom User Properties
We recommend sending in the following custom user properties to enrich your dataset. More information on events and properties can be found in Step 5 of the Getting Started guide.
| Property | Description |
|---|---|
| Last Purchase Date | Date of the user’s last purchase |
| LTV (Lifetime Value) | # of purchases or total value of customer |
| Email Opt-in | Whether or not the user has email notifications subscribed or paused |
| Sign Up Date | When user signed up or bought first purchase |
| 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 sending in the following events and associated properties to enrich your dataset. Note that you’ll need to have the identify API set up to label these events.
| Event | Trigger | Properties |
|---|---|---|
| Clicked on Email | When a customer clicks on a link in a marketing email. | Email Subject, CTA |
| Demo Request* | When the customer requests a demo (phone, email, not on the site). | Product, Contact Method |
| Deal Closed | When the deal contract is signed. | Contract Value, Contract Start, Contract Length, Sales Representative, Contract Type |
| 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 |
| Upgrade | When a customer’s upgrade is successfully processed. | Current membership type, New membership type |
| 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 doesn’t convert to a paid membership. | trialStartDate trialEndDate |
| Bill Sent | When the bill is sent to the customer. | Due Date, Amount |
| Bill Paid | When the payment has been processed for the bill. | Due Date, Amount Paid |
| Renewed Membership | When a user 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 |
| Cancel Membership* | When a user 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 |
| Support Request* | When the customer submits a support request (phone, email, not on the site). | Reason/Category, Submitter Role |
| Contract Terminated | When the contract is terminated. | Termination Date, Termination Reason |
| Errors | Any errors that a customer encounters on the site. | Error Code, Error Text |
*events may be autocaptured if performed on the platform where Heap is installed.
Custom Event Properties
We recommend sending in the following custom event properties to enrich your dataset.
| 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. |
Custom Account Properties
We recommend sending the following custom account properties into Heap to enrich your dataset.
| Property | Description |
|---|---|
| Account Tier | How the account is tiered based on your organization’s CRM. Additional related properties could include company size and/or account revenue. |
| Account Vertical | What industry the account falls under. |
| Account Owner | Which sales representative owns the account. |
| First Contact Date | When the company was first contacted by a sales representative. |
| Deal Close Date | The date that the contract was signed. |
| Account Location | Region/city the account is based in. |
Custom User Properties
We recommend sending in the following custom user properties to enrich your dataset. More information on events and properties can be found in Step 5 of the Getting Started guide.
| Property | Description |
|---|---|
| Account | Account ID sent through SFDC integration or via the addUserProperties API. |
| Role | The role or job title of the user within their organization. |
| Sign Up Date | The date the user first signed up for the product or activated their account. |
| User Permissions | The permissions the user has within the product. |
| Last Login | Date of the user’s last login. |
| Membership Type | Type of customer’s membership or subscription. |
| Membership Started | Date user’s membership started. |
| Age group | User’s age bracket. |
| Gender | The user’s gender. |
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. Note that you’ll need to have the identify API set up to label these events.
| Event | Trigger | Properties |
|---|---|---|
| Lead Submission | When the user clicks on a lead generation for a financial product/service | Product TypeLead Name |
| Created Account | When a user successfully creates an account with a unique user ID. | appTypeauthTypeplanTypeMembership TypeProduct |
| Application Processed | When the user’s application is processed | Application TypeApplication Status |
| Started Membership | When a user completes all steps to start or begin a purchase/product/policy or otherwise purchase a product/subscription/plan. | membershipIditemIditemNameitemPriceitemTypeitemDiscount |
| Claim Filed | When a user files a claim | Claim Type, Claim Amount |
| Purchased | When the payment has been processed and funds have been transferred. | transactionIdmembershipIdrevenuesubTotal |
| Logged In | When a user logs into their account. | idemail |
| Logged Out | When a user logs out of their account. | idemail |
| Started Trial | When a trial issuccessfully activated. | trialStartDatetrialEndDate |
| Ended Trial | When a user cancels their free trial and does not convert to a paid membership. | trialStartDatetrialEndDate |
| Renewed Membership | When a user completes a renewal of an existing purchase/product/policy or otherwise purchases another term of their product/subscription/plan. | membershipIditemIditemNameitemPriceitemTypeitemDiscount |
| Contact Support | When the customer submits a support request (phone, email, not on the site). | Reason/Category |
Custom Event Properties
We recommend sending the following custom event properties into Heap to enrich your dataset.
| 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 |
Custom Account Properties
We recommend sending the following custom account properties into Heap to enrich your dataset.
| Property | Description |
|---|---|
| Account Tier | How the account is tiered based on your organization’s CRM – additional related properties could include company size and/or account revenue |
| Account Vertical | What industry the account falls under |
| Account Owner | Which sales representative owns the account |
| Financing Purpose | What the account uses the financing for |
| Deal Close Date | The date that the contract was signed |
| Account Location | Region/city the account is based in |
Custom User Properties
We recommend sending the following custom account properties into Heap to enrich your dataset.
| Property | Description |
|---|---|
| Last Login Date | Date of most recent login |
| Sign Up Date | Date of first sign in |
| Email Opt In | What are the email preferences of the user |
| Lifetime Value | The total spend of the user |
| Demographic Data | Any demographic data the user put in when signing up for a financial service (birth date, income, etc.) |