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 define 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, defined 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.
- Defined properties: You can define 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 define 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 are unable to 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 queries when conducting analysis:
- Behavioral properties: Behavioral properties can be used to filter your reports by users who have or have not 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 reports 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 have 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, wheres 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.
To review the list of properties available in your Heap account, navigate to Definitions > Properties. Your properties are organized as follows:
- Personal Defined User Properties
- Personal Defined Event Properties
- Defined User Properties
- Defined Event Properties
- User Properties (from Web, iOS, Android and Server)
- Event Properties (from Web, iOS, Android and Server)
- User Properties from Sources
- Event Properties from Sources
- Hidden User Properties
- 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 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.
You cannot modify the data type of certain properties that are native to Heap, such as autocaptured client-side properties and source properties.
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 manually 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.
For a full list of all autocaptured properties in Heap for web and mobile, see Autocaptured Data.
Custom properties allow you to enrich your autocaptured data with data from Heap’s APIs and from 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.
When you define an event in the Event Visualizer, 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 definition.
Once the event has been created, the newly defined property will also be available via Definitions > Properties.
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 definitions 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 of 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.