Developer's guide to installing Pendo

This article summarizes the components and instructions for installing Pendo. Installation involves inserting Pendo's JavaScript code into the front-end of your Web application. Broadly, this is a three-step process:

1. Identify visitor and account metadata.
2. Install and initialize Pendo.
3. Verify the installation.

Note: The install script is commonly referred to as “the snippet”. The snippet is the code block that references the Pendo agent, and includes the API key and initialize method. The Pendo agent is the pendo.js file that provides event collection, in-app guidance, and a Feedback module, depending on your subscription. For more information on these components, see What installation involves, below.

If you’re already a Pendo customer, and would like to add Pendo Feedback to your product, see the Developer's guide to installing Feedback, which provides instructions for new Feedback customers.

Installation is the only required technical part of integrating Pendo into your application – no other engineering resources are required. Once set up, the agent provides Pendo for users of your application. Detailed documentation about the Pendo agent and API Developer can be found by visiting Engage API.

You also have further development options. You can optimize Pendo by adding custom HTML attributes for tagging and tracking events. For information, see HTML Attributes and Track Events.

You can also expand Pendo by adding integrations with other popular CRM, analytics, and collaboration tools. The scope ranges from native integrations with codeless installation wizards, to custom development. For more information, see our Integrations articles. You can also reach out to a Pendo representative for help with integrations in your subscription after completing the Pendo install.

For more information on the Pendo installation process, see Planning your Pendo Installation.

Before you get started

To install Pendo, you need:

• • A Pendo subscription.
  • Engineering resource to install Pendo.
  • A Visitor ID and Account ID naming convention.
  • A list of other metadata you want to capture.

We recommend that you use the Pendo Installation Workbook to share the information you need to complete the installation with your team members.

Data requirements

For Engage (Insights and Guidance) customers, Pendo requires a globally unique Visitor ID so that it can track individual users across environments and product lines, and to ensure Pendo tracks analytics and delivers guides correctly.

Visitor ID values are limited to 128 bytes in size. Larger values are truncated. You must have consensus on these IDs between your product and engineering teams. For details, see Step 1: Identify visitor and account metadata.

We recommend that you optimize the code for the data needs of both Engage and Feedback, which includes: globally unique Visitor IDs, email metadata, and Account IDs. For more information on what’s needed for Pendo Feedback, see the Developer's guide to installing Feedback.

What installation involves

This section briefly describes the overall steps and the main components involved in the installation process.

Pendo Installation Overview

The Pendo agent

Depending on your subscription, the Pendo agent is the JavaScript file (pendo.js) that runs in the browser to:

• • Collect and track visitor events (page loads, feature clicks, and so on).
  • Capture visitor and account metadata.
  • Load guides.
  • Deliver the Feedback module.

The agent is typically configured on Pendo servers and is then requested by the install script (“snippet”).

The install script ("snippet")

The install script, commonly referred to as “the snippet”, is a short JavaScript function that retrieves and loads the Pendo agent code (pendo.js), allowing you to track usage, collect feedback, and deliver messages and guides. To do this, the install script includes:

• • The request for the Pendo agent.
  • A customer-specific API key that maps the data that the agent collects to the product in your Pendo subscription.
  • The initialize method needed to activate the Pendo agent.

Both the install script and the initialize method must be present on all pages of your website for the agent to work, unless your application has child frames that come from the same domain as the top frame. In this case, you can configure the install script to automatically install Pendo on child frames by adding the install script to the top frame of your application. Changes to visitor identity or metadata in any of these frames is then applied to all frames.

Note: The existence of the snippet doesn't mean tracking is taking place. The snippet must be initialized to start tracking. See Initialization for more details.

The application (API) key

The install script loads Pendo as a library to make its functions available at the window-level and passes through a 32-digit application (API) key that’s included in the code block.

The API key is pre-populated in the application details of your subscription, and is found on the Install page or in App Settings.

Initialization

