Skip to content
  • Home
  • Developers
  • API
  • Releases
  • Community
  • University
  • Status
  • Home
  • Developers
  • API
  • Releases
  • Community
  • University
  • Status
Home Administration Data Governance Naming conventions overview
Session Replay Getting Started Administration Data Management Definitions Charts Analysis Examples Heap Plays Integrations Heap Connect Data Privacy

Read in Order

  1. Data Governance: Overview
  2. Naming conventions overview
  3. Categories overview
  4. Definition Verification
  5. Event Repair Flow
  6. Dataset Cleanup
  7. Definition History
  8. Managing Events, Segments, Properties, & Reports
  9. Ongoing Maintenance

Table of Contents

Was this article helpful?

Yes No

Thank you for your feedback!

Naming conventions overview

In this article you'll learn:

  • Recommended naming conventions for events, segments, and reports
  • How to enable and customize a naming convention for events (Admins & Architects only)
  • What the user experience looks like when using the naming convention after it's been enabled

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.

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.

Was this article helpful?

Yes No

Thank you for your feedback!

Last updated January 20, 2023.

event naming conventionsreport naming conventionssegment naming conventions
  • Blog
  • Partners
  • Legal
  • Security
  • Terms
  • About
  • Careers
  • Privacy
  • Contact Us

© 2023 Heap, Inc.