Contact Us

Installation

Pendo Help CenterInstallationInstallation for Single-Page Frameworks

Installation for Single-Page Frameworks

Overview

Pendo’s product analytic capabilities can be particularly helpful with single-page application frameworks. Traditional Web analytic tools struggle in these environments as they are tailored around page views. Within a single-page framework, many different user interactions may happen within the context of a single pageview. Development teams can work around these issues, but it adds additional 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, Pendo requires the insertion of a single and small JavaScript snippet in your application. This snippet securely and asynchronously loads a Javascript file from our CDN.

Your Installation Snippet

Your Pendo installation snippet can be found on the Install Settings page (only accessible by admins), and can be inserted into your common HTML template as is for most apps. It can take up to 2 hours for data to initially feed into Pendo. You’ll receive an e-mail once we begin receiving data.

Installation Process

The installation approach is similar to a multi-page installation where the same installation snippet is used, however, it is deployed slightly differently. With a single page framework, the first part of the Pendo snippet,  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.

Our Agent 2.0 FAQ includes more information on the installation snippet and how the Pendo Agent is updated.

Here is a sample snippet to show you how you will break up the snippet for install: snippet-breakdown.png

Part 1 of Snippet

So for example, you would add the following portion of the snippet to your application library or index page:

warning: This is a sample snippet to illustrate how you will need to adjust your provided JavaScript Snippet. To ensure you are copying and modifying your snippet with your unique API key, please refrain from copying directly from this article.

snippet-part1.png

Part 2 of Snippet

Then, once you have the user context within the application, you would use the second half of the snippet to pass the user, account, and any additional demographic information to Pendo:

warning: This is a sample snippet to illustrate how you will need to adjust your provided JavaScript Snippet. To ensure you are copying and modifying your snippet with your unique API key, please refrain from copying directly from this article.

snippet-part2.png

Again, this is the the extent of the coding that is required to install Pendo within your application. All user tracking will begin immediately, and specific features anywhere in the application can be tagged in the Pendo interface for retroactive analysis.

Install FAQ

Where Do I install the snippet? Everywhere!

The snippet needs to be installed on every page. Does your site use iframes? If so, you’ll want to make sure it’s installed within each of these frames.

Why Do Universally Unique IDs Matter?

Make sure you are passing unique Visitor and Account IDs. This is what identifies your Visitors and Accounts. If any of these are duplicated, multiple users’ data could be aggregated under a single ID.

Why Does Metadata Matter?

What information do you have about your Visitors and Accounts that you want to pass to Pendo? You will be able to segment Visitors based on any information that is passed. (Perhaps you want to pass us the role of each user so that you can eventually target guides or filter data toward specific roles.) Learn more about Metadata.

Who Are Your Unknown Users?

Unknown or anonymous users are those who don’t login to your app. Do you have anonymous visitors and would you like to see their data? Would you like them to be able to see guides? You can enable analytics on your unknown users and allow them to see guides if you choose.

Is There Any Data You Don’t Want to See?

Between testing and staging environments and internal users, data can get messy. Is there data you absolutely do not want included? Blacklist it. Pendo can hide data based on Server/Host Domain, IP Address, Visitor ID, or Account ID.

Validation and Troubleshooting

How Do I Validate That My Install is Correct?

To check the status or your install and if metadata is set for a particular user you can do the following:

  1. After installing Pendo, open up your application in a browser tab.
  2. Sign in as a user.
  3. Open the Browser Developer Console.
  4. Type pendo.validateInstall() into the console and hit enter.
  5. Information on the Visitor’s identifiable metadata will be returned.

Why is My Data Not Appearing in Pendo?