The Pendo agent must be initialized before it can start tracking usage analytics, collecting feedback, and delivering guides. Initialization is a JavaScript function in the Pendo install script (“snippet"), where you.

• • Determine the values you want to pass as the Visitor and Account IDs.
  • Customize the metadata that you provide to Pendo.
  • Create auto-tags for Pendo Feedback. For information, see Auto-tagging in Feedback.

The initialization code block allows you to identify visitors and accounts so that you can segment analytics, target guides using metadata passed in from your application variables (such as from a User object or similar), and auto-tag Feedback requests.

All variables passed into the install script must be defined before pendo.initalize() is run. For more information, see Conditionally Initializing Pendo.

Initialization must run on every window reload after a visitor has authenticated and in every frame (if your site has iframes). If you have a multi-page application, you might need to initialize Pendo on each page (not just the login page) or on your global template, if you have one.

Below is an example of the initialization code block, which you can find on the Install page or in App Settings. You can customize this example to meet the needs of your subscription.

pendo.initialize({
    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' // Required if using Pendo Feedback
        // 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.
    }
});

 Step 1: Identify visitor and account metadata

Pendo offers a template with your subscription, which includes the initialization code block needed for Pendo to serve guides, collect analytics, and deliver the Feedback module.

You only need to adjust the visitor (unique end-users of the product), account (groups of visitors) values, and metadata in that code. This information is sent to the agent from within your app.

If you’re a Pendo Feedback customer, you can also set up auto-tagging, which involves pulling data from your app to automatically add tags to your visitors and accounts in Feedback. We recommend that you do this now, rather than after you’ve started using Pendo Feedback. For more information, see the Developer's guide to installing Feedback.

Visitor and Account IDs

Engage (Insights and Guidance) relies on Visitor (end-user) IDs to make the end-user record unique. Email addresses make good unique Visitor IDs. You can also pass visitor email addresses as metadata. This is useful for custom segmentation, reporting, and communicating with your users.

We highly recommend using Account IDs, which are necessary for account-level analytics and reports, and for using Pendo Feedback. For more information on data requirements for Feedback, see the Developer's guide to installing Feedback.

Even if you’re not a Feedback customer, we recommend using account information associated with a group of visitors, including a universally unique Account ID across environments and product lines, to optimize the user experience of Pendo.

For Engage customers, the Visitor ID must represent one person through their entire customer journey in your various products. For information, see Multi-app subscriptions.

Multiple end-users with the same Visitor ID can result in an ID collision, causing activity for more than one user to be tracked against that one ID. This can happen even if your visitors use different apps or versions of an app in the same multi-application Pendo subscription. ID collisions can affect:

• • Visitor Metadata. Pendo records metadata based on a last-in value. The metadata is updated based on the user with the most recent activity. This can affect segmentations that rely on accurate metadata.
  • Analytics. The activity captured under a colliding ID can’t be separated, resulting in inconsistent analytics.
  • Guide delivery. If a guide is designed to be seen only once, the second user with the same Visitor ID won't see that guide.

If you’re worried that the Visitor IDs between your environments will collide, you can append an identifier for the environment to the ID with a prefix or suffix. Methods for identifying Visitors in different environments are described in Pendo in Development and Testing.

Identifying Visitors in different environments can be helpful later for excluding data. For information on excluding data, see Listing 101: Exclude & Include Listing.

There are additional considerations for Feedback customers, especially surrounding the use of email metadata and the need for Account IDs. For more information, see the Developer's guide to installing Feedback.

Metadata

You can supply metadata at the Visitor and Account levels to enrich your options for segmenting and grouping in analytics, for guide targeting, and to filter Feedback data. We recommend that you identify what information and metadata you want to capture before installing Pendo. You can also add metadata after the initial installation, which will update to the visitor and account details in Pendo.

The additional fields shown in the code block, above, are examples of metadata you can send us about visitors and accounts. You can send dates, integers, floats, booleans, lists, and strings. Pendo doesn’t support objects. See our article on Data Mappings for more information.

