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.

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.

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.