Confirm that your API Key has been included in the snippet. If you copy your snippet from your Install Settings page, the API Key is already included. If you pulled the snippet from somewhere else, confirm the API Key is present in your snippet. There are data syntax rules you will need to follow in order for Pendo to receive all of your data: Do not send null values for any fields. If you do not have data for a field omit sending that field. Any custom fields added in the snippet cannot include a space. This field must start with letter or underscore and can follow with any combination of letters or numbers; as well as an underscore. Click here for more on Visitor/Account Metadata.

Note: Data will not appear instantly. It is batch aggregated at the top of the hour, every hour, and can take up to 15 minutes past the top of the hour to fully appear in the Pendo UI.

pendo.js and pendo-staging.js

The Pendo snippet will first load pendo.js agent. This agent will first check if the server hostname matches a staging server rule and if so, load the pendo object from pendo-staging.js instead of pendo.js.

No Logged In Users

During setup, the message "No Logged In Users" informs that Pendo is receiving basic data from your application (specifically that pages and features are being used in your app), but there is no user identifying information. While you can still use Pendo without this data, the functionality will be greatly reduced.

In snippet, there are two blocks of interest for this issue, the Visitor block and the Account block. The data is either not being passed, or it is structured incorrectly.

Here is the template for this code:

visitor: {
  id:              'VISITOR-UNIQUE-ID'   // Required if user is logged in
  // email:        // Optional
  // role:         // Optional

  // You can add any additional visitor level key-values here,
  // as long as it's not one of the above reserved names.
},

account: {
  // id:           'ACCOUNT-UNIQUE-ID' // Highly recommended
  // name:         // Optional
  // planLevel:    // Optional
  // planPrice:    // Optional
  // creationDate: // Optional

  // You can add any additional account level key-values here,
  // as long as it's not one of the above reserved names.
}

This is an example of what the data may look like in your code:

visitor: {
  id:              $user.ID,
  email:           '$user.email',
  role:            '$user.accessLevel',
  creationDate:    $user.creationDate
},

account: {
  id:           '$account.ID',
  name:         '$account.name',
  planLevel:    $account.subscriptionCost,
  isFoo:        $account.isFoo
}

This is an example of what the code would look like after it is processed and sent to Pendo.

visitor: {
  id:              62343,
  email:           'john@doe.com',
  role:            'admin',
  creationDate:    1404326949156
},

account: {
  id:           17,
  name:         'Acme, inc',
  planLevel:    995,
  isFoo:        false
}

Optional Flags

There are three optional flags you can place in the JS snippet:

excludeAllText: true

By default, the Pendo Agent collects the text values from DOM elements that a visitor clicks on (but we do not collect text from text areas and input fields). This is done to more accurately describe what HTML is part of a Feature (e.g. we use the button text to determine the different between the ‘Search’ button and the ‘Log out’ button so you can know which one your users are using more).

If you don’t want any of this text to be gathered by Pendo, simply set the excludeAllText flag to true inside the pendo_options object in your snippet. Note: This will make it more difficult to track features in your product.

Keep in mind, only elements that are actually clicked on (and their parents up to body) are ever processed. At no point will the Pendo Agent scrape your entire web application of its own accord.

disableGuides: true

If you know that you are not going to be using the Guides product at all (no in-app messages to your end-users), you can set the disableGuides:true flag, which will result in the Pendo snippet not making an outbound request to see if there are guides available.

excludeTitle: true

warning: Agent 2.11.5+ only
By default, Pendo collects <title> in page load events. This can be prevented by including the optional excludeTitle: true flag.

Pendo Performance

What is the performance impact of adding Pendo’s Javascript snippet to my web application?

Pendo’s Javascript files are hosted and served on Amazon’s Cloudfront CDN utilizing state-of-the-art edge caching. The javascript file is minified to only 54K bytes and loads asynchronously.

Data is securely transmitted via SSL from each user’s browser to our server every two minutes and when a page is ‘unloaded.’ Data is compressed prior to sending and each transmission is less than 2K bytes.

For additional information, check out the Security & Privacy help article.

© 2018 Pendo  |  Terms of Service  |  Privacy Policy