Skip to content
  • Home
  • Developers
  • API
  • Releases
  • Community
  • University
  • Status
  • Home
  • Developers
  • API
  • Releases
  • Community
  • University
  • Status
Home Getting Started Setting up Heap Step 5: Create & Manage Definitions
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 5: Create & Manage Definitions

With your data governance and organizational strategy decided, you’re ready to define events, properties, and segments for your team in Heap.

Wait, what are those?

Events

An event is any action associated with a user. Examples of events you can define in Heap include:

  • Click Sign Up
  • View Product Page
  • Complete Checkout
  • and many more!

Thanks to Heap’s autocapture, no matter how you define your event, all of the correct data will be there. If you change an event definition in any way, all the data is still readily accessible.

Your Heap account starts off as an empty slate with only two events defined: Session and Pageview (only visible in the analysis modules).

We recommend defining a small set of about 12-20 core events based on your user journey to help your team get started with analysis.

For a deep dive on defining events via the Event Visualizer and CSS, check out our Creating Event Definitions course in Heap University.

To quickly get started with events, we recommend visiting the Explore events page to define events based on common user actions.

Industry Recommendations

Click the industry tabs below to see examples of events you may want to define based on your business needs.

EventDescriptionCommon Definition Structure
Submit – SearchWhen a user submits a string in a product search barSubmit on .search-form
View – Product Category PageWhen a user views a product category pageView page *
Add filters for all product category paths
View – Product PageWhen a user views a product landing pageView page * 
Add filters for all product page paths
View – Product ReviewsWhen a user views a product review pageView page *
Add filters for all product review page paths
Click – Add to CartWhen a user clicks ‘add to cart’Click on .add-to-cart-button
View – CartWhen a user views the checkout pageView page /cart
Click – Remove From CartWhen a user clicks ‘remove item from cart’Click on .remove-from-cart-button
Click – Apply Promo CodeWhen a user successfully enters a promo code and the promo code is successfully applied to the cartClick on .apply-promo-code-button
Click – Checkout (Start)When a user clicks ‘start checkout’Click on .checkout-button
Click – Place OrderWhen a user clicks the button to place/submit their order (this does NOT include payment confirmation of the order)Click on .place-order
View – Marketing PageWhen a user views a marketing page, like a ‘why [your product]’ pageView page /why-heap/*
View – Blog PostWhen a user views a blog postView page /blog/*
View – Landing PageWhen a user views a landing pageView page /
Optional: filter by domain (ex. ‘Domain equals learn.heap.io’)
Click – Call to ActionWhen a user clicks a marketing CTAClick on .free-trial-signup-button
Submit – Product ScoreWhen a user submits a product score reviewSubmit on .product-score
Completed Order [Custom event via API]When a user completes ‘purchase from cart’ and the payment processor returns a successSource set to ‘custom’ with the custom event defined via a Heap API selected, ex. ‘Complete Purchase’
Account Created [Custom event via API]When a user successfully signs up for an account and gets a unique userIDSource set to ‘custom’ with the custom event defined via a Heap API selected, ex. ‘Account Created’

EventDescriptionCommon Definition Structure
View – Pricing PageWhen a user views one of your pricing pagesView page /pricing/*
View – Blog PostWhen a user views a post on your blogView page/blog/*
View – FAQ PageWhen a user views one of your FAQ pagesView page /faqs/*
OR
View page with a filter for your support portal’s subdomain (ex. support.company.com)
Click – Request DemoA click on the ‘request demo’ buttonClick on .request-demo-button
Click – Start Free TrialWhen a user clicks on the ‘start free trial’ buttonClick on .start-free-trial
Submit – Support RequestWhen a user clicks on the support buttonClick on .get-support-button
Submit – Create AccountWhen a user successfully created an account and received a unique user IDSubmit on .sign-up
Submit – Membership SignupWhen a user successfully completes all steps to start or begin a membership or otherwise purchases a membershipSubmit on .membership-sign-up
Submit – Complete PurchaseWhen the payment has been processed and funds have been transferredSubmit on .complete-purchase
Click – Log InWhen a user logs into their accountClick on .log-in-button
Click – Log OutWhen a user logs out of their accountClick on .log-out-button
Click – Start TrialWhen a trial is successfully activatedClick on .start-trial-button
Click – Cancel TrialWhen a user cancels their free trial and does not convert to a paid membershipClick on .cancel-trial-button
Click – Renew MembershipWhen a user successfully completes a renewal of an existing membership or otherwise purchases another term of their membershipClick on .renew-membership-button

EventDescriptionCommon Definition Structure
Submit – Create AccountWhen a user successfully created an account and received a unique user IDSubmit on .sign-up
Submit – Membership SignupWhen a user successfully completes all steps to start or begin a membership or otherwise purchases a membershipSubmit on .membership-sign-up
Click – Apply Promo CodeWhen a user enters a coupon codeClick on .apply-promo-button
Click – Started Free TrialWhen a user starts a trial/quote/offer processClick on .start-free-trial-button
Click – Log InWhen a user logs inClick on .log-in-button
Click – Log OutWhen a user logs outClick on .log-out-button
View – Marketing PageViews of marketing pages, like a ‘why [your product]’ pageView page /why-heap/*
View – Pricing PageWhen a user views a pricing pageView page /pricing/*
Click – Call to ActionWhen a user clicks on a primary call to actionClick on .free-trial-signup-button
View – Landing PageViews of dedicated landing pagesView page /
Filter by domain (ex. ‘Domain equals learn.heap.io’)
Submit – Subscribe to NewsletterWhen a user signs up for your newsletterSubmit on .newsletter-sign-up
Click – Install AppWhen a user clicks the ‘install app’ CTA from your marketing siteClick on .install
View – OnboardingWhen a user begins the onboarding/welcome flow in your appView page /welcome/*
Click – Complete OnboardingWhen a user finishes all of the onboarding steps in your appClick on .done-onboarding
Installed App /Initial Open App [Custom event via API]When a user completes the installation process for your app and/or opens it for the first timeSource set to ‘custom’ with the custom event defined via a Heap API selected, ex. ‘App Install’
Opened App [Custom event via API]When a user opens your appSource set to ‘custom’ with the custom event defined via a Heap API selected, ex. ‘App Open’

Take a moment to jot down what core events would work best for your organization as part of your rollout plan. For full steps to create and manage events in Heap, see our Events guide.

Explore pageview events

Heap automatically recommends the top pages in your website or app to define as events. Defining these pageviews lets you dive in and start analyzing behavior on these pages.

To get started with suggested pageviews, open up the Event Visualizer and click View Suggestions.

Have omnichannel events across web and mobile? You can create combo events to easily easy track these!

Properties

Properties are bits of metadata that are captured during user interactions with your app. Heap already captures a wide variety of properties at each level of our data model, listed out in Autocaptured Data. You can also bring in custom properties via the APIs mentioned earlier in this guide.

In addition to all of these, you can define new properties, known as defined properties, based on existing property values from within Heap. This allows you to create custom groupings of data points in your account, which can be useful for doing things like:

  • Aggregating properties with similar functions into one universal property, ex. a ‘marketing’ property that includes all of your marketing efforts (paid search, email, adwords, etc) into one
  • Grouping related page or screen types, such as a ‘blog’ umbrella property for all of your blog posts
  • Merging or re-naming existing autocaptured properties to make them more intuitive for your team
  • Defining custom marketing channels based on the types of user journeys you are looking to better understand

Depending on your needs, you may not even need to define any new properties at this stage. Familiarizing yourself with what they are and how you can rename and categorize them is helpful for establishing a dataset that’s easy for your team to understand.

Complete steps on how to define, update and hide properties are available in our Properties guide. For a refresher on the data hierarchy in Heap and how different types of properties fit into that hierarchy, see Heap’s Data Model.

Snapshots

Snapshots are a Heap feature that allows you to attach custom properties to events without having your engineers use an API. For example, you can attach the price of an item as a property of an “Add to Cart” event, or the value of a field as a property of a “Form Submission” event.

You can create snapshots from the Event Visualizer or directly in the Event Definition tab within Heap. For more details and examples, see Snapshots. Note that unlike other data features, snapshots cannot capture data retroactively, so you’ll want to set up snapshots as early in the process as possible.

Segments

Defining segments allows you to group your users into – you guessed it – segments. These can be any subset of your users defined by any condition, such as: Frequent Buyers, Canadian Visitors, New Signups in January, and more. If you are going to be running analysis on certain user groups consistently, segments can save you a lot of time.

Your segments can get as granular as you need them to be. Want to make a segment of first-time buyers? Go for it! Want to make a segment of first-time buyers who live in Canada and have seen your blog? You can do that too! Want to make a segment of first-time buyers who live in Canada, have seen your blog, spent more than $100 on their purchase, and have used the chatbox on your website? Well, you can do that too.

Similar to properties, you may not need to define segments this early on, though it’s helpful to know about them for when you dive into our analysis features. More information on how segments work, and instructions on how to create and manage them, can be found in our Segments guide.

QA Definitions

Each time a new definition is saved to your shared space, it should be properly QAed. Some common methods for QAing events include: 

Using the Analysis Preview within the event definition page

  • Group by the ‘path’ property to make sure it’s firing everywhere 
  • Group by other properties to verify the values make sense e.g. ‘domain’, ‘href’ any snapshots defined on it, etc. 
  • Group by target text and check that the results make sense based on the structure of the page or screen
  • Note the number of times this event has occurred in the past week – does this number make sense in comparison to other data?

Using the Live View tool 

  • Filter for yourself (typically using your IP address or user ID) and interact with your product to see if the events you’ve defined are firing as expected 

You also have the ability to add notes to new definitions from the definition details page. A recommended best practice when creating new definitions is to always add a note that indicates what is being captured (if it’s not already obvious from the category or name) and record any nuances.

Answer the following questions to come up with your recommended QA strategy for your team:

  • Are there any other steps your team members should take to QA their definitions that are specific to your organization?
  • Is there other information that should be included in the notes area that would be specific to your organization?
  • Who in your organization should own the process of QAing events?

Reports & Dashboards

Once you’ve created and QAed your events, segments, and properties, your team will be set up to use them in analysis and save the results into reports. Reports are saved queries, which you can use to consistently re-run and monitor your analytics. Dashboards allow you to group related reports together to quickly review the latest results from a birds-eye view.

In addition to defining core events, we recommend establishing baseline metrics you use to define success. Baseline metrics are the activities, or events, that indicate some sort of value that your team wants to monitor. This will provide you with some guidance on what analysis to run first in your Heap account.

In Heap, our Suggested Reports are phrased as a question, such as ‘Which countries are my visitors from?’ As a guide for establishing your baseline metrics, take a moment to brainstorm a list of questions you want to answer about your user journey. These will help you establish your baseline metrics.

We recommend saving a few reports which track these baseline metrics and at least one Dashboard to give your team a starting point when they join Heap. See Dashboards & Reports for steps to set these up. 

Was this article helpful?

Yes No

Thank you for your feedback!

Last updated August 16, 2022.

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

© 2023 Heap, Inc.