@pendo/agent 2.271.0 → 2.273.0

package/README.md

@@ -53,7 +53,7 @@ The object returned by calling `initialize` is the same as a snippet install of
 | 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](#config). |
 | 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](#assets). |
 
-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`.
+> **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
 
@@ -65,15 +65,19 @@ During runtime, the Pendo Agent occassionally needs to download additional scrip
 | ---- | ---- | ----------- |
 | 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. Defaults to false. |
+| 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](#cli) below can be used to copy these static files from this package to your application code.
+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 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](#cli) below can be used to easily download and save a new version of that configuration.
+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
 
@@ -87,10 +91,27 @@ The current list of available plugins and their export names are:
 - 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](#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).
+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. It will probably look like this: `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 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:
+
+```json
+"pendo-build": "pendo copy --dest=public && pendo config --apiKey={{APIKEY}} --env={{YOUR_ENV}}",
+```
+
 ### Help
 
 ```bash