What is a Property?

Properties are bits of metadata that are captured during user interactions with your app. Heap automatically captures a wide variety of properties for you, as listed in Autocaptured Data. You can also bring in additional custom properties via Heap’s APIs and label new properties. Heap gives you complete organizational control over the extensive set of property data available to you.

There are many different types of properties in Heap, as described in the sections below.

Types of Properties

The following properties are named based on whether they are automatically captured by Heap, brought in via an implementation of one of our APIs, labeled within the app, or brought in via an integration.

• Autocaptured properties: Once Heap is installed on your website or app, these properties are automatically captured. A full list can be reviewed in Autocaptured Data.
• Custom properties: These are brought in via Heap’s APIs or snapshots, and allow you to enrich your autocaptured data. For example, you can use the addUserProperties API to assign custom properties to any of your users from your servers, such as account-level information from your database, or demographic info.
• Labeled properties: You can label your own properties to create a new schema on top of existing properties in your account. This can be useful for things like grouping app screens or blog pages into one property. Details about these properties and steps to label them are available further on in this guide.
• Enriched properties: If you’re using one of our integrations, this property type refers to the information we are pulling from those sources.

The following properties are named based on how where the property fits in Heap’s user > session > event hierarchy data model:

• User properties: Metadata that we know about a user, such as where were they the first time they visited your homepage, or what city were they in during their most recent session. Other than “initial” properties, these can change.
• Session properties: These roll up into the user and the events taken during a session. Unlike event and user properties, you can’t create your own session properties.
• Event properties: Metadata about the actions users are taking, such as the target text on the button they clicked, or what browser they used.

These types of properties are specifically for refining your charts when conducting analysis:

• Behavioral properties: Behavioral properties can be used to filter your reports by users who have or haven’t done something for more granularity. Examples include ‘users who have done a count of’, ‘users who have done’.
• Active usage properties: Digging deeper into the concept of user behavior, active usage properties allow you to better understand engagement with your features. Filter your charts by users who have started or stopped doing an event, who are repeat users or are users who are re-engaging with the event.

What is the difference between client-side and server-side properties? Client-side properties are all of the actions we are capturing on the app or site you’ve installed Heap onto. Server-side properties are what you are capturing on your backend. You won’t see these names in the app, though the distinction is important to understand when using properties.

Additionally, properties in Heap are grouped by whether they are personal or shared. Personal properties only appear on your account, whereas shared properties are available for all of your team members to use in analysis. For more information on how personal and shared data is managed, see Shared vs. Personal Spaces.

Properties List

To review the list of properties available in your Heap account, navigate to Data > Properties. Your properties are organized as follows:

1. Personal Labeled User Properties
2. Personal Labeled Event Properties
3. Labeled User Properties
4. Labeled Event Properties
5. User Properties (from Web, iOS, Android and Server)
6. Event Properties (from Web, iOS, Android and Server)
7. User Properties from Sources
8. Event Properties from Sources
9. Hidden User Properties
10. Hidden Event Properties

The Event Properties section in your account may appear similar to the image below, where you can see a combination of properties being sent from Heap client tracking libraries. This includes custom properties sent via the API such as Author, autocaptured properties such as Browser and City, and custom snapshot properties, such as Dashboard Count.

Property Details View

After selecting a property from the properties list, you’ll be presented with a view that gives you all of the context available for that property. Within this view, you can gain context on what the property is by reading the property notes and seeing a preview of the common values for this property in your dataset. You can also see the current visibility state of the property (personal or shared) and its data type in Heap.

Property Data Types

Heap currently supports the following data types for properties:

• Text (string)
• ID (unique value)
• Number (numeric)

By default, Heap will automatically try to assess the property type when the data type is set to Auto-Detect. However, in certain cases, you may want to specify how Heap should treat the property in analysis by changing the data type. For example, your identity may be a number (manually specified as ID), or a numerical property may contain a ‘$’ (manually specified as Number). This allows Heap to perform mathematical aggregations on dollar amounts or prevents Heap from bucketing unique identities when your internal ID is a number.

Autocaptured Properties

For a full list of all autocaptured properties in Heap for web and mobile, see Autocaptured Data.

Custom Properties

Custom properties allow you to enrich your autocaptured data with data from Heap’s APIs and snapshots. For example, you can use the addUserProperties API to assign custom properties to any of your users from your servers, such as account-level information from your database, or demographic info. See our API docs for information on how to set up custom properties.

Property Suggestions

When you label an event, if data attributes are present on the event, Heap will provide property suggestions associated with the event that you can choose to add to your event.

Once the event has been created, the newly created property will also be available via Data > Properties.

Property Notes

For any property, you can include an annotation of the property to provide your team members with more context on what it is. This is particularly useful for properties like revenue that might have complex data types or custom properties added via snapshots, like the example below.

The notes added in this view also are shown throughout the drop-downs and analysis modules in Heap. For example, you may want to provide context on your revenue metric as seen below:

Exporting Property Data

You can export property data to a CSV to analyze outside Heap. To do so, select the checkmark next to them where they are listed on the properties page, then click Export Metadata.

You’ll be prompted to select which types of metadata you want to export. Make your selections, then click Export Properties to download the file.