Intro to Properties

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. There are two types of defined properties, conditional and formula. Details about these property types 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.

Properties List

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

1. Personal Defined User Properties
2. Personal Defined Event Properties
3. Defined User Properties
4. Defined 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 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 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.

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

Defined Properties

You can define new properties based on existing property values in Heap from the properties page and via property suggestions in the Event Visualizer. This allows you to define a new virtual schema on top of your existing dataset for specific use cases that require custom groupings of property values. Some popular use cases for defined properties include:

• Define custom marketing channels
• Aggregate unique property values into larger groupings
• Merge, re-name, or clean up existing properties

Property Suggestions

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.

Creating a New Defined Property

To define a new property in Heap, click the New Definition button in the top right corner of the Properties page and select New Property. This will launch the property creator, as seen below.

A property definition consists of the following components:

1. The property name
2. The property type (event or user) – once specified, you’ll be restricted to only using properties of the same type within each case statement
3. How the property is defined (conditional or formula)
4. Cases (conditional properties) and formulas (formula properties)
5. Conditional properties only: an optional default value for when the property cases are not met

Team members in the Read-Only and Consumer role can only create personal properties. Analysts, Architects, and Admins can create shared properties using the visibility toggle in the top-right.

Limitations

Defined properties have the following limitations:

• They cannot be used in event definitions
• They cannot be used in segment definitions.
• In Heap Connect, defined properties sync to Redshift and S3 only.

Conditional Properties

Conditional Properties Overview

As referenced in the name, conditional properties are defined by the conditions applied to them. They consist of cases, which are ‘when {condition} is met, set value to {value}’ statements, with optional default values applied, as detailed below.

Cases

A case in a conditional property consists of the following components:

1. The When clause (the property mapping condition)
2. The Set value to a clause (the value populated based on the when condition)

Cases are evaluated in order they are defined. In general, it’s best practice to place cases with more general conditions at the bottom or below cases with more specific conditions to prevent any misclassifications.

A When clause requires a Property, an Operator, and a Value to formulate a condition. In the example below, this might be when a Referrer contains Google if you’re creating custom marketing channels in Heap.

A set value to a clause requires a value type which can either be a constant value or a property value. A value is also required if the value type is set to constant value to complete the clause. When value type is set to constant value, the value provided in the input field will always be the value created for the new property for the condition specified.

In the example below, we’ll be setting a value of Search whenever the referrer property contains Google so that we can group by our own channel definitions in analysis.

When value type is set to property value, you’ll also need to select the property in Heap whose value you’d like to adopt in the newly created property. In certain cases, you might not have an explicit value you want to map a case to and want to use an existing property value in the newly created property. This is particularly useful when merging property data to organize your account in the example shown below:

When defining a conditional property with many different conditions that are similar, you can use the copy button to duplicate the condition, then update the duplicate.

Conditional Properties Use Cases

Marketing Channels

Heap has an out-of-the-box ‘Marketing Channel’ property that allows you to review where your visitors came from. You may see ‘Other Referral’ listed there, which means those results don’t fit the criteria for any of the other referral states. Note that Marketing Channel is a generic property; we encourage you to make a copy of this property and customize it to fit your companies attribution model, as described in our example below.

If you’re creating custom marketing channel groupings in Heap, you’ll want to create a Channel property on the event level that specifies several conditions that map to your definition of marketing channels. Once created, you’ll have several conditions in your definition that look like the following example:

Aggregating unique values into larger groupings

A common use case for defined properties is to take countless unique values and map them to custom groupings that you can use in analysis. As an example, the Heap application generates unique URLs for each query run. For the ease of analysis, I may want to aggregate these values into custom groupings to understand which analysis modules in Heap users are engaging with based on the URL pattern. To create an Analysis Module property, I would define the following conditions:

Merging, re-naming or cleaning up existing properties

Properties can become messy and unorganized in Heap over time. For example, you may have sent one custom property last year to Heap titled plan but made a change in your implementation to send the property as Plan the following year. You can leverage defined properties in Heap to merge these values and create a new complete property as a result as shown below.

Formula Properties

Formula Properties Overview

Formula properties allow you to transform existing properties in some way to make it easier to review that property data. For example, you can use formula properties to combine existing street name, city, and state properties into one new address property, or extract part of a URL to capture important query parameters.

Formula properties consist of a function and arguments to that function. The arguments can be autocaptured or custom properties, some constant text, or nested formulas up to a certain depth. The initial functions we support are:

