When using Heap on sites developed built with popular web frameworks and libraries, such as React, Angular, Vue, or Electron, you’ll want to take the following general and specific considerations into account. 

General Considerations

One important consideration is if the web framework/library your site is built on uses dynamically generated CSS attributes, which could break your Heap events.

When Heap captures users’ interactions on a website (ex: clicks), Heap also captures information such as the element’s tag (<a>, <span>, etc), the element’s attributes (class, ID, etc), and hierarchy. Capturing this additional information allows the data to be used in analysis.

Front-end frameworks/libraries, such as React, Vue, and Angular, allow developers to modify and create elements on a page completely within the framework/library. The problem is sometimes these frameworks/libraries will generate random text for attribute names in order to style the elements, and these random attribute names are regenerated every time their developers modify the website.

Here’s an example of a div element rendered with React’s Styled Components library:

<div class="sc-dnqmqq dhvMaI"> Click here! </div>

 If we defined an event for this element in visual labeling, we’d get event criteria along the lines of .sc-dnqmqq.dhvMaI. The problem is the next time this website is deployed, the div looks like this:

<div class="sc-fbkdwo dhdfwI"> Click here! </div>

The event we created via visual labeling will no longer capture events for this updated div because the class name is now different.

We recommend implementing additional meaningful attributes/IDs for analyses. For example, if we added a unique ID cta-1 to the div element above, we can define the event using #cta-1 and it won’t matter that the class name is being changed every time the page is modified.

The other consideration is how these dynamically generated attributes change over time. There are a range of frameworks and libraries that handle this in different ways. If they are static, this consideration can be uniquely addressed through element selectors. 

However, some will “version” or dynamically update your selectors when you update your site, which will render your events useless. In these cases, we recommend updating your website to mitigate the dynamic class changes or implementing additional meaningful attributes.

Framework/Library-Specific Considerations

Review each section below for considerations that are specific to your framework or library of choice.

Need help? Please post in Community or contact us via the Get support page in Heap.

For special considerations on how Heap works with SPAs, see Using Heap With Single Page Application (SPA) Websites.

React

React-specific considerations are covered in Using Heap with React Websites. For information on using Heap with Styled Components, see Using React with Heap.

Angular

If Heap is installed in your public index.html file, the Heap object will not be in the scope of the Angular project, so you will not be able to access the Heap client-side API. A simple solution is to include declare var heap: any; in any component/service that accesses Heap’s client-side API.

Here’s an example of an Angular service that accesses Heap’s client-side API:

import { Injectable } from '@angular/core';

declare var heap: any;

@Injectable({
  providedIn: 'root'
})

export class HeapService {

  constructor() {
  }

  track(eventName, eventProps) {
    heap.track(eventName, eventProps);
  }

  identify(identity) {
    heap.identify(identity);
  }

...

}

Here’s an example of a simple decorator for Angular:

 
interface Heap {
 
 
 track: (event: string, properties?: Object) => void;
 
 identify: (identity: string) => void;
 
 resetIdentity: () => void;
 
 addUserProperties: (properties: Object) => void;
 
 addEventProperties: (properties: Object) => void;
 
 removeEventProperty: (property: string) => void;
 
 clearEventProperties: () => void;
 
 appid: string;
 
 userId: string;
 
 identity: string | null;
 
}
 
 
 
declare var heap: Heap;

Vue

If Heap is installed in your public index.html file, it’s likely the heap object is not in the scope of your component. You can resolve this by creating a Heap instance property set to window.heap:

Vue.prototype.heap = window.heap;

Electron

Electron is a framework that allows developers to create native desktop applications using web technologies (HTML, CSS, JavaScript, React, etc). Since Electron simply packages your web project to exist as a native application, the installation process is the same as the web installation, except you have to enable cookies for Electron.

By default, Electron doesn’t support cookies, though Heap requires cookies to work properly. See our Electron installation guide for steps to set up Electron to work with Heap.

Heap requires an internet connection to send network requests whenever an interaction is detected. This means that events that occur when the app is not connected to the internet are not captured by Heap.