Installation for Single-Page Frameworks

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 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 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 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.

Warning: All snippets shown here are sample snippets 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.

Here is a sample snippet to show you how to break up the snippet for installation:

Fullsnippet.png

Part 1 of Snippet

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

SPAsnippetpart1.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:

SPAsnippetpart2.png

 

Frequently asked questions

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.

Learn more about Unique IDs.

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 log in 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.

Learn more about Anonymous Visitors.

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 to be included? Exclude it. Pendo can hide data based on Server/Host Domain, IP Address, Visitor ID, or Account ID.

What about URLs?

Pendo relies on the URL to distinguish between different pages of the application. Does the URL change as the user navigates throughout the application? If the answer is no, we recommend implementing the Location API.

What if Visitor or Account data changes without a window reload?

We have some functions that can either modify optional fields or reinitialize a session with a new Visitor or Account ID.

If you're modifying additional metadata associated with a Visitor, call pendo.updateOptions().

If you need to change a Visitor or Account ID, call pendo.identify()and pass in your Visitor or Account IDs as you would in the initialization.

Learn more about our Initialization and Identification functions in the developer docs.

 

Validation and troubleshooting

How do I validate that my installation is correct?

To check the status of 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 does my data not appear 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:        // Recommended if using Pendo Feedback, or NPS Email
  // full_name:    // Recommended if using Pendo Feedback
  // 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
  // is_paying:    // Recommended if using Pendo Feedback
  // monthly_value:// Recommended if using Pendo Feedback
  // 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',
  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,
  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',
  full_name:       'John Doe',
  role:            'admin',
  creationDate:    1404326949156
},

account: {
  id:           17,
  name:         'Acme, inc',
  is_paying:    true,
  monthly_value:'99.99',
  planLevel:    995,
  isFoo:        false
}

 

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 before sending, and each transmission is less than 2K bytes.

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

Optional flags

You can add optional flags to the JS snippet. Learn more here.

For additional FAQs, go here.