Developer's guide to implementing Pendo using the install script

This article is intended for developers. It summarizes the technical instructions for installing and configuring Pendo.

• For guidance on the overall steps for implementing Pendo, from choosing IDs and metadata to adding users and getting started with Pendo, see Plan your direct web implementation of Pendo using the install script.
• For a summary of the components of the install script and a brief technical overview of how it works, see Components of the install script.

Installation and configuration through the install script is the only required technical part of integrating Pendo into your application. No other engineering resources are required. After Pendo is set up, the agent provides Pendo for users of your application. For documentation about the Pendo agent and API Developer, see Engage API.

Data requirements

Pendo requires some information in a particular format to run effectively. This section summarizes specific data needs for a direct implementation of Pendo using the install script. 

If you're also a Feedback customer, we recommend that you optimize the code for the data needs of Pendo Feedback as well, which includes: globally unique Visitor IDs, email metadata, and Account IDs. For more information on what’s needed for Pendo Feedback, see the Configure for Feedback.

Unique Visitor IDs

Pendo requires globally unique Visitor IDs 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 Choose IDs and metadata.

Syntax for custom metadata values

Supported syntax for metadata values includes letters, numbers, and underscores (_).

A custom key value must start with a letter or an underscore. No other types of syntax are supported for the starting character. For example, if you have a key such as "300", you need to change it to "_300". If this syntax isn't followed, you can't create segments or run reports using those custom fields.

Custom language metadata

The default language metadata field in Pendo is collected from the visitor's browser settings by the Pendo agent. Custom visitor metadata can be passed through by the agent or through integrations such as Salesforce. Custom language metadata fields must use a name other than language since this name is reserved for browser language metadata and can't be replaced.

You can specify a different metadata field in your localization settings through Settings > Subscription Settings > Localization Settings.

Get started

A direct implementation of Pendo involves running the install script code from your application to call the Pendo agent (pendo.js), which allows Pendo to launch in your application, and then running the initialize method in the install script on the pendo.js file to start the Pendo agent. After the agent is running in the application, Pendo collects analytics and allows you to access previously stored data, retrospectively.

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 Pendo customer switching on Feedback for the first time, see Configure for Feedback, which provides instructions for new Feedback customers.

First, you must adjust the install script for your particular subscription. To find the install script in Pendo:

1. Open Settings > Subscription Settings from the bottom of the left-side menu.
2. Open the Applications tab and select Install Settings.
3. Copy the install script code into a text editor to adjust it.
4. Complete the steps for installing and configuring Pendo outlined in the Process overview.

If you experience any issues, see Troubleshoot installation for a Pendo implementation that uses the install script.

Process overview

Implementing Pendo using the install script involves inserting Pendo's JavaScript code into the front-end of your web application. This is broadly a three-step process:

1. Define visitor and account metadata by editing the install script code.
   • Set the field names within the Visitor and Account objects of the install script.
   • Populate the install script initialize method with metadata and tags in your application.
2. Install and initialize Pendo by copying the edited install script code into a common area of your HTML so that it's automatically included in all pages of your application.
3. Verify the installation either in App Settings through the Pendo UI or using the pendo.validateEnvironment() command in the Browser Developer Console.

 

Note: The install script is commonly referred to as “the snippet”. It 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 Components of the install script.

Step 1. Define visitor and account IDs and metadata

This section covers the process of, and technical considerations associated with, identifying IDs and metadata by adjusting the install script code. For guidance on deciding what to define, see Choose IDs and metadata.

Visitor IDs, Account IDs, and metadata are defined in the install script. Pendo offers an install script template with your subscription, which includes the code block needed for Pendo to serve guides, collect analytics, and deliver the Feedback module. You can find this in Settings > Subscription settings > Applications > Install Settings.

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

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 Configure for Feedback.

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 Configure for Feedback

Visitor and Account IDs

We strongly recommend setting up both Visitor and Account IDs now. These should be defined based on the guidelines outlined in Choose IDs and metadata. Below are some key technical considerations for configuring IDs:

IDs mustn't change

