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 installing Pendo.
Pendo admins can find the install script in Install Settings in Pendo.
- Navigate to Settings > Subscription Settings from the bottom of the left-side menu.
- Open the Applications tab.
- Find and open your application from the Applications list.
- 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:
- Initialize on application load and identify visitors after login.
- Initialize only after the visitor signs in.
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.
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:
- Open your application in a browser tab.
- Sign in as a user.
- Open the Browser Developer Console.
- Type
pendo.validateEnvironment()into the console and press enter.
This returns information on the Visitor IDs and metadata you set up.
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:
- Navigate to Settings > Subscription settings from the bottom of the left-side menu.
- Open the Applications tab.
- Find and open your application from the Applications list.
- Open the Raw Events tab.
To view advanced configuration settings, such as track events or metadata, see the Pendo Agent API documentation.