We provide visual labeling as an easy way to define events without using code. However, if you are familiar with your site’s markup, you can manually create events via base event definitions. To do so, complete the steps below.
- Navigate to Definitions > Events, then click the New Definition button and select New Event in the drop-down.
2. Add a category and name to your event. For our example, we are manually defining a click on the checkout button as it appears on the product page.
If you are creating a personal event, click on the Publish To Shared Space toggle to turn it off. You’ll see the category switch to Personal.
3. Select a Source. The options listed might include the following based on which platforms you have Heap installed on and integrated with.
- Web: An event that happens on your website.
- iOS/Android: An event that happens in your mobile app.
- Integration (ex. Shopify, Salesforce): An event from an integration you have connected Heap with.
- Custom: Select this option if you are setting an event based on data pulled in via one of Heap’s APIs. See Using Custom Events to Build New Events below to learn more.
- Combo: Select this option to combine multiple existing events into one. See Combo Events below to learn more.
Depending on the type of source you’ve selected, you may need to select a base event that you will build the event definition on, then the custom criteria for that event. See the platform-specific sections below for more details:
For our example, we will define this as a web event with the base event Click on, using the CSS selector for a click on the checkout button as the definition for that event.
5. Click Define Event & Request Confirmation to create your new event.
Once submitted for verification, an event definition cannot be edited. However, you can always cancel the submission, edit the event further, and resubmit as needed. For more info on how the verification process works, see Definition Verification.
For a deep dive on defining events via the Event Visualizer and CSS, check out our Creating Event Definitions course in Heap University.
There are 5 types of base events we capture in Heap out-of-the-box that you can use to manually define new events:
View page: A pageview (MDN reference)
Click on: A click on an element (MDN reference)
Change on: A change in an
selectelement (MDN Reference)
Submit on: A form submission (MDN Reference)
Start Session: A session
We provide a list of recommended pageview events to define based on the popularity of those pages. Defining these pageviews as events allows you to dig into engagement with those pages to better understand user behavior. For more info, see Pageview Suggestions.
To better understand what modifiers to apply to these events, we’ll walkthrough how common CSS elements should be written in Heap event definitions.
Tags, Classes, and Ids
Tag refers to the tag name (e.g.
<input> ). In line with standard CSS practices, in Heap, this is written as
A class name comes after the attribute
class=. Classes are prepended by a period, for example
An id comes after the attribute
id=. IDs are prepended by a hash, as in
An attribute is the part of the markup that is not an
class, such as
name. Attributes are contained in square brackets, as in
[placeholder="Email Address"]. Quotes are only required if the attribute contains a space.
In this example, you would define:
<form accept-charset="UTF-8" action="/login" class="login signupform" id="new_user" method="post"> <label>Email</label> <input autofocus="autofocus" class="email" id="user_email" name="email" placeholder="Email Address" tabindex="1" type="email"> <label>Password</label> <input class="field with-reset" id="user_password" name="user[password]" placeholder="Password" tabindex="2" type="password" /> <input class="button b-big" name="commit" tabindex="3" type="submit" value="Sign In" /> </form>
- A pageview as
View page: /signup.
- A click into the email field as
Click on: .emailor
Click on: [placeholder="Email Address"]which uses the attribute instead of the class.
- A change in the password field as
Change on: #user_password.
- A form submission as
Submit on: #new_user.
You can combine tags, classes, and IDs in the same element by stringing them together. For example,
Change on: input#user_email.email.
To combine selectors in a hierarchy, add a space between the tags, classes, and IDs. For example, let’s say you have more than one email form on a page: one to sign up, another to subscribe to a newsletter, and both email fields are defined the same way. You can use the
form ID to specify which form to target;
Change on: form#new_user #user_email which will limit the event to just the new user sign up form; and
Change on: form#newsletter #user_email, which would limit the event to the newsletter form.
To use attributes in an event definition (here defined as attributes other than classes or IDs, and which includes things like
type, and anything that starts with
data-*), simply surround the attributes’ key and value elements with brackets. For example,
name="email" from the sample markdown above becomes
[name=email] within Heap’s event creator.
You can also use simplified attribute selectors to match data attributes:
[key]Targets elements with a key attribute
[key=value]Target elements with a key attribute that’s value.
[key*=value]Targets elements with a key attribute containing a value within it.
[key^=value]Targets elements with a key attribute starting with value.
[key$=value]Targets elements with a key attribute ending with value.
Please note, we do not capture the following attributes:
We only capture class and ID, not attributes, on
iOS, Android, React Native
We provide the option to manually create mobile and React Native event definitions from the events page. However, we strongly recommend defining new mobile and React Native events via visual labeling or the live data feed. These allow you to verify the accuracy of the definition by testing it via a device or emulator.
When defining iOS, Android, and React Native events, you’ll use autocaptured events and properties as a base, then apply filters to define your new event.
For example, we have a base ‘touch on’ event:
Which you can use to define a touch element and apply a filter to specify the criteria for this event definition:
Base Events & Properties for Defining Mobile Events
Out-of-the-box, Heap provides the following mobile events which you can use as a base, listed on the left. Each is defined based on the base property in the middle column. Key properties that are often used to define a new event based on this one are listed on the right.
|Event||Base property||Key properties|
|View Screen||Full Activity||n/a|
|Fragment Transitions||Added Fragments||Activity, Full Activity, Visible Fragments|
|Page Transition||Transitioned-to Page Title||Transitioned-to Page Class, Transitioned-from Page Title and Class, View Pager Swiped, Target Resource ID|
|Touch On||Hierarchy||Target Text, Target Class, Full Target Resource ID|
|Edit Field||Hierarchy||Target Text, Target Class, Full Target Resource ID|
|App install/Upgrade||Current Version Name||Is Upgrade|
|Event||Base property||Key properties|
|View Screen||View Controller||Title, Accessibility Identifier, Accessibility Label|
|Touch On||Hierarchy||Target Text, Target View Class, Target View Name, Accessibility Identifier, Accessibility Label|
|Action Methods||Action Method||Target Text, Target View Class, Target View Name|
|Edit Field||Hierarchy||Target View Class, Accessibility Identifier, Accessibility Label|
|Gesture Recognizers (any event related to gestures, such as panning, zooming, etc.)||Target View Ivar||n/a|
|App Install/Upgrade||Current Version Name||Is Upgrade|
|Event||Base property||Key properties|
|View Screen||Screen path||Navigation Action, Screen Name|
|Touch On||React hierarchy selector||Target Text, Is Long Press|
|Change On||React hierarchy selector||n/a|
|Edit Field||React hierarchy selector||Placeholder Text|
|Page Transition||React hierarchy selector||Page Index|
Generally, it’s important to ensure that the event is defined by a set of properties that specifically refer to that particular interaction. When defining mobile events, consider the following:
- Can this event be specifically defined based on the default property it relies on?
- Do the property values have semantic meaning (e.g. “RegistrationFormScreen”) or are they generic (e.g. “FormScreen”)?
- Are certain key property values being reused throughout the app?
Currently, Heap cannot be used to capture the following types of events.
- Push notifications: As a workaround, you can send custom server-side events as push events. However, since these will not be sessionized, and interactions with these push events will be part of a client-side session, using this workaround will inflate your session count and you will not be able to conduct session-based analysis.
- App crashes: Heap is not intended to be used as a replacement for Crash analytics solutions. A workaround is to catch otherwise-uncaught exceptions to send as a custom event to Heap.
- Uninstall events
Additionally, we do not provide a way to tell if an event was captured while the app was offline.
We recommend reviewing the Best Practices sections of the iOS and Android visual labeling guides, as most of these also apply to defining mobile events via the events page.
React & Angular Apps
Using a Single Page App framework like React or Angular? Be sure to write distinct classes or IDs or make use of data-attributes so you can accurately define events based on those selectors.