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. Here are some examples of events you may want to define based on your business needs:

• eCommerce: View Product, Add Product to Cart, Applied Promo Code, Completed Order
• SaaS: Sign Up, Login, Activate Subscription, any actions you use to define acquisition, conversion, and retention

Recommended events based on your role within your organization include:

• Product Management: Completed Onboarding, any actions you use to define feature engagement
• Marketing: View Home Page, Click Subscribe to Marketing Emails, Apply Promo Code

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.

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.