Pendo Agent

This package is for Pendo customers who want to host the Pendo agent on their own infrastructure.

Installation

Install the package:

npm install @pendo/agent

Usage

Import the package into your application code and create the Pendo agent using your own settings:

import { initialize, TextCapture } from '@pendo/agent';
import pendoConfig from '../pendo.config.json';

const pendo = await initialize({
    apiKey: 'YOUR_API_KEY',
    env: 'YOUR_PENDO_ENVIRONMENT',
    visitor: {
        id: 'THE_VISITOR_ID'
    },
    account: {
        id: 'THE_ACCOUNT_ID'
    },
    globalKey: 'pendo',
    plugins: [ TextCapture ],
    config: pendoConfig,
    assets: {
        host: 'https://mycdn.com',
        path: 'public',
        localOnly: false
    }
});

The object returned by calling initialize is the same as a snippet install of the Pendo Agent and has access to all public functions found in the public function documentation pages.

Parameters

key	required?	type	description
apiKey	required	string	Your specific application apiKey can be found by going to the application details page in the Pendo App for your application. It will be a 32-digit code that identifies that application and connects it to Pendo.
env	required	string	The environment that your Pendo subscription resides in. io is the default US environment and environments other than that can be found in the url that you use to access Pendo (e.g. app.eu.pendo.io). One of: ['io', 'eu', 'jpn', 'us1', 'au'].
visitor	optional	object	The visitor information for the current user of your application. This includes the id and any other metadata you want attached to the visitor. If not provided the visitor will be treated as an anonymous visitor.
account	optional	object	The account information for the current user of your application if applicable. If not provided the visitor will not be assigned to an account.
globalKey	optional	string	The key where you would like the global pendo object to be stored after initialization. By default this will be stored on window.pendo but this allows it to change to a different name if desired.
plugins	optional	array	A list of imported plugins to enable additional features in the Pendo Agent. More information can be found below.
config	optional	object	An object that contains the entire server configuration for your application may be passed. By default, the Agent will download the latest configuration upon initialization if not passed in. More information can be found below.
assets	optional	object	Configuration for the host and path to support including Agent static assets in your application code. More information can be found below.

Note: In addition to the above parameters, any additional options that can normally be provided to pendo.initialize may be included. See our documentation for the full list of options that can be passed to initialize.

Additional Information

Assets

During runtime, the Pendo Agent occassionally needs to download additional script files to provide functionality that is not bundled into the Agent. This functionality is mostly meant for admins that need to design and preview guides as well as debug Pendo within their application. By default the Agent in this package will download those assets from Pendo's CDN when needed. If you would prefer to include these scripts in your application code instead of downloading them from Pendo at runtime, you can provide a host and path to where these files can be loaded from. The host can be your own CDN, domain, extension runtime location, or can even be a relative url if the host is empty.

name	type	description
host	string	domain host for where your assets will be hosted, if this value is an empty string, the assets will be loaded using a relative url.
path	string	additional path to add to the url before the filename. Useful if your assets are served from a path of public or something similar. If left blank, no additional path will be added to the urls.
localOnly	boolean	serve all possible assets from the given asset host. This will prevent the use of things that are unable to be self served, like the Visual Design Studio and guide code blocks. To be able to use guide code blocks you will need to allow remote scripts. The designer will not launch at all and will print a log message instead if this is set to true. This option is useful when including the Agent in things like browser extensions that have strict rules around remote code execution but will need to be disabled in local builds to utilize the designer. Defaults to false.

The CLI can be used to copy these static files from this package to your application code.

Note: If you are using the static assets in this manner, every time you upgrade agent versions, you will need to make sure that you copy a fresh version of the static files to maintain version compatibility.

Config

By default, the Pendo Agent will use the provided apiKey and environment to download the latest version of the configuration for that application. This includes what settings have been enabled/disabled as well as any configured historical metadata fields and feature event properties. This ensures that the latest configuration is always being used without you requiring to redeploy your application. If you would prefer to not download the latest configuration and instead use a local static version, you can pass the JSON object to the config property instead. This will mean however, that to take advantage of any changes made to settings in the Pendo UI or to your historical metadata fields and feature event properties you will need to download a new version of the config and redeploy your application.

The CLI can be used to easily download and save a new version of that configuration.

Note: If you are using the a local version of the config file you will need to download a new version of the file regularly to ensure your settings are up to date with your application and subscription.

Plugins

