You can use categories to organize your events, segments, properties, and reports, which makes it easier for your team to find what they need in Heap.
Managing Categories
You can only create new categories while saving or editing a report, event, or segment. Check the steps below for complete steps on how to create a category while creating or updating a report, event, or segment.
Creating Report Categories
When creating a new report, on the Save as Report pop-up, simply type the name of the new Category into the ‘Select category’ box.
To learn more about creating and managing reports, see our article on Reports.
Creating Event Categories
You can create new events in the Event Visualizer or from the Events tab in your Heap dashboard.
From the Event Visualizer
When creating a new event in the Event Visualizer, you can add a new event category by simply typing the new category name in the categories field while creating the event.
From the Events tab
You can also create a new event category while creating an event on the events tab. Simply type the new category into the categories field while creating the event.
Once the event is saved, the new category will be available in your Heap dashboard.
For more information on and best practices for defining events, see Events.
Creating Segment Categories
To create a new segment category from the Segments page, simply type the new category into the categories field while creating the segment.
To learn more about managing segments, see Segments.
Updating Categories / Moving Things Between Categories
To change the category of an existing report, event, or segment, navigate to the page it’s listed on, click on it to open up the details, then click on it’s current category name as listed at the top of the page. A drop-down will appear where you can select a different category.
Move Multiple Things Between Categories At Once
You can also move multiple reports, events, or segments into a category at once. From the Reports page, the Define > Events page, or the Define > Segments page, open the category of the report, event, or segment, click the checkbox next to the item, then click the move category icon next to “x (reports / events / segments) selected”.
Removing Categories
The only way to remove a category in Heap is to remove all of the reports, events, or segments within that category. Read the section below for steps to do this.
Removing Reports, Events, or Segments from a Category
To remove a report, event, or segment from a category, navigate to the page it’s listed on, click on it to open up the details, click on its current category name as listed at the top of the page, then update the category to ‘uncategorized’.
The report, event, or segment will return to being uncategorized, and will appear in the ‘Uncategorized’ category on that page.
Known Limitations
You cannot batch categorize in Heap – please reach out to support@heap.io if you have a large amount of definitions that you need migrated into categories and we’ll help you out!
Managing Naming Conventions
This feature is only available to customers on the Premier plan, and as an add-on to our Pro plan. To upgrade, contact your Customer Success Manager or sales@heap.io.
Naming Conventions lets Admins and Architects establish a consistent naming convention for new events. This allows you to keep your growing dataset organized by enforcing an accurate naming convention and makes it faster and easier for team members to find the exact event they need.
When the naming convention is active, team members creating shared events will have to follow the naming convention set up in their account. For example, if you set up an Action – Object naming convention, then the event name field will be completed like this:
Set Up Naming Conventions
Before we jump in, here are a couple of important things to know about how naming conventions work:
- Naming conventions are applied per project: to apply the same naming convention across multiple projects, you will need to manually update this setting for each project.
- Naming conventions are not retroactive: events created prior to your naming convention being set up will need to be manually updated to match the naming convention. This also applies when the naming convention is updated; those updates will not be applied retroactively.
- Naming conventions will not apply when an event is being renamed: the structure is only enforced when an event is being named for the first time.
Admins and Architects can enable and disable the naming conventions feature by navigating to Account > Manage > Data Governance. Click the Set Up button to get started.
You’ll be prompted to configure the prefixes, which are the building blocks of your names, for your naming convention. The default (recommended) approach is to use a Location – Action convention.
When you click on the elements in the text field (in this case, Location or Action), you’ll be prompted to define a list of values for this prefix. Following our example, for the Location prefix, we may define website (our marketing site), app (in-app pages), and help center (our documentation hub) values for Location.
For Action, we’ll follow Heap’s event property types: view, click, submit, and change.
Click the + button to add an additional prefix. After the third prefix, you’ll be able to populate the rest of the event description when creating it.
To allow team members to enter unique values for any given prefix, we can update their role to grant them the ability to add new values. To grant team members the ability to add new values, navigate to Account > Manage > Roles, select the role you wish to provide these permissions for, and check the box next to Add New Values to Naming Conventions.
Once the new naming convention is set up, it will apply to all new events created via the Definitions page in this project. This allows you to establish different naming conventions for each of your projects. Review the next section to see what this looks like for team members.
Naming conventions cannot be applied to events retroactively to events that were created before the naming convention was set up.
Using Naming Conventions
After your naming convention has been set up, when team members are creating new shared events from the New Definitions drop-down on the Definitions page, they will only be able to use the defined naming convention. If permission has been granted, they can also add values to certain prefixes, such as the Object prefix below.
This naming convention will not apply to personal events, though users will see a prompt to structure their personal event like a shared event.
This naming convention will only apply to events created via the Events page. Events created via Live View and the Users View will not have this naming convention enforced. Support for the Event Visualizer is coming soon!
Recommended Naming Conventions for Categories
Categories and naming conventions work best when used together, which is we cover both in one guide! Below we’ve provided a set of recommendations for using these effectively to manage your dataset.
Events
The category name for your events should be based off your site’s architecture. Depending on the size of your application, a category should be either a product, feature or page, and the event name should be the action.
For example:
Category: Cart | Event: Submit Purchase Form
Category: Dashboard – Account Settings | Event: Click Edit Profile
Segments
Within Heap, you can segment users by their properties, such as geographic location, as well as by their behavioral activity, such as the number of orders. A segment’s category name should be based on the type of properties or actions used to define each cohort of users. Additionally, you may choose to group segments that correspond with key metrics (e.g. DAUs) or specific business units.
For example:
Attribution Channels
Category: Attribution | Segment: Social Traffic
Category: Attribution | Segment: Direct Traffic
Category: Attribution | Segment: Organic Search Traffic
Key Metrics
Category: KPI | Segment: MAU
Category: KPI | Segment: DAU
Activity (Should be in reference to the module)
Category: Blog | Segment: Blog readers
Category: Checkout | Segment: Frequent Purchasers
Category: Checkout | Segment: Added to cart → did not complete order
Teams
Category: Sales | Segment: Bill’s Open Opportunities
Category: Customer Success | Segment: Carly’s Active Accounts
Reports
Whenever you’re performing analysis in Heap, you’re asking specific questions about your business, such as: What is my conversion rate? How many people are using this feature?
We recommend that all of your reports adhere to a naming convention based around these business questions to help inform teammates the question you’re trying to answer in Heap.
The report’s category should reflect the subject of the report, which can be based on the type of the analysis you’re performing (Attribution), the portion of the application you’re analyzing (Sign Up) or the team that the report is associated with (Customer Success).
For Example:
Category: Attribution | Question: What are the top 10 referrers?
Category: Sign Up | Question: Where do users drop off in the sign up flow?
Category: Customer Success | Question: When should we re-engage with customers?
For more best practices and an example of how Heap uses naming conventions, see Step 4: Establish Naming Conventions.