Components of the install script

Implementing Pendo directly into your application involves the following key components:

• The Pendo agent, which is typically hosted on the server (Pendo) side. This is what delivers Pendo.
• The install script that you add to your application (client-side) code. The install script consists of:
  • A call for the Pendo agent.
  • The app (API) key for your account.
  • The initialize method, which activates the Pendo agent and defines IDs and metadata.

This article summarizes these components and provides a brief technical overview of how they work. For guidance on the main 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 instructions on how to install and configure Pendo using the install script, see the Developer's guide to implementing Pendo using the install script.

How it works

Your developers must insert the install script into the page header. All pieces of the install script must be present on every page that you want to collect data from. This includes a call for the Pendo agent, an app (API) key to identify your account, and an initialize method to activate the Pendo agent and define IDs and metadata.

Mobile developers add the SDK to your app, initialize Pendo when your app loads, and identify the visitor when you're ready to collect data and display guides.

After installation and configuration through the install script, it can take up to an hour to receive that data. Most data used for analytics is batch-aggregated every hour. It can take up to 15 minutes past the top of the hour to appear in Pendo. 

Pendo agent

Depending on your subscription, the Pendo agent is a 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 on the client side.

Install script ("snippet")

The install script 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 app 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.

The install script and the initialize method must be present on all pages of your website for the Pendo 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 are then applied to all frames.

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

App (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 app (API) key that’s included in the code block. The app key identifies data sent to Pendo to be associated with the specific application within the subscription. 

This isn't a secret key and is unrelated to security and privacy. The app key is only used to send data to your Pendo subscription and doesn't provide read access to any of your data.

To find your app key:

1. Go to Settings > Subscription Settings.
2. Open the Applications tab.
3. Choose your application from the list.

The app key is already in the application details of your subscription. You can find it in App Details or at the bottom of your install script in Install Settings.

Initialize method

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, 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 more information, see Auto-tagging in Feedback.

The first code block lets you find visitors and accounts so that you can group analytics, target guides using information from your application variables (like from a User object or similar), and automatically tag Feedback requests.

All variables passed into the install script must be defined before pendo.initalize() is run. Pendo doesn't initialize correctly if all of the variables passed to Pendo aren't present at initialization. For more information, see Conditionally Initialize 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-id-goes-here'   // Required if user is signed in. Should be human-readable (for example, email or username) because it's used in Pendo reports.
        // is_paying:    // Recommended if using Pendo Feedback
        // 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-id-goes-here' // Highly recommended; required if using Pendo Feedback. Should be human-readable (for example, company name) because it's used in Pendo reports.
        // 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.
    }
});