• Convert to uppercase
• Convert to lowercase
• Concatenate (combine two values into one)
• Coalesce (take the first non-null value of two values)
• Extract using Regular Expression (use Regex to pull out part of a value)
• Replace using Regular Expression (use Regex to replace part of a value)
• Add
• Subtract
• Multiply
• Divide

Regular Expressions

Regex (short for regular expression) is a mini programming language used to define a search pattern. Learn more about it at RegexOne and play around with formulas at Regular Expressions 101.

Formula Properties Use Cases

Formula properties are extremely customizable based on your app’s data structure and analysis needs. Here are a couple of broadly applicable regex examples for capturing these properties:

• Extract a query string value given a key
• Extract a substring from a path

Review the use cases below for additional examples of how to set up your own formula properties.

Group together different address properties into full address property

You can use formula properties to group together different properties to display as one property in analysis. This gives you the flexibility to view data for many different properties grouped together by category.

For example, you may want to display your users’ full locations in your analysis results rather than having those bits of location data in different rows.

To concatenate different location properties into one, set up a formula property with the formula ‘Concatenate’ nested for each property. Depending on how you want your location listed (such as having their zip code added) you may need to nest more properties than this example.

Group together inconsistent casing across browsers & devices

Because browsers and devices tend to vary in how content is displayed, you may find yourself in the situation where a call to action button, such as ‘NEXT’ that is rendered in different cases (Next, NEXT, next) across these different browsers or devices. You can set up a formula property to solve this problem without losing historical data or requiring your engineers to update your codebase.

When creating the property, select ‘Convert to Uppercase’ or ‘Convert to Lowercase’ based on which way you want it to be cased, then add in the property that needs consistent casing.

Group together related UTM parameters

You may want to define a property like ‘Source – Medium‘ to combine your Source and Medium properties into one view instead of appearing as two columns when analyzing your data. This also frees you up to view a third property type, such as device.

You can group together these UTM parameters by selecting ‘Concatenate’ under the ‘Formula’ drop-down, then selecting the two properties.

Group together related sections of a path

You may need to extract a piece of information from a URL to capture in it’s own property, such as the domain of a user’s email address.

To do so, select ‘Extract Using Regular Expression’ as the formula and define the regex to extract the email address from the path.

Extracting non-UTM parameters from a query string

You may want to capture non-UTM parameters directly from a URL, such as capturing the channel from ?source=CHANNEL.

You can set this up using the Extract Using Regular Expression formula.

Extracting the product ID of a URL

You may want to grab the product ID from the URL to analyze the popularity of your different product pages.

To do so, use the Extract Using Regular Expression formula and define the correct regex to apply to your URL.

Note that the regular expression you need to define will vary based on the path of your URL.

Showing the full referrer in analysis modules

By default, Heap’s autocaptured Referrer property only returns the domain when used in analysis. You may want to look at the full referrer. You can set this up using a defined property.

Remove trailing slashes in reports when grouping by path

When grouping by path, paths that are semantically the same are sometimes split in the results, such as /test/blog-post-123/ and /test/blog-post-123, where the only difference is the presence of the slash at the end. You can set up a formula property using the following regex: (\/.*?)\/?$ to remove the trailing slash and thus ensure this data is reconciled into consistent properties.

Managing Properties

Reviewing & Updating Property Details

Once you’ve defined a property, you can review it by navigating to Definitions > Properties, searching for the property, and clicking on it in the list that appears.

On the Property details page, you can see the following:

• Data type (ID, number, text, or auto-detect)
• The property history (when it was created, verified, and last edited)
• Any notes added to the property

You can edit the property definition in the Edit Property Criteria’ section further down the page, and review the full event history at the bottom.

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

Archiving Properties

To archive a property, from the Define > Properties page, click the property to open up the property details, then click the archive icon in the top-right.

To archive multiple properties at once, from the properties tab, click the checkboxes next to the properties, then click the archive button at the top.

You can also use shift-click to select a large section of properties between two properties. So if you have:

• Property A
• Property B
• Property C
• Property D
• Property E

Click Property A and then shift-click Property E to select Properties A, B, C, D, E.

Note that built-in properties cannot be archived, only hidden. To archive snapshot properties, you have to remove the snapshot within the event it’s created on by clicking the X to the right of it.

Restoring Archived Properties

See the Restoring Archived Definitions section of the Data Cleanup guide for complete steps to restore archived properties.