Install Pendo on a single-page web application

Last updated:

This article summarizes how to install Pendo on your single-page web application using some standard defaults. For more detailed configuration options, see the Installation section of the Knowledge Base.

If your application is built on a multi-page framework, see Install Pendo on a multi-page web application.

Overview

Pendo’s product analytic capabilities can be particularly helpful with single-page application frameworks. Traditional Web analytic tools struggle in these environments because they're tailored around page views. Within a single-page framework, many different user interactions can happen within a single-page view.

Development teams can work around these issues, but it adds workload to ensure that the analytic solutions are tracking properly. Pendo gets around these challenges by capturing all user interactions on the page and attributing them to specific users. To do this, you must insert the Pendo install script into your application. 

Your install script

Pendo is installed into your application with an install script that must be included on every page of your application. The install script consists of a short JavaScript code block (snippet) that securely and asynchronously loads the Pendo agent, which is a JavaScript file (pendo.js). The install script includes your unique API key and the initialize method needed to activate the Pendo agent. The initialize method also determines what values you pass as Visitor and Account IDs, and the metadata that you provide to Pendo. For more information about the main components of Pendo installation, see the Developer's guide to implementing Pendo using the install script.

Pendo admins can find the install script in Install Settings in Pendo.

  1. Navigate to Settings > Subscription Settings from the bottom of the left-side menu.
  2. Open the Applications tab.
  3. Find and open your application from the Applications list.
  4. Open the Install Settings tab.

For most apps, you can copy and paste the install script into your common HTML template as-is.

Raw events are passed to Pendo immediately, but it can take up to two hours for data to be processed for use in the Pendo UI. You receive an email when we begin receiving data.

Installation process

The installation approach is similar to a multi-page installation where the same install script is used. However, it's deployed slightly differently. With a single-page framework, the first part of the Pendo install script,  function(p,e,n,d,o){} is added to the application library, and then the second half,  pendo.initialize({}), is loaded with the page once the application has user-identifying information to share with Pendo.

For more information about the install script and how the Pendo agent is updated, see Update your Pendo agent.

Warning: All snippets shown here are examples to illustrate how to adjust your code. To ensure you're copying and modifying your install script with your unique API key, don't copy directly from this article.

Step 1. Define your data mappings

When initializing Pendo, you pass the following data to Pendo:

  • Visitor ID (required).
  • Visitor metadata (strongly recommended).
  • Account ID (required for Pendo Feedback).
  • Account metadata (strongly recommended if passing Account ID).

Define and test these values before the installation process to ensure that you're using globally unique identifiers as well as using meaningful metadata that enhances your ability to segment data in Pendo. 

Warning: Updating the Visitor and Account IDs after initial installation can result in anomalies in analytics and segmentation, and repeat guide experiences. All other metadata can be added or removed later with little disruption.

Step 2. Add Pendo to the index.html page

The Pendo install script for single-page applications is split into two parts. The first part pulls in the Pendo agent and needs to be included on your index.html file or another HTML file that is always present on all views in your application.

<script> 
(function(apiKey){
(function(p,e,n,d,o){var v,w,x,y,z;o=p[d]=p[d]||{};o._q=o._q||[];

v=['initialize','identify','updateOptions','pageLoad','track'];for(w=0,x=v.length;w<x;++w)(function(m){

o[m]=o[m]||function(){o._q[m===v[0]?'unshift':'push']([m].concat([].slice.call(arguments,0)));};})(v[w]);

y=e.createElement(n);y.async=!0;y.src='https://cdn.pendo.io/agent/static/'+apiKey+'/pendo.js';

z=e.getElementsByTagName(n)[0];z.parentNode.insertBefore(y,z);})(window,document,'script','pendo');
})('YOUR_API_KEY_HERE');
</script>

Step 3. Initialize Pendo

There are two common patterns for when to initialize Pendo in a single-page application:

Important: Initializing Pendo with an anonymous ID and later identifying the visitor using the pendo.initialize() call creates two Visitor IDs in Pendo (one anonymous, one identified) with separate events. Those events aren't merged into one stream of events for the end user. 

When Pendo is installed, it creates a global object on the window of your browser called pendo. The code examples that follow rely on using the global pendo object that was added to the window. If, instead of plain JavaScript, you're using TypeScript, you might need to either:

  • Use a type assertion like (window as any).pendo.initialize() to tell TypeScript to ignore warnings of pendo not existing in the window.
  • Declare pendo as a global variable in your TypeScript code, typically in a file named global.d.ts. For example: declare var pendo: any; tells TypeScript that there's a variable named pendo of the type any.

This is because TypeScript might not automatically recognise the global pendo object, which means that you might need to explicitly tell TypeScript that pendo exists on the browser Window. 

Initialize on application load

Call pendo.initialize() when your application first loads and then pass a special string ('VISITOR-UNIQUE-ID') to the Visitor ID. This generate a Pendo anonymous Visitor ID.

 pendo.initialize({
        visitor: {
            id:
        }
    });

After the end-user (visitor) signs in, call pendo.identify() and pass the identified Visitor ID and associated metadata for that visitor and account.

 pendo.identify({
        visitor: {
            id: user.ID,
            email: user.email,
            full_name: user.full_name,
            role: user.accessLevel,
            creationDate: user.creationDate
        },
        account: {
            id: account.ID,
            name: account.name,
            is_paying: account.is_paying,
            monthly_value: account.monthly_value,
            planLevel: account.subscriptionCost,
        }
    });

Initialize after visitors sign in

Wait until the end-user (visitor) signs in before calling pendo.initialize() to pass the identified Visitor ID and associated metadata.

 pendo.initialize({
        visitor: {
            id: user.ID,
            email: user.email,
            full_name: user.full_name,
            role: user.accessLevel,
            creationDate: user.creationDate
        },
        account: {
            id: account.ID,
            name: account.name,
            is_paying: account.is_paying,
            monthly_value: account.monthly_value,
            planLevel: account.subscriptionCost,
        }
    });

Step 4. Verify the installation

To check the status of your install and that metadata is set for a particular user:

  1. Open your application in a browser tab.
  2. Sign in as a user.
  3. Open the Browser Developer Console.
  4. Type pendo.validateEnvironment() into the console and press enter.

This returns information on the Visitor IDs and metadata you set up, for example:

Screenshot 2023-12-14 at 11.19.58.png

Visit the Pendo Academy for a video with step-by-step instructions on how to verify your Pendo installation. 

Once installed and initialized successfully, you can see raw events recorded in the Raw Events tab of your Subscription Settings. To view raw events:

  1. Navigate to Settings > Subscription Settings from the bottom of the left-side menu.
  2. Open the Applications tab.
  3. Find and open your application from the Applications list.
  4. Open the Raw Events tab.

For information about advanced configuration settings, such as Track Events or metadata, see Configure Track Events, Configure visitor and account metadata, and the Pendo Agent API documentation.

Was this article helpful?
3 out of 13 found this helpful