This guide covers a few general strategies for creating stable event definitions regardless of the frontend framework that you use.

Use Data Attributes

One best practice for using Heap with your minified web app is to use data-* attributes. These are commonly added to web apps by developers to store semantically useful information. Since they are manually added and store semantic information, they are great candidates for being used in event definitions.

Heap’s Event Visualizer is designed to automatically pick up the most unique attribute possible. Any data-* attribute will typically be the most specific semantic identifier for a given element, making event definition easier and more reliable.

Here’s an example button with a class and data-* attribute.

<a data-returning-login="true" href="/login" data-ol-has-click-handler="" style="">Log In</a>

In Heap, you would define this event as a Click on: [data-returning-login="true"].

Use data attributes from testing frameworks

If you use an automated testing framework to test the frontend of your app, it may be possible to use data-* attributes which those testing frameworks rely on to function.

For instance, Cypress is a frontend testing framework which recommends adding stable attributes to the DOM so that the testing framework can effectively select elements. These attributes are often data-test-id or data-cy. Since these attributes are actually used to test the correctness of your app, they also make great candidates for use when analyzing various metrics for your app. See Cypress’s doc on selecting elements for more information.

Use Semantically Useful Class Names

While data-* attributes are often extremely useful for event definitions, they might not always be desirable for your engineering team. That’s why our next recommendation is to write semantically useful class names.

In React Styling Libraries & DOM Minification, we discuss ways to automatically generate semantically useful class names when using a React styling library. Below, we discuss how to define events using those class names once they are in your app.

Defining events using semantically useful class names

Here’s another example of a header with some text. Notice that the classes have useful, semantic meaning, i.e. product-form__title___2QndP.

<h1 class="heading__heading___2MSiC product-form__title___2QndP heading__without-margin___3ORnh">Some data</h1>

The downside of this class name is when we try to use Heap’s Event Visualizer, it uses the full class name, including the appended random string ___2QndP which is likely to change between builds.

To handle this variable appended string, we need to use a wildcard character: *

In this case, the correct event definition would be Click on: product-form__title*

You can create this event directly in the app:

Use Accessibility Attributes

Accessibility or a11y has become an integral part of the web. Generally, accessibility attributes are added to sites to make a site more accessible to people with disabilities. These accessibility attributes are commonly prepended with aria- where aria stands for Accessible Rich Internet Applications. Since these attributes are useful to users, they are often semantically meaningful and stable between builds.

For instance, to make a button more accessible, you may add an aria-label attribute like so:

<button aria-label="Enable">✔️</button>

Heap will capture that aria-label attribute. Since Heap captures the aria-label attribute and it’s unlikely to change between builds, it is a great attribute to define an event on.

Use heap.track()

If some or all of your web app does not have any stable, semantically meaningful attributes in the DOM, it’s still possible to track user behavior by adding heap.track() calls to your web app.