Developer's Guide To Installing the Pendo Snippet – Pendo Help Center

Overview

Pendo captures product usage insights, user feedback, and lets you communicate in-app to onboard, educate, and guide users to value. Pendo Guidance and Tracking is completely codeless, no engineering resources are required. However, we need engineers to install the Agent and initialize Pendo. Information about Pendo and the Pendo installation process is available in the Installation Planning article. We suggest your Pendo Champion fill out the Pendo Installation Workbook to share the information you'll need to complete the install. With preparation the technical installation of the Pendo Snippet is straightforward.

Our Agent is the only technical piece of the initial Pendo installation. Once the Agent is properly installed anyone can use Pendo. The Agent tracks a Visitor’s events, like page loads and feature clicks, loads Guides, and captures session metadata. Additional development may be done later to optimize and expand the use of Pendo, for example adding custom HTML attributes for tagging or Track Events. Pendo also has integrations with other popular CRM, analytics, and collaboration tools. The scope of integrations ranges from native integrations with a codeless installation wizard to custom development and will not be covered in this article. Check our Integrations articles for help with our popular integrations or reach out to a Pendo representative for help with integrations in your subscription after completing the Snippet install.

Installation Overview and Demonstration - Runtime: 6:24

The Agent

The installation of the Pendo Agent is made up of two pieces, the Snippet and the Initialization. The Snippet is a short Javascript function that adds the Pendo.js file to the window. The Initialization identifies the user with Visitor and Account metadata. Both pieces of the installation must be present on all pages of your website, if you have a single page application you only need to initialize once per session. Multi-page apps may need to initialize on every page, not just the login page, to initialize Pendo if there's a hard refresh on a page after login.

Typically Pendo is run after a Visitor is identified. Only initialize Pendo without a Visitor ID if you are deliberately trying to track anonymous Visitors. Anonymous Visitors are tracked with cookies and the same user could easily count as multiple Visitors across multiple sessions. Anonymous Visitors will count towards the subscription's MAU total. Contact your Sales Representative or Account Manager to understand the impact anonymous Visitors will have on your subscription billing.

The Snippet

The Snippet code block loads Pendo as a library that will make our functions available at the window level. The script also passes through the subscription API key. The API key is included in the Snippet provided on the Install page or in your App Settings. The API key maps the data the Agent collects to your app subscription in Pendo.

Note: The existence of the Snippet does not equate to tracking taking place. The Snippet must be initialized in order to enable tracking.

The Initialization

The Pendo Agent must be initialized to track usage and to deliver guides. The initialization is where you customize the metadata that you provide Pendo. Pendo users will be able to segment Visitors and Accounts in analytics and target Guides using this metadata. The initialization must run on every window reload after a Visitor is authenticated or in every frame, if your site has iframes.

The Visitor ID and Account ID values should not be changed after installation. Only the Visitor and Account ID are stored in Raw Events. Other metadata may be added after the initial installation and will update to the Visitor and Account details in Pendo. If the Visitor or Account ID values change after installation, new Visitor or Account records will be created in Pendo with no product usage or Guide view history. This will result in anomalies in analytics and segmentation and will repeat Guide experiences.

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' // 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.
    }
});

We provide the initialization code block. Your team must determine the appropriate values to pass as the Visitor and Account ID and additional metadata. The Visitor ID must represent one person through their entire customer journey in your various products. Consensus on this ID between your Product and Engineering team is crucial. If you’re worried that IDs between your environments, dev or staging, will collide you can append an identifier for the environment to the ID using a prefix or suffix. Methods for identifying Visitors in different environments are described in Pendo in Development and Testing. Identifying Visitors in different environments will be helpful later when excluding data.

The additional fields shown above are examples of other metadata you can send us about the Visitor or Account. You can send dates, integers, floats, booleans, and lists. Pendo does not support objects at this time. See our article on Data Mappings for more information.

If your Pendo Champion has filled out an 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 to pendo.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.

Verifying Your Install

There are two ways you can validate your installation.

Review Pendo Raw Events and Data Mappings in Settings
pendo.validateInstall() in Browser Developer Console

