Snippet Install

Overview

Pendo captures product usage insights, user feedback, and lets you communicate in-app to onboard, educate and guide users to value.

Pendo requires the insertion of a small Javascript snippet into a template that is present on every page of an application. The snippet securely and asynchronously loads a Javascript file from our CDN. We have one installation snippet that should cover all applications and we support every framework. 

This video provides a quick overview:

Installation Process

Although you don’t need to be a developer to use Pendo, it does require a quick technical install. For most apps, the snippet is inserted into your common HTML template as-is. During this process, we highly recommend that you communicate with your technical resource(s) as soon as possible so you can help him or her understand what’s needed to have a quick and successful implementation. 

Get started with Pendo Installation in this 3 step process:

1. Determine the type of install (standard or JWT)
2. Identify Visitor and Account information (metadata) 
3. Install the Pendo Snippet
4. Verify the Installation 

It can take up to two hours for data to initially feed into Pendo. You’ll receive an e-mail once we begin receiving data. Once you receive this email, head to your Subscription Settings page (only accessible by admins) to check the data flowing in.

Step 1. Determine the type of Install 

Before installing the snippet, it's very important to choose the type of installation that works best for your company: standard or JWT. To put it simply, the standard install does not require a shared JWT secret to process data, while the JWT snippet does require a shared secret to process data. Depending on your company stage and security policies, we highly recommend that you communicate these options with your technical resource(s) as soon as possible. If you choose the JWT snippet, please note the additional installation requirements necessary in order to complete the process on Step 3. 

Step 2. Identify Visitor and Account Metadata

Before installing the Pendo snippet, identify what information or metadata you want to capture. Pendo has metadata about Visitors (or users) and Accounts (or grouping of users) that’s defined within the snippet. Because these are defined within the JavaScript snippet, they are referred to as “agent metadata.”

Each Visitor and Account will have a universally unique ID associated to help track and deliver to Guides as applicable. Adding more metadata allows you to have more context within Pendo to segment or target your NPS survey to the right audience. We typically see customers identify what metadata they want to use and communicate with their technical resource(s) since metadata variables can differ between applications.

Visitor Metadata

Visitor ID is a required metadata field that you will need to adjust within the Snippet to identify users within your Pendo data. 

VisitorIDs must be universally unique values across environments and/or product lines to accurately track analytics and deliver Guides.

In the Pendo provided JavaScript snippet, your developer should replace the VISITOR-UNIQUE-ID with the unique visitor or user id associated with your product.

Here is an example list of what your visitor metadata could be:

• Unique VisitorID
• First Name
• Last Name
• Email Address (Note: If you plan to email NPS to users. Be sure to add user’s email address as a metadata value so you don’t need to adjust your snippet when the feature is released.)
• User Permissions (ie. admin, user, read-only)
• Role or Title
• Department 

Account Metadata

While not required, we highly recommend passing the account information that’s associated with a group of users. An Account ID will also be a universally unique ID that’s associated with a group of users. In addition, we recommend passing in any additional information about the account, such as the account name (if not obvious from the ID), and other information that may be helpful to target to such as industry, plan price, or account creation date.

Note: Account ID is required for Pendo Feedback. 

In the Pendo JavaScript snippet, your developer should replace the ACCOUNT-UNIQUE-ID with the unique account id associated with your application.

Here is an example list of Account Metadata you could have:

• Unique Account ID
• Account Name
• Industry (ie. Accounting, Real Estate, Healthcare, Technology, etc.)
• Market Segment (ie. SMB, Mid-market, Enterprise)
• Account Creation Date or Sign Up Date
• Contract Start Date
• Renewal Date
• Plan Price or Contract Value

Step 3. Install the Pendo JavaScript Snippet

Standard Install

For Multi-Page Applications: 

Where do I add the Pendo snippet? Everywhere:

• Insert snippet into your common HTML template
• All pages
• All iframes

For Single Page Applications: 

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.

