Usage
To install Heap with react (also known as reactJS), follow our web installation instructions. The snippet attaches Heap to the browser’s window, so you can access Heap from within React components by calling window.heap.
Defining Events
When customers use your product or app, Heap collects that raw event data. This includes all references to the tags, classes, IDs, and attributes that make up what’s known as the DOM (Document Object Model). When you define an event, you’re telling Heap what that data means— it’s a virtual pointer to all the raw data we collect.
Most of the time, those classes, IDs, and attributes have some semantic meaning. For example, a signup button may have an ID of “signup” and look like this:
<button id="signup">Sign Me up!</button>It may also have classes, a type, a name, etc. depending on the element, such as this:
<button id="signup" class="btn btn-primary" type="submit" name="signup">
This semantically useful information makes it easy for you to identify and define events. However, with newer frameworks like React, which include libraries and modules to make developer work faster and more efficient, the amount of semantically useful information in the DOM is often diminished.
React libraries that implement CSS modules do non-conventional things to the HTML code on the page. They may completely replace semantic class names with short, random strings. They may preserve some semantically useful information, but may also append a random string to the end of the class, which changes on each build. Some implementations may only use a data-react-id attribute which has no semantic value (typically just a number) and that Heap, accordingly, doesn’t track.
With this in mind, we recommend the following best practices when using Heap with react websites.
Use Data Attributes
One best practice for using Heap with your React app is to use data-* attributes which allow developers to store extra information on standard, semantic HTML elements without other hacks. They are commonly used in React development. Heap is optimized for this type of semantic layer.
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.
<button class="layout-header-template__user-menu-button___3HsXw" data-tname="AccountMenu">
In Heap, you would define this event as a Click on: [data-tname="AccountMenu"].
Using Semantically Useful Class Names
While data-* attributes are the way to go, it might not always be desirable for your engineering team. That’s why our next recommendation is to write semantically useful class names. (It’s possible to build an entire React app without ever doing this, but it’s still a best practice to use semantic classes.)
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:
