Skip to content
  • Home
  • Developers
  • API
  • Releases
  • Community
  • University
  • Status
  • Home
  • Developers
  • API
  • Releases
  • Community
  • University
  • Status
Home Getting Started Setting up Heap Step 1: Enrich Your Dataset Via APIs
Session Replay Getting Started Administration Data Management Definitions Charts Analysis Examples Heap Plays Integrations Heap Connect Data Privacy

Read in Order

  1. Step 0: Frame Your Business Questions
  2. Step 1: Enrich Your Dataset Via APIs
  3. Step 2: Integrate With Your Warehouse & 3rd Party Tools
  4. Step 3: Plan Your Data Governance Strategy
  5. Step 4: Establish Categories & Naming Conventions
  6. Step 5: Create & Manage Definitions
  7. Step 6: Learn Our Data Governance Tools
  8. Step 7: Complete Rollout
  9. Additional Resource: Getting Started Videos

Table of Contents

Was this article helpful?

Yes No

Thank you for your feedback!

Step 1: Enrich Your Dataset Via APIs

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 in order to enrich your autocaptured dataset.

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 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, such as an email or an internal user ID. 

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. User properties are stateless and a new value 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 (SPAs), which have a tendency 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:

  • Purchase data
  • Scroll depth
  • Video interactions
  • Hover events
  • Impressions
  • Form validation errors

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. You can learn more about choosing see 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 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.

APIUse Case
Server-side TrackSend purchase server-side data such as when the payment is processed, what was purchased, the shipping status, type, speed, cost, and other important values.
identifyTrack 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.
addEventPropertiesSend 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.
addUserPropertiesSend 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.

EventTriggerProperties



Add to Cart*

Clicked on Add to Cart Buttonproduct ID
price
quantity
category
currency
Completed OrderWhen the user completes a purchase from the cart and the transaction is successfully processedrevenue 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
RefundCompleted last step of refund funnelProduct ID
Category
refund amount
refund reason
Search Bar*Click enter on Search barSearch Term
Product Review PublishedUser submits review of productRating
Time of Purchase
category

*Autocaptured event with custom properties through snapshot 

**Events may be captured client or server-side

Custom Event Properties

We 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.

PropertyDescription
createdAtThe datetime of when the user signed up, aka when their account was created.
accountTypeThe type of account of the user, such as free or paid.
firstPurchaseDateThe date of the user’s very first purchase.
purchaseCountThe total amount of purchases they have made in their account history.
purchaseTotalValueThe total value of a single purchase, i.e. if the user is buying multiple items at once, how much that adds up to.
birthdateThe birthday of the user.
genderThe gender of the user.

Custom Account Properties

We recommend defining the following custom account properties to enrich your dataset. More information on properties can be found in Step 5 of this guide.

PropertyDescription
Account TierHow the account is tiered based on your organization’s CRM – additional related properties could include company size and/or account revenue
Account CategoryWhat category of goods the account sells
Order ScheduleHow frequently the account gets goods delivered
Total Lifetime OrdersHow many orders the account has made since becoming a customer
Deal Close DateThe date that the contract was signed
Account LocationRegion/city the account is based in

Custom User Properties

We recommend defining the following custom user properties to enrich your dataset. More information on events and properties can be found in Step 5 of this guide.

PropertyDescription
Last Purchase DateDate 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 DateWhen user signed up or bought first purchase 
GenderThe user’s gender identity

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.

APIUse Case
Server-side TrackTrack when and how much users pay, including automatic payments.
identifyTrack 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.
addEventPropertiesSend 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.
addUserPropertiesSend 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.

EventTriggerProperties
Clicked on EmailWhen 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 ClosedWhen the deal contract is signed.Contract Value, Contract Start, Contract Length, Sales Representative, Contract Type
Created AccountWhen a user successfully creates an account with a unique user ID.appType
authType
planType
Started MembershipWhen 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
PurchasedWhen the payment has been processed and funds have been transferred.transactionId
membershipId
revenue
subTotal
UpgradeWhen a customer’s upgrade is successfully processed.Current membership type, New membership type
Logged InWhen a user logs into their account.id
email
Logged OutWhen a user logs out of their account.id
email
Started TrialWhen a trial is
successfully activated.
trialStartDate
trialEndDate
Ended TrialWhen a user cancels their free trial and does not convert to a paid membership.trialStartDate
trialEndDate
Bill SentWhen the bill is sent to the customer.Due Date, Amount
Bill PaidWhen the payment has been processed for the bill.Due Date, Amount Paid
Renewed MembershipWhen 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
Cancel 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
Support Request*When the customer submits a support request (phone, email, not on the site).Reason/Category, Submitter Role
Contract TerminatedWhen the contract is terminated.Termination Date, Termination Reason
ErrorsAny 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 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.

