Snippet Install

Pendo helps product teams deliver software users love. Pendo captures product usage patterns and user feedback, and lets you communicate in-app to onboard, educate and guide users to value. To get started, Pendo requires a small JavaScript snippet to be inserted into a template that is present on every page of your application. After you signed up for Pendo, you should have received an email (From Pendo Support) to sign in and view your installation instructions.

Pendo requires the insertion of a small Javascript snippet into a template that is present on every page of an application. This 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:

How Does Pendo Work?

Before you perform the installation process, here is a little background on how the Pendo platform works. Pendo operates across 3 primary components:

1. The Pendo Agent (The outcome of installing the snippet)
2. The Pendo Application (app.pendo.io)
3. The Aggregation Engine (Pendo backend)

Across these 3 components, you will be able to do the following generalized actions:

• Uniquely identify and associate metadata with your site's visitors.
• Consume the product usage data that Pendo collects via rich analytics, segmentation, and exploration.
• Deliver in-app messages, tooltips, polls, and walkthroughs to your desired target audience within your app.

Installation Process

Although you don’t need to be a developer to use Pendo, it does require a quick technical install. 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. Identify what information (or metadata) you want to capture and use in Pendo.
2. Install the Pendo Snippet
3. Verify your installation

Your Pendo installation snippet can be found in your app’s Subscription 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.

Step 1. Identify Additional 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. So, by adding more metadata, you will essentially 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 variable that you will need to adjust within the Snippet to identify users within your Pendo data. VisitorIDs are universally unique values across environments or product lines to help you 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 to 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 slice by, or target to - such as industry, plan price, or account creation date.

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 2. Install the Pendo JavaScript Snippet

After you work with your developer on what metadata you want and adjust your Pendo Snippet, the next step is to install it in your Product.

So, where do I add the Pendo snippet? Everywhere:

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

Once you complete the install, Pendo will notify you via email when the first piece of data from your application is received.

Step 3. Installation Validation

After installing your snippet, 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

To navigate to the “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 and if metadata is set for a particular user by following these steps:

• Open up your application in a browser tab and sign into your app (not Pendo) as a user
• Open the Browser Developer Console
• Type pendo.validateInstall() into the console and hit enter
• Information on the Visitor’s identifiable 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, 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 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.

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 whitelisted. Broadly, guides are inbound traffic and analytics are outbound.

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:        // 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
}

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

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.

More on Installation

Single-Page Frameworks

The installation approach is similar to a multi-page installation, and 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.

Learn more on Single-Page Installation.