Review Pendo Raw Events and Data Mappings In Settings

Get to Raw Events by opening Subscription Settings in Settings.

Get to Data Mappings by opening Data Mappings in Settings.

Raw Events

Open App Details and click Raw Events.

Note: The App Details should indicate that the app is installed.

The Raw Events Page shows a list of Raw Events that have been captured by the Snippet. Clicking into an event will show the code and metadata collected by that event. The event should indicate the Visitor ID and Account ID of the user who generated the event. It may also indicate the browser session metadata. The additional metadata in the Snippet will not be stored in Raw Events.

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

Data Mappings

Review Data Mappings to validate that the data listed in Pendo matches the data sent by the Snippet. This metadata creates a new Visitor or updates an existing Visitor when a user initializes Pendo in your application. If an Agent metadata field is incorrectly populated, it can only be updated the next time Pendo initializes. These fields cannot be modified manually or through the API. They can only be changed by modifying the Snippet.

Browser Developer Console

You can validate your installation by entering the pendo.validateInstall() command in the Console. This should be done where the Snippet and Initialization have been installed and the user is authenticated, unless anonymous users are being used.

Sign in to your App
Open the Browser Developer Console
Enter pendo.validateInstall() into the Console
Visitor and Account metadata will be returned

Additional Configurations

How can I prevent Pendo from running in certain situations?

While Pendo does allow you to specify a staging domain for Guide testing, it does not provide any configurations to prevent initialization under certain conditions. If pendo.initialize() is called the Agent will track behavior and attempt to display Guides.

If you want to conditionally initialize Pendo we recommend using some logic to determine if Pendo should be initialized, either by feature flagging or by wrapping the initialize in an 'if' statement.

Some of our URLs contain sensitive data, how can we prevent Pendo from seeing that data?

Pendo pulls a Visitor's current URL in Raw Events and Page tagging. Specific details of the info in one Visitor's URL won't be accessible without looking at Raw Events or Untagged Pages. If the Page rules for Tagged Pages incorporate the sensitive data as a wildcard, those Page views will automatically group under the Tagged Page and won't be visible in Untagged Pages.

If you need to prevent this data from ever making it to Pendo we suggest using our URL Sanitization. Reach out to Support for more details.

How can we prevent Pendo from collecting text?

Pendo doesn't collect text input, like input fields or text boxes, unless it is configured by a Pendo user using Click Event Properties. However, we will 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 make be collected, completely or partially, by Raw Events when recording the hierarchy of an element.

If you need to prevent text collection, add an extra line with excludeAllText: true to your initialization.

For additional Agent customizations check our developer docs.

Example of Modified Snippet

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

Can I block Pendo guides in the snippet if we won't be using them?

If you know that you are not going to be using Guides at all, you can set the disableGuides:true flag, which will prevent the Pendo snippet from making outbound requests to see if there are guides available. If a Pendo user builds and publishes a guide it cannot load in your app.

Example of Modified Snippet

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

It is 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 may load are published guides in the app that meet all of the user and application-specific targeting criteria.

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 are 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 and Account IDs just like in the initialization.

Learn more about our Initialization and Identification functions.

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 by your application if you do not want it to be pulled from Pendo’s CDN.

For instructions on hosting the Agent reference Self-hosting the Pendo Agent.

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.
Fields must start with letter or underscore and can include any combination of letters, numbers, and an underscore.

Learn more about Visitor and Account metadata.

Note: Most data used for analytics 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 the pendo.js Agent. This Agent will check if the server hostname matches a Staging server rule and if it does it will load the Pendo object from pendo-staging.js instead of pendo.js.

No Logged In Users

During setup, the message "No Logged In Users" means that Pendo is receiving, pages and features usage data but there is no user identifying information. You can still use Pendo without identified users but the functionality will be greatly reduced.

Either the Visitor or Account ID parameters in the Snippet could be causing the issue. Either the data is not being passed or it is 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.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
}

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}

Why are my auto-tags not appearing in Pendo 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.

Learn more about auto-tagging in Feedback.