We strongly recommend using email metadata. Email metadata is accessible in Pendo reports, can be used to create custom segments, and can be used to email users who voted for a feature in Pendo Feedback.

If you’re a Feedback customer, you can also configure auto-tagging. For more information, see the Developer's guide to installing Feedback and Auto-tagging in Feedback.

Examples of Visitor-level metadata include: 

• • Visitor name (highly recommended)
  • Email address (highly recommended). 
  • User permissions
  • Role or title

Examples of Account-level metadata include: 

• • Account name (recommended)
  • Paying status (recommended)
  • Account value (such as ARR or MRR, also used in Feedback reports)
  • Industry
  • Market segment
  • Account creation date
  • Signup date
  • Contract start date
  • Renewal date
  • Contract value

You can pass any values from variables that are already available in your application, including industry-specific metadata fields. You can also use combinations of metadata rules to create segments in Pendo and deliver contextual guides to target audiences. If you’ve completed the Pendo Installation Workbook, refer to Basic Installation for the fields your team expects to capture.

Note: The total size of the metadata passed during initialization must be less than 64kb. To determine the size, convert the parameters passed topendo.initialize()into JSON; that JSON file must be smaller than 64kb. This data is compressed by the agent and sent to Pendo. If the compressed JSON data is greater than 64kb it will be dropped by the agent.

For more information about metadata in Pendo, see Visitor and Account metadata.

Step 2: Install Pendo on your application

Installing Pendo involves the following:

1. Run the install script (“snippet”) to download the agent (pendo.js).
2. Run the initialize method in the install script on the pendo.js file to start the agent.
3. If you’re also a Feedback customer, Pendo Professional Services enables Feedback during install. If you’re not seeing Feedback in your subscription, contact Pendo Support.

If you’re an existing Engage customer switching on Feedback for the first time, see the Developer's guide to installing Feedback, which provides instructions for new Feedback customers.

The install script contains the code that allows Pendo to launch in your application. Once the agent is running in the application, Pendo collects analytics and allows you to access previously stored data, retrospectively.

The code must be present on any page that you want to deliver guides on, to collect analytics from, or to gather feedback. Thus, Pendo recommends that you place the code in a common area of your HTML so that it's automatically included on all pages of your app. You must also ensure that the code is included in any iframes you might have so that Pendo can properly collect feedback, track analytics, and serve guides.

To get and install the snippet – the code needed to serve Pendo Guides, Analytics, and Feedback:

1. Navigate to app.pendo.io in your browser.
2. Ensure you’re on the right subscription in the Subscriptions tab in the left-side navigation.
3. Open Settings > Subscription Settings from the bottom-right of the left-side menu.
4. Open the Applications tab
5. Select Install Settings.
6. Copy the code into a text editor and edit it.
7. Set the field names within the Visitor and Account object of the install script.
8. Populate the code with metadata and tags in your app.
9. Copy the code to your app code by pasting it into the Head tag of your HTML template, which is present on all pages of your application.

Once the code is live, Pendo is installed in your app.

Step 3: Verify the installation

Verification is carried out where the code was installed and where the end-user is authenticated (unless anonymous users are used). There are two ways to check the status of the installation, and that metadata is set for a particular user:

• • Review Pendo raw events and data mappings in App Settings.
  • Use the pendo.validateEnvironment()command in the Browser Developer Console.

Review in App Settings

