# Pendo Web SDK

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

## Installation

Install the package:

```bash
npm install @pendo/web-sdk
```

## Usage

Import the package into your application code and create the web SDK using your own settings:

```javascript
import { initialize, TextCapture } from '@pendo/web-sdk';
import pendoConfig from '../pendo.config.json';

const pendo = await initialize({
    publicAppId: 'YOUR_PUBLIC_APP_ID',
    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 web SDK and has access to all public functions found in the public function [documentation pages](https://web-sdk.pendo.io/public/core).

### Parameters

| key | required? | type | description |
| --- | --------- | ---- | ----------  |
| publicAppId | required | string | Your specific application `publicAppId` 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', 'gov']. |
| 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 web SDK. More information can be found [below](#plugins). |
| config | optional | object | An object that contains the entire server configuration for your application may be passed. By default, the web SDK will download the latest configuration upon initialization if not passed in. More information can be found [below](#config). |
| assets | optional | object | Configuration for the host and path to support including the web SDK's static assets in your application code. More information can be found [below](#assets). |

> **Note**: In addition to the above parameters, any additional options that can normally be provided to `pendo.initialize` may be included. See [our documentation](https://agent.pendo.io/config/) for the full list of options that can be passed to `initialize`.

### Additional Information

#### Assets

During runtime, the web SDK occassionally needs to download additional script files to provide functionality that is not bundled into the web SDK. 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 web SDK 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 guide code blocks. The designer will now try to download its startup files from your set asset host and path as well so you must use the [designer](#cli) command from the CLI to regularly download those files. Be aware that the designer plugin files receive updates regularly, sometimes weekly, and some of those changes are not backwards compatible, meaning if this file is not kept up to date that the designer might not operate correctly. This option is useful when including the web SDK in things like browser extensions that have strict rules around remote code execution. Defaults to false. |

The [CLI](#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 web SDK 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 web SDK will use the provided publicAppId 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](#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 web SDK. 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)
- Capture Console Logs (ConsoleCapture)
- Capture Network Logs (NetworkCapture)

## 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 the web SDK into, in order to understand how your customers use your extension, you will need to follow a few steps to ensure that the web SDK 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](#cli) to copy the web SDK's static files, using the `copy` command, into a folder that will be included in your packaged extension (ensure this is run each time you update your web SDK version).
1. Use the [CLI](#cli) to download copies of the designer plugin files, using the `designer` command, into your packaged extension (ensure this runs each time you rebuild your extension to ensure you have the latest designer code).
1. 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)
1. Initialize Pendo on the desired page or pages with any desired options, making sure to use the [assets option](#assets).
1. The "host" field will need to be the extension resource url. You can use a code snippet like this to properly retrieve that url: `chrome.runtime.getURL('').slice(0, -1)`
1. 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`.
1. The "localOnly" field will need to be set `true` in order to disable remote code execution and allow the designer to launch using your extension's files.

We have created an [example extension](https://github.com/pendo-io/chrome-mv3-example) to show what a basic setup might look like.

## CLI

The Pendo package includes a CLI tool to be able to simplify a few actions providing greater control of the web SDK in your application. Once you have installed `@pendo/web-sdk` 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, copy, or designer 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:

```json
"pendo-build": "pendo copy --dest=public && pendo config --publicAppId={{PUBLICAPPID}} --env={{YOUR_ENV}} && pendo designer --dest=public --env={{YOUR_ENV}}",
```

### Help

```bash
Usage: pendo <command>

CLI for @pendo/web-sdk to assist in integrating the web SDK into your application.

Commands:
    pendo config            download a new web SDK configuration file for your application
    pendo copy              copy static assets for the web SDK 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 web SDK

Documentation for the Pendo Web SDK can be found at:
    https://web-sdk.pendo.io
```

### Download Config

```bash
Usage: pendo config --publicAppId=<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:
    --publicAppId required, the public app ID 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 --publicAppId=dd753dfd-ac99-4c5c-48ad-6eb18190cf77 --env=io --output=pendo.config.json
```

### Copy Static Assets

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

Copy static web SDK 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/web-sdk dist folder, defaults to "./node_modules/@pendo/web-sdk/dist"

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

### Download Designer Plugins

```bash
Usage: pendo designer --env=<subscription_environment> --dest=<destination_folder>

Download new copies of the plugin files needed for the Visual Design Studio to launch and operate correctly. This does not download the html files used in the frames, those will still be loaded from Pendo domains.

Options:
    --env         required, the Pendo environment for your subscription, allowed environments: [${environments}]
    --dest        required, the destination folder to copy the static files to, usually the "public" folder of your application

Examples:
    Download and save the designer files from the default US environment
    $ pendo designer --env=io --dest=public`
```