All user tracking will begin immediately, and specific features anywhere in the application can be tagged in the Pendo interface for retroactive analysis.

Once you complete the install, Pendo will notify you via email when the first piece of data from your application is received. It may take up to two hours to receive that data.

 JWT Installation

JWT snippet installation requires requests to be signed using your shared secret with JWT. You can find the shared secret by logging in to the Install Settings page (only accessible by admins).

Step. 4 Verify the Installation 

There are 2 ways you can validate your installation:

1. Review Pendo Data Mappings & Raw Events under "Install Settings"
2. Through the Browser Developer Console

Review Pendo Data Mappings & Raw Events under Install Settings

• Click on "Settings" in the lower left-hand corner of your navigation
• Choose Subscription Settings
  
  • Hover over your app and click View App Details
  • Choose the Install Settings tab

Data Mappings

Review the Data Mappings section to ensure that the data-type listed in Pendo matches the actual data-type sent in the snippet. This metadata automatically updates when a user visits a page in your application and passes the fields to Pendo. If an agent metadata field is incorrectly populated, it can only be updated the next time the user visits your application and passes the correct information. These fields cannot be modified manually or through the API.

Raw Events

Review the Raw Events list to further validate your installation by confirming the metadata that’s been captured so far.

Browser Developer Console

Alternatively, you can validate your installation by following these steps:

1. Open your application where Pendo is installed 
2. Sign in as a user 
3. Open the Browser Developer Console
4. Type pendo.validateInstall() into the console and hit enter
5. Visitor and Account metadata will be returned

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, install within each iframe.

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 will be aggregated under a single ID.

Why Does Metadata Matter?

Metadata allows you to create powerful Segments to yield rich insights and personalize Guides. You will be able to segment Visitors based on any information that is passed. 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 Data You Don’t Want to See?

Pendo can hide data based on Server/Host Domain, IP Address, Visitor ID, or Account ID. Learn more about Exclude Lists here. 

Can I Host the Agent Locally?

The installation snippet pulls in pendo.js which contains the Pendo agent code. pendo.js can be downloaded and hosted via your application if you do not want it to be pulled from Pendo’s CDN. Admins can download this code on the Subscription Settings page by clicking on the desired Web App, clicking the "Agent Settings" tab, clicking on "Manage Staging/Prouction Settings" and then by clicking the "Download" link under your currently selected "Guide Delivery Settings". Note that you will need to update this reference in the installation snippet to point to your hosted pendo.js file.

Can Pendo Be Installed On-Premise?

The Pendo agent can be hosted locally and included in on-premise applications. Pendo currently only hosts and processes data in the cloud so this will still require a connection to the internet and Pendo servers must be added to "Include Lists." Broadly, guides are inbound traffic and analytics are outbound.

Troubleshooting

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 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 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// monthly_value:// Recommended if using Pendo Feedback// is_paying:    // 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.email',
  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',
  monthly_value:'99.99',
  is_paying:true,
  planLevel:995,
  isFoo:false}

Why are My Auto-tags Not Appearing in Feedback?

Feedback receives Visitor and Account tag values embedded within the Pendo snippet. To show metadata values (collected from the Pendo snippet) in the Feedback UI, add key value pairs for Visitor and Account tags in array format. Click here to learn more about Auto-tagging in Feedback.

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
  // tags:         // Recommended if using Pendo Feedback

  // 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
  // monthly_value:// Recommended if using Pendo Feedback
  // is_paying:    // Recommended if using Pendo Feedback
  // planLevel:    // Optional
  // planPrice:    // Optional
  // creationDate: // Optional
  // tags:         // Recommended if using Pendo Feedback

  // 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,
  tags:            ['$user.accessLevel','$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,
  tags:         ['$account.subscriptionCost','$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',
  monthly_value:'99.99',
  is_paying:    true,
  planLevel:    995,
  isFoo:        false
}

Optional Flags

There are two 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.

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.