# Integrate Pendo with ThoughtSpot Embed

> For the complete documentation index, see [llms.txt](https://developers.thoughtspot.com/docs/llms.txt)

Source: https://developers.thoughtspot.com/docs/pendo-integration

# Integrate Pendo with ThoughtSpot Embed

To launch Pendo guides and analytics within your ThoughtSpot embed, you must integrate Pendo with your embed environment. This integration typically requires adding a custom JavaScript to enable product tours, feature announcements, and usage tracking within the embedded experience.

> **IMPORTANT:** By default, the third-party tool integration feature is disabled on ThoughtSpot instances. To enable this feature, contact ThoughtSpot Support. ThoughtSpot strongly recommends that you review your organization’s security guidelines and assess potential security risks associated with the injection of custom scripts and third-party tools. Malicious scripts introduce XSS risks and can compromise user data and application integrity. Both ThoughtSpot Support and the customer must explicitly approve and enable the integration to ensure that only vetted and trusted script URLs are allowed in the embed app.

## Before you begin

Pendo integration with ThoughtSpot embed requires the following:

-   Access to Pendo  
    If you do not have a Pendo account, you can [sign up for Pendo](https://app.pendo.io/register) and create a trial account.
    
-   Access to a ThoughtSpot instance. You need administrator privileges to enable Pendo integration.
    
-   Approval from ThoughtSpot Support for Pendo integration.
    
-   A publicly accessible domain to host your integration script.
    

## Step 1: Sign in to your Pendo Account

To integrate Pendo in your ThoughtSpot embed, you’ll require a script. Before creating your integration script:

1.  Sign in to your Pendo account.
    
2.  Identify the information you want to capture.
    
3.  Define visitors and accounts, and segment data.
    
4.  Review your existing Pendo implementation in your application to understand how you initialize Pendo (for example, using a React hook, vanilla JavaScript, or other methods).
    

The above information will be used as metadata in the Pendo install script. For more information, refer to the [Pendo Documentation](https://support.pendo.io/hc/en-us/articles/21326198721563-Choose-IDs-and-metadata).

## Step 2: Create an integration script

The integration requires a script that is designed to install and initialize the Pendo agent within your embed environment.

> **IMPORTANT:** Create your own integration script: ThoughtSpot strongly recommends that you replicate your own Pendo initialization logic within your own externally hosted JavaScript file for easier management and maintenance. This approach ensures consistency with your existing Pendo implementation and allows you to adapt it to your specific requirements. The sample JavaScript provided by ThoughtSpot is an example only and may not work for all use cases, particularly in cookieless environments or when using custom authentication flows.

The integration script typically includes the following components:

-   A JavaScript function that includes the initialize method required to retrieve, activate, and load the Pendo agent, `pendo.js`.
    
-   The Pendo client key that is unique to each customer account. It maps the metadata to your Pendo subscription.
    
-   Pendo visitor configuration that identifies the user (visitor).
    
-   Pendo account configuration that identifies the account (organization or user group) to which the user belongs
    

The client key and configuration metadata for the Pendo visitor and account must be passed to the script via the [customVariablesForThirdPartyTools]({{navprefix}}/{{pendo-integration}}#_step_6_define_custom_variables_in_the_visual_embed_sdk) object in the Visual Embed SDK to identify users and accounts for tracking, segmentation, and personalized experiences within Pendo.

For more information about the Pendo configuration metadata, script creation and its components, refer to the following articles in the Pendo documentation:

-   [Developer’s guide to implementing Pendo using the install script](https://support.pendo.io/hc/en-us/articles/360046272771-Developer-s-guide-to-implementing-Pendo-using-the-install-script)
    
-   [Components of the install script](https://support.pendo.io/hc/en-us/articles/21362607464987-Components-of-the-install-script#01H6S2EXET8C9FGSHP08XZAE4F)
    
-   [Pendo configuration metadata](https://support.pendo.io/hc/en-us/articles/21326198721563-Choose-IDs-and-metadata)
    

### Sample JavaScript for Pendo integration

To assist you with the Pendo integration process, ThoughtSpot provides a sample JavaScript, `pendoIntegrationScript.js`, as a **reference example only**. You can find this sample JavaScript in the [ThoughtSpot Developer examples](https://github.com/thoughtspot/developer-examples/blob/main/visual-embed/pendo-integration/pendoIntegrationScript.js) GitHub repository.

> **NOTE:** This sample script is provided for reference purposes. It demonstrates how to: Access custom variables defined in the SDK. It waits for the Visual Embed SDK to initialize and load. Wait for the user to authenticate successfully and receive information such as user ID, name, email, groups, and account details from the Visual Embed SDK. Initialize Pendo with the metadata and key, so that Pendo can track the user and their actions within the embedded app. However, you should create your own script that replicates your application’s Pendo initialization logic. For example, if your application uses a React hook to call pendo.initialize, adapt that logic to vanilla JavaScript in your hosted script. This ensures consistency with your existing implementation and better compatibility with your authentication and environment setup.

## Step 3: Host the script on a public site

When your integration script is ready, host it on a publicly accessible domain, such as AWS S3, Azure Blob, GitHub, or a trusted CDN. The script must be accessible to ThoughtSpot so it can fetch and inject it into the embed iframe.

Note the hosting domain and ensure the script URL is publicly accessible.

> **NOTE:** If you anticipate frequent updates to the script, choose a hosting service that allows content overrides without changing the URL. If you use the same hosting URL, you don’t need to request approval from Support each time the script is modified.

## Step 4: Contact ThoughtSpot Support to enable integration

Create a ThoughtSpot Support request to enable Pendo integration with your ThoughtSpot Embed.

In your support request:

-   Specify the exact domain that will host your script in the embedding environment. Send the full URL path, including the `.js` extension.
    
-   Send the script that you want to integrate.
    

Wait for ThoughtSpot Support to validate and approve your request. This step is required to ensure that only scripts from the vetted domain are allowed to run in your embed environment.

## Step 5: Add the Script source to the CSP Allowlist

After ThoughtSpot enables the integration for your instance, you must add your script’s hosting domain to the Content Security Policy (CSP) allowlist to ensure ThoughtSpot can fetch and execute your script:

1.  Log in to your ThoughtSpot instance as an administrator.  
    
2.  Go to the **Develop** page.  
    If your instance has Orgs, switch to the **All Orgs** context.
    
3.  In the **Customizations** section, click **Security Settings**.
    
4.  Check whether the **CSP script-src domains** setting is visible on the **Security Settings** page.
    
5.  Add the domain that hosts your script to the **CSP script-src** allowlist.  
    This step is required to allow ThoughtSpot to fetch your script from the hosting domain and inject it into the embed iframe.
    

## Step 6: Define custom variables in the Visual Embed SDK

Define the required variables in `init ()` configuration of your embed code.

To pass the variables to your script, use the [customVariablesForThirdPartyTools](https://developers.thoughtspot.com/docs/Interface_EmbedConfig#_customvariablesforthirdpartytools) object in the Visual Embed SDK. The `customVariablesForThirdPartyTools` object allows you to securely pass variables, such as API keys and user/account information, to scripts loaded in the embed context. Note that these variables include private information such as credentials or keys. The integration script will read these variables from the global window object (`window.tsEmbed`).

Add the following variables in the `init()` configuration:

-   `pendoClientKey`  
    The API key or client key to initialize Pendo
    
-   `pendoVisitorConfig`  
    The object containing Pendo visitor (user) metadata
    
-   `pendoAccountConfig`  
    The object containing Pendo account (organization) metadata
    

```JavaScript
init({
  thoughtSpotHost: 'Your-ThoughtSpot-Host', // (Required) The URL of your ThoughtSpot instance
  authType: AuthType.None, // (Required) Authentication type; 'None' is for development/testing only
  // Pass custom variables for Pendo
  customVariablesForThirdPartyTools: {
    pendoKey: 'your-key', // Pendo API key or client key
    pendoVisitorConfig: { // Pendo visitor (user) metadata
      id: 'user-id',      // User ID
      name: 'user-name'   // User's display name
    },
    pendoAccountConfig: { // Pendo account (organization) metadata
      id: 'account-id',   // ID of the Pendo account
      name: 'account-name'// Display name of the Pendo account
    }
  },
});
```

The script will include the following code to access these variables via the `window.tsEmbed` object and initialize the Pendo agent in your ThoughtSpot embed environment.

```JavaScript
const pendoKey = window.tsEmbed.pendoKey;
const pendoVisitorConfig = window.tsEmbed.pendoVisitorConfig; // Make sure to pass at least the id and name in the customVariablesForThirdPartyTools
const pendoAccountConfig = window.tsEmbed.pendoAccountConfig; // Make sure to pass at least the id and name in the customVariablesForThirdPartyTools
```

When the SDK initializes and the authentication is completed successfully, your hosted JavaScript will run seamlessly in your ThoughtSpot embed environment.

## Step 7: Validate and test Pendo integration

To validate and test Pendo integration in your embed:

1.  Log in to your embedded ThoughtSpot application as an end user.
    
2.  Open browser dev tools and verify if the network requests are being sent to Pendo.
    
    ![Dev console verification](/docs/doc-images/images/pendo-dev-console.png)
    
3.  If your integration script includes validation checks with `pendo.validateEnvironment()`, you can verify the logs in the console to confirm if the script is executed successfully and initializes as expected. You can also enable debug logs by adding `logLevel: LogLevel.DEBUG` to your `init` code.  
    For more information about `pendo.validateEnvironment()`, see the "Verify the installation" section in the [Pendo Documentation](https://support.pendo.io/hc/en-us/articles/360046272771-Developer-s-guide-to-implementing-Pendo-using-the-install-script) or refer to the [sample script provided by ThoughtSpot](https://github.com/thoughtspot/developer-examples/blob/main/visual-embed/pendo-integration/pendoIntegrationScript.js).
    
4.  Log in to Pendo to create a sample guide for your ThoughtSpot application instance.
    
5.  In the ThoughtSpot UI, verify if the Pendo guide is published.  
    In the following figure shows the sample Pendo element assigned to the information badge next to Watchlist on the ThoughtSpot Home page:
    
    ![Dev console verification](/docs/doc-images/images/pendo_info_icon.png)
    

## Troubleshooting

If the script is not loading:

-   Check the browser console for CSP or network errors.
    
-   Check the CSP allowlist in ThoughtSpot to ensure the domain hosting URL is allowed.
    

If the variables are not available:

-   Check if the SDK is initialized and the variables are passed in the `customVariablesForThirdPartyTools` object in the `init()` function in the SDK.
    
-   Check whether your script can access the `window.tsEmbed` object after the embed has initialized.
    

## Additional resources

-   [ThoughtSpot Developer examples GitHub repository](https://github.com/thoughtspot/developer-examples/tree/main/visual-embed/pendo-integration)
    
-   [Pendo Getting Started Guide](https://www.pendo.io/resources/getting-started-with-pendo/)
    
-   [Pendo Documentation](https://support.pendo.io/hc/en-us/articles/360046272771-Developer-s-guide-to-implementing-Pendo-using-the-install-script)
    
-   [Code sandbox](https://codesandbox.io/p/devbox/optimistic-mcclintock-lw2qq8)