Pendo has a subset of features that need to be manually enabled or are part of separate purchases. By default the functionality for these features is not included in the Agent. When using this package when there is a need to enable these features requires passing in the desired plugins. These plugins are available to be imported just like the initialize function and can then be passed directly into an array using the plugins property. Any plugin that also requires an additional purchase or package can still be included but will not function without configuration inside of your subscription.

The current list of available plugins and their export names are:

• Text Capture (TextCapture)
• Feedback (Feedback)
• Session Replay (Replay)
• Guide Logic (GuideMarkdown)
• Voice of the Customer Portal (VocPortal)

Manifest V3 Extensions

Writing an extension that adheres to the strict requirements of Manifest V3 can sometimes be challenging. If you have a Manifest V3 extension that you would like to install Pendo into, in order to understand how your customers use your extension, you will need to follow a few steps to ensure that the Pendo agent does not fetch any remote code. Using this npm package is the most straightforward way to include all Pendo assets in your extension.

1. Use the CLI to copy the agent static files into a folder that will be included in your packaged extension (ensure this is run each time you update your agent version).
2. Update the manifest.json file to include those copied files in your "web_accessible_resources". The files copied are: "guide.css", "pendo.debugger.min.js", "debugger-plugin.min.js", "pendo.preview.min.js", "replay.worker.min.js" (the worker is only needed if using Pendo Session Replay)
3. Initialize Pendo on the desired page or pages with any desired options, making sure to use the assets option.
4. The "host" field will need to be the extension resource url. It will probably look like this: chrome.runtime.getURL('').slice(0, -1)
5. The "path" field will need to be set to whatever the folder the assets were copied to. If they are in the root of your packaged extension this can be an empty string but if, for example, those assets are in a folder called pendo, the "path" would just be pendo.
6. The "localOnly" field will need to be set true in your final packaged extension. This does mean that you will not be able to launch the designer in the store version of your extension however. In order to utilize Visual Design Studio you will need to use a dev unpackaged version of your extension where "localOnly" is either not set or set to false.

CLI

The Pendo package includes a CLI tool to be able to simplify a few actions providing greater control of the Pendo Agent in your application. Once you have installed @pendo/agent in your application, you will have access to the pendo script from your terminal (you can also use a tool like npx to make use of the pendo script without installing the package if desired by using npx pendo). The usage of this script can be found below or by typing pendo or pendo help into your terminal where the package is installed:

Note: If the config and copy commands are being used by your application, you might want to use those as part of your regular build process to ensure that you always maintain up to date versions of your config and of the static assets. For example, you could add a script to your package.json like below that you then call as part of your build:

"pendo-build": "pendo copy --dest=public && pendo config --apiKey={{APIKEY}} --env={{YOUR_ENV}}",

Help

Usage: pendo <command>

CLI for @pendo/agent to assist in integrating the Pendo Agent into your application.

Commands:
    pendo config            download a new Pendo Agent configuration file for your application
    pendo copy              copy static assets for the Pendo Agent to a static folder
    pendo help              provide help for how to use the Pendo CLI
    pendo help <command>    search for help on a specific <command>
    pendo version           show the current version of the Pendo Agent

Documentation for the Pendo Agent can be found at:
    https://agent.pendo.io

Download Config

Usage: pendo config --apiKey=<application_api_key> --env=<subscription_environment> [--output=<filename>]

Download a new configuration file for a specific application built from the most recent subscription and application settings.

Options:
    --apiKey      required, the api key for your Pendo application, found in the application settings page in the Pendo app
    --env         required, the Pendo environment for your subscription, allowed environments: [${environments}]
    --output      optional, the name of where to save the config, defaults to "pendo.config.json"

Examples:
    Download and save the configuration file from the default US environment
    $ pendo config --apiKey=dd753dfd-ac99-4c5c-48ad-6eb18190cf77 --env=io --output=pendo.config.json

Copy Static Assets

Usage: pendo copy --dest=<destination_folder> [--src=<node_module_folder>]

Copy static Pendo Agent files into a local folder for self hosting. Includes guide styles, scripts for the debugger and preview mode, and the worker file for Session Replay.

Options:
    --dest      required, the destination folder to copy the static files to, usually the "public" folder of your application
    --src       optional, the location of the @pendo/agent dist folder, defaults to "./node_modules/@pendo/agent/dist"

Examples:
    Copy from the default location to your public folder
    $ pendo copy --dest=public