PropertyDescription
accountTypeThe type of account of the user, such as free or paid.
lastAccountTypeThe most recent type of account or membership that the user had, i.e. tiers of a paid subscription service.
birthdateThe birthday of the user.
genderThe gender of the user.

Custom Account Properties

We recommend defining the following custom account properties to enrich your dataset. More information on properties can be found in Step 5 of this guide.

PropertyDescription
Account TierHow the account is tiered based on your organization’s CRM. Additional related properties could include company size and/or account revenue
Account VerticalWhat industry the account falls under
Account OwnerWhich sales representative owns the account
First Contact DateWhen the company was first contacted by a sales representative
Deal Close DateThe date that the contract was signed
Account LocationRegion/city the account is based in

Custom User Properties

We recommend defining the following custom user properties to enrich your dataset. More information on events and properties can be found in Step 5 of this guide.

PropertyDescription
AccountAccount ID sent through SFDC integration or via the addUserProperties API.
RoleThe role or job title of the user within their organization.
Sign Up DateThe date the user first signed up for the product or activated their account.
User PermissionsThe permissions the user has within the product. 
Last LoginDate of the user’s last login
Membership TypeType of customer’s membership or subscription
Membership StartedDate user’s membership started
Age groupUser’s age bracket
GenderThe user’s gender identity

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.

APIUse Case
Server-side TrackTrack when and how much users pay, including automatic payments.
identifyTrack 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.
addEventPropertiesSend 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.
addUserPropertiesSend 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.

EventTriggerProperties
Lead SubmissionWhen the user clicks on a lead generation for a financial product/serviceProduct TypeLead Name
Created AccountWhen a user successfully creates an account with a unique user ID.appTypeauthTypeplanTypeMembership TypeProduct
Application ProcessedWhen the user’s application is processedApplication TypeApplication Status
Started MembershipWhen a user successfully completes all steps to start or begin a purchase/product/policy or otherwise purchase a product/subscription/plan.membershipIditemIditemNameitemPriceitemTypeitemDiscount
Claim FiledWhen a user files a claimClaim Type, Claim Amount
PurchasedWhen the payment has been processed and funds have been transferred.transactionIdmembershipIdrevenuesubTotal
Logged InWhen a user logs into their account.idemail
Logged OutWhen a user logs out of their account.idemail
Started TrialWhen a trial issuccessfully activated.trialStartDatetrialEndDate
Ended TrialWhen a user cancels their free trial and does not convert to a paid membership.trialStartDatetrialEndDate
Renewed MembershipWhen a user successfully completes a renewal of an existing purchase/product/policy or otherwise purchases another term of their product/subscription/plan.membershipIditemIditemNameitemPriceitemTypeitemDiscount
Contact SupportWhen the customer submits a support request (phone, email, not on the site).Reason/Category

Custom Event Properties

We 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.

PropertyDescription
createdAtThe datetime of when the user signed up, aka when their account was created.
accountTypeThe type of account of the user, such as free or paid.
lastAccountTypeThe most recent type of account or membership that the user had, i.e. tiers of a paid subscription service.
firstPurchaseDateThe date of the user’s very first purchase.
birthdateThe birthdate of the user.
genderThe gender of the user.

Custom Account Properties

We recommend defining the following custom account properties to enrich your dataset. More information on properties can be found in Step 5 of this guide.

PropertyDescription
Account TierHow the account is tiered based on your organization’s CRM – additional related properties could include company size and/or account revenue
Account VerticalWhat industry the account falls under
Account OwnerWhich sales representative owns the account
Financing PurposeWhat the account uses the financing for
Deal Close DateThe date that the contract was signed
Account LocationRegion/city the account is based in

Custom User Properties

We recommend defining the following custom user properties to enrich your dataset. More information on events and properties can be found in Step 5 of this guide.

PropertyDescription
Last Login DateDate of most recent login 
Sign Up DateDate of first sign in 
Email Opt InWhat are the email preferences of the user 
Lifetime ValueThe total spend of the user 
Demographic DataAny demographic data the user put in when signing up for a financial service (birth date, income, etc.)

Was this article helpful?

Yes No

Thank you for your feedback!

Last updated March 2, 2023.

identifyidentify apisetting up heap
  • Blog
  • Partners
  • Legal
  • Security
  • Terms
  • About
  • Careers
  • Privacy
  • Contact Us

© 2023 Heap, Inc.