Agent API

The Agent API allows developers to interact with the Pendo Agent, which collects user interactions and displays in-app messages in your application. The default installation provides everything you need to capture browser events and deliver guides to your end users.

Installation

To make use of the Agent API, Pendo must be correctly installed and initialized in your application. There are two primary methods shown below:

1. Using the Install Script (Snippet)

   The install script or "snippet" fetches the JavaScript agent and creates the global pendo object on a page. Next, the agent must be initialized with configuration and visitor information. For a more detailed guide to installation, see the Pendo Help Center. This installation method allows you to easily control the Agent's configuration and version through the Pendo UI without needing to redeploy your application.

2. Using the NPM Package

   You can also install the Pendo Agent via npm. Install the package:

   npm install @pendo/agent

   Then, initialize the agent in your application following the README. Since the Agent will be bundled with your application when installed through npm, updating to a new version of the Agent requires deploying a new version of your application.

Agent Functionality

Additional functions allow you to control the agent and the data it collects. For example, you can exclude text collection, programmatically change page URLs captured in events, delay guide loading, and more to customize your installation. Advanced functionality such as sending track events, debugging, and programmatically activating guides requires interaction with the Agent API within your application JavaScript.

caution

Any undocumented functionality you encounter while inspecting the pendo namespace should be considered either internal or experimental and is subject to change. Do not rely on undocumented functionality.

Agent Build Differences

We offer three builds of the agent to support various browser environments. New installations will use the Standards version by default, which uses modern browser APIs to improve security and performance. This is the recommended version, but XHR and JSONP builds are also available to support legacy browsers and guides. The major differences between the builds are listed below.

	Standards	XHR	JSONP
Best for	Environments using modern browsers	Environments that need to support some legacy browsers	Environments that primarily use legacy browsers
Security compliance	Most secure request format and unlikely to be flagged by security scanning tools	Most secure request format, though polyfills may raise false negatives in security scanning tools	Potentially vulnerable from script element request and polyfills may raise false negatives in security scanning tools
Guide load method	JSON data via XHR request	JSON data via XHR request	JSONP request to evaluate JavaScript
CSP permissions	connect-src	connect-src	script-src
IE support	None	IE 9 and up	All IE versions
P1 guide support	Limited support	Full support	Full support
Guide code blocks	Only code blocks without templates	All code blocks	All code blocks

Agent Updates

The Agent typically releases a new version each week. During development, each change must pass a full suite of automated testing as well as developer testing. Releases first reach the beta release track, then after a few days move to the stable track. Any issues discovered during the beta process are addressed with patch updates. Updates to each channel can be found here, and you can subscribe to the RSS feed to be notified when the beta or stable version changes.

We recommend using the stable version on production environments to ensure access to the latest security and performance improvements. Use the beta version on staging environments to identify any environment-specific issues before they reach production. Information about changing your Agent version to a specific track or pinning to a specific version can be found here. Release notes for each version are available here.

Note on versioning

• Major versions (1.x.x) are very rare and represent a breaking change in guide structure. A major update will be announced early and often to allow for migration planning.
• Minor versions (x.1.x) are our most common update. Each minor version represents the weekly release cycle detailed above. They are announced via RSS feeds and documented on the releases page. These versions generally include new features.
• Patch versions (x.x.1) are released as needed to fix issues found on current beta/stable agent versions. Patches are generally reverts or quick fixes to recently introduced errors. New features will not be added to patch versions, and all patch fixes are carried over to the next minor version.

Debugging

For additional troubleshooting, you can use our debugging tool by running pendo.enableDebugging() in the console. A full guide on what you can do with the debugger can be found here.