1. Navigate to Settings > Subscription Settings.
2. Open the Applications tab.
3. Find and open the relevant app from your Applications list (which should indicate that the app is installed).
4. Select the Raw Events tab to open a list of raw events captured by the agent.
5. Select an event to show the code and metadata collected by that event. The event should indicate:
   • The Visitor and Account IDs of the user who generated it.
   • The browser session metadata (additional metadata isn't stored in raw events).
   • Navigate to Settings > Data Mappings.
   • Check whether the data listed in Pendo matches the data sent by the agent.

If an agent metadata field is incorrectly populated, it can only be updated the next time Pendo initializes. These fields can’t be modified manually. They can only be changed by modifying the install script or passing an update visitor function.

Note: It can take up to two hours to receive initial data.

Review the Browser Developer Console

Visit the Pendo Academy for a video with step-by-step instructions on how to verify your Pendo installation. If you're on our US domain, visit the US Pendo Academy. If you're on our EU domain, visit the EU Pendo Academy.

1. Open your application in a Chrome browser (preferred) and sign into your app.
2. Open the browser's developer console by right-clicking on the page and selecting Inspect.
3. Select the Console tab.
4. Enter pendo.validateEnvironment() into the console.
5. Select Enter on your keyboard to return your metadata – the values you supplied in your Snippet.
6. Check that the visitor and account metadata is accurate.

This information tells you whether you successfully mapped the data to Pendo.

If you get an error saying that "Pendo is not defined", the snippet was either not successfully included or executed in your code.

Additional Configurations

You have further configuration options available to you, listed below.

Prevent Pendo from collecting text

Pendo doesn't collect user-entered text, like input fields or text boxes, unless it’s configured by a Pendo user with Click Event Properties.

Pendo does collect text from the DOM to make tagging easier. For example, features or guides can tag elements in the UI targeting element:contains("UI Text"). If sensitive information is displayed in the DOM, it might be collected, completely or partially, by raw events when recording the hierarchy of an element.

If you need to prevent text collection, you can either:

• [Recommended] Contact Pendo Support to request that text collection be disabled.
• Add an extra line with excludeAllText:true to your initialization. Pendo can’t reverse this for you.

For additional agent customizations, see our developer docs.

Example of modified snippet

pendo.initialize({
    visitor: {
        id:              'VISITOR-UNIQUE-ID'
    },
    account: {
        id:           'ACCOUNT-UNIQUE-ID'
    },
    excludeAllText: true 
 });

Block Pendo guides in the snippet

If you know that you're not going to use guides at all, you can set the disableGuides:trueflag, which prevents the Pendo agent from making outbound requests to see if there are guides available. If a Pendo user builds and publishes a guide it can't load in your app

Example of modified snippet:

pendo.initialize({
    visitor: {
        id:              'VISITOR-UNIQUE-ID'
    },
    account: {
        id:           'ACCOUNT-UNIQUE-ID'
    },
    disableGuides: true 
 });

It’s technically possible for a user to change this setting and load guides in the console after initializing. Doing this manually requires significant technical knowledge of Pendo and your application. In this unlikely scenario, the only guide content that can load are published guides in the app that meet all of the user and application-specific targeting criteria.

Troubleshooting

My data isn't appearing in Pendo

Confirm that your application key has been included in the snippet. If you copy your snippet from your Install Settings page, the application key is already included. If you pulled the snippet from somewhere else, confirm the application key is in your snippet.

There are data syntax rules you must follow for Pendo to receive all of your data:

• • If you don’t have data for a field, omit sending that field.
  • If you want to delete the existing value for a field, send null.
  • Don’t include a space in custom fields.
  • Fields must start with a letter or an underscore, and can include any combination of letters, numbers, and an underscore.

For more information about metadata in Pendo, see Visitor and Account metadata.

Note: Most data used for analytics is batch aggregated every hour, and can take up to 15 minutes past the top of the hour to appear in the Pendo UI. 

Message: No Logged In Users

During setup, the message "No Logged In Users" means that Pendo is receiving pages and features usage data with no user-identifying information. You can still use Pendo without identified users but this reduces the functionality. For more information about unidentified users, see Anonymous Visitors.

The Visitor or Account ID parameters in the Snippet could be causing the issue. Either the data isn't being passed or it’s structured incorrectly.

Code template:

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

Code example with Metadata

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
}

Code example 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}