Visitor and Account IDs mustn't change after implementing Pendo. If Visitor and Account IDs mappings change after implementation, new visitor and account records are created in Pendo with no product usage or guide view history, resulting in anomalies in analytics and segmentation, and repeat guide experiences.

IDs should be human-readable

Visitor and Account IDs should already be defined as part of the process for choosing IDs and metadata during the implementation planning phase. These guidelines highlight the need for recognizable IDs, such as email address for visitors and company name for accounts. Visitor and Account IDs using strings of random characters avoid duplication, but make it difficult to use Pendo reports, create segments, and integrate with the rest of your tech stack. You should also avoid using \ or " in Visitor and Account IDs.

IDs must be globally unique

Visitor IDs must be unique for each end-user and Account IDs must be unique for each account. If any of Visitor and Account IDs are duplicated, data from multiple sources are aggregated under a single ID, skewing your analytics and reducing your ability to target guides effectively.

Visitor IDs must represent only one end-user throughout the entire customer journey and across applications. 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:

• 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 multiple environments for development and testing.

Visit the Pendo Academy for a video on avoiding and resolving ID collisions. 

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

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 select the metadata you want to capture before installing and configuring Pendo. You can also add metadata after the initial installation, which updates 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. For more examples, see Choose IDs and metadata. You can send dates, integers, floats, booleans, lists, and strings. Pendo doesn’t support objects. See our article on Metadata and data mappings for more information.

If you’re a Feedback customer, you can also configure auto-tagging. For more information, see the Configure for Feedback and Auto-tagging in Feedback.

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 Configure visitor and account metadata and Choose IDs and metadata. 

Step 2. Install and initialize Pendo on your application

After adjusting the install script template to define your IDs and metadata, copy the edited code into your application code. 

The code must be present on any page that you want to deliver guides on, to collect analytics from, or to gather feedback from. 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. Typically, this is the Head tag of your HTML template, which is present on all pages of your application. 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.

Step 3. Verify the installation

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

• Review Pendo raw events and metadata 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 > Metadata.
   • 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. 

Open your application in a Chrome browser (preferred) and sign into your app.

1. Open the browser's developer console by right-clicking on the page and selecting Inspect.
2. Select the Console tab.
3. Enter pendo.validateEnvironment() into the console.
4. Select Enter on your keyboard to return your metadata – the values you supplied in your Snippet.
5. 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.

Pendo performance

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 and compressed to approximately 100KB and loads asynchronously.

Data is securely transmitted through TLS 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 2KB.

Other configurations

If you’re already a Pendo customer, and would like to add Pendo Feedback to your product, see Configure for Feedback, which provides instructions for new Feedback customers.

You also have further development options. You can optimize Pendo by adding custom HTML attributes for tagging and tracking events. For information, see Custom 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 contact a Pendo representative for help with integrations in your subscription after completing the Pendo install.

There are some scenarios where you might need help with your installation. A Pendo representative can talk through your concerns and assist with your installation.

You might need direct support with your installation if you have any of these requirements.

• Non-standard web snippet installations
• Security concerns
• Custom integrations
• Segment.io or Google Tag Manager installations
• API integrations or webhooks

Frequently asked questions

Where do I install the install script ("snippet")?

Everywhere. The Pendo needs to be installed on every page. If your app uses iframes, install within each iframe.

Who are your unknown users?

Unknown or anonymous users are those who don’t sign in to your app. You can enable analytics on your unknown users and allow them to see guides in your subscription settings.

How do I hide data that I don't want to see?

Pendo can hide data based on Server or Host Domain, IP Address, Visitor ID, or Account ID using include and exclude lists. For more information, see Exclude and Include Lists.

Can I host the agent locally?

The install script pulls in pendo.js, which contains the Pendo agent code. pendo.js can be downloaded and hosted by your application if you don't 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-premises?

The Pendo agent can be hosted locally and included in on-premises applications. Pendo currently only hosts and processes data in the cloud, so this still requires a connection to the internet and you might need to allow traffic to Pendo servers from your network. Broadly, guides are inbound traffic and analytics are outbound. For more information, see Hostname list for visitors in restricted network environments and Hostname list for Pendo subscriptions in restricted network environments.