From 9b32e00dc6f8f499009da1ac4481a98262f573bd Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Fri, 4 Jul 2025 11:04:01 +0530 Subject: [PATCH 1/6] pendo int guide --- modules/ROOT/pages/common/nav.adoc | 1 + modules/ROOT/pages/pendo-integration.adoc | 156 ++++++++++++++++++++++ 2 files changed, 157 insertions(+) create mode 100644 modules/ROOT/pages/pendo-integration.adoc diff --git a/modules/ROOT/pages/common/nav.adoc b/modules/ROOT/pages/common/nav.adoc index 396200e61..e01bc0305 100644 --- a/modules/ROOT/pages/common/nav.adoc +++ b/modules/ROOT/pages/common/nav.adoc @@ -153,6 +153,7 @@ include::generated/typedoc/CustomSideNav.adoc[] *** link:{{navprefix}}/prerender[Prerender components] ** link:{{navprefix}}/security-settings[Security settings] *** link:{{navprefix}}/external-tool-script-integration[Integrate external tools and scripts] +**** link:{{navprefix}}/pendo-integration[Pendo integration with embed] ** Other embedding methods *** link:{{navprefix}}/embed-without-sdk[Embed without SDK] *** link:{{navprefix}}/custom-viz-rest-api[Create a custom visualization] diff --git a/modules/ROOT/pages/pendo-integration.adoc b/modules/ROOT/pages/pendo-integration.adoc new file mode 100644 index 000000000..06e92383c --- /dev/null +++ b/modules/ROOT/pages/pendo-integration.adoc @@ -0,0 +1,156 @@ += Integrate Pendo with ThoughtSpot Embed +:toc: true +:toclevels: 2 + +:page-title: Pendo integration guide +:page-pageid: pendo-integration +:page-description: This document describes how to intregate Pendo in your embed experience. + +To launch Pendo guides and analytics within your ThoughtSpot embedded instance, you must integrate Pendo with your ThoughtSpot 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. +==== + +== Before you begin +Before you begin, make sure your application environment has the following: + +* Admin access to your ThoughtSpot instance. If Orgs are enabled on your instance, ensure that you have logged in to the All Orgs context. +* A publicly accessible URL to host your integration script. +* Approval from ThoughtSpot Support to enable integration. +* Review and understand potential security risks. + +Malicious scripts introduce XSS risks and can compromise user data and application integrity. Therefore, both ThoughtSpot Support and the customer must explicitly enable and approve the integration to ensure that only vetted and trusted script URLs are allowed. + +== Step 1: Sign in to your Pendo Account + +If you have a Pendo account, sign in to Pendo. + +If you have not installed Pendo or do not have a Pendo account, link:https://app.pendo.io/register[sign up for a trial, window=_blank] Pendo account. + +For integration with ThoughtSpot embed, you'll need to use a custom script. For this, you need to identify the information you want to capture, define visitors and accounts, and segment data. This information will be used as metadata for the variables in the Pendo install script. For more information, see link:https://support.pendo.io/hc/en-us/articles/21326198721563-Choose-IDs-and-metadata[Pendo documentation]. + +== Step 2: Create an integration script + +To integrate Pendo with ThoughtSpot embed, you'll need a custom JavaScript that is designed to install and initialize the Pendo agent in your ThoughtSpot embed environment. + +The script typically includes the following components: + +* The Pendo app key +The Pendo app key is unique to a customer accounts. It maps the data that the agent collects to the product in your Pendo subscription. You must also include a variable for this app key in the Visual Embed SDK. +* A JavaScript function that includes the initialize method required to retrieve, activate, and load the Pendo agent, `pendo.js`. + +You can either create your own integration script or use the xref:pendo-integration.adoc#_sample_javascript_for_pendo_integration[sample JavaScript] provided by ThoughtSpot. + +For more information about the script creation and components, refer to the following articles in Pendo documentation: + +* link:https://support.pendo.io/hc/en-us/articles/360046272771-Developer-s-guide-to-implementing-Pendo-using-the-install-script[Developer's guide to implementing Pendo using the install script] +* link:https://support.pendo.io/hc/en-us/articles/21362607464987-Components-of-the-install-script#01H6S2EXET8C9FGSHP08XZAE4F[Components of the install script]. + +=== Sample JavaScript for Pendo integration +To assist you with the Pendo integration process, ThoughtSpot provides a sample JavaScript, `pendoIntegrationScript.js` for app integration. You can access this sample JavaScript in the link:https://github.com/thoughtspot/developer-examples/blob/524ef13121fcae4756a951648e3e6dc4bb29aa26/visual-embed/pendo-integration/pendoIntegrationScript.js[ThoughtSpot Developer examples, window=_blank] GitHub repository. + +The script performs the following actions: + +* Access custom variables defined in the SDK. It waits for the Visual Embed SDK to initialize and load. + +* Listen for authentication. + +It waits for the user to authenticate with ThoughtSpot. +* Fetches user and context data + +When the user authentication is successful, the script retrieves the current user's information, such as user ID, name, email, and groups from the SDK. It also listens for navigation events within the embedded ThoughtSpot app to capture the current page or context. +* Initialize Pendo + +The script initializes Pendo with the user and context data, so that Pendo can track the user and their actions within the embedded app. +* Update Pendo on navigation + +Whenever the user navigates to a new page or context within the embedded ThoughtSpot app, the script updates Pendo with the new context information. + +== Step 3: Host the script on a public domain + +When your integration script is ready, host it on a publicly accessible domain; For example, for AWS S3, Azure Blob, or a trusted CDN. + +Note the domain URL. You need to send this URL to ThoughtSpot Support and add it to your CSP allowlist later. + +== 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 domains that will host your script in the embedding environment. Make sure that you send the full URL path, including the `.js` extension at the end. +* Send the script that you want to integrate. + +Wait for ThoughtSpot Support to validate and approve your request. This step will ensure that only scripts from the trusted and vetted domains are allowed to run scripts in your embed environment. + +== Step 5: Verify feature enablement + +After ThoughtSpot enables the integration for your instance: + +. Log in to your ThoughtSpot instance as an administrator. +. Go to **Develop** > **Security Settings**. +. Make sure that you are in the *All Orgs* context. +. Check if the *CSP script-src domains* setting is visible on the *Security Settings* page. +. Add the domain that hosts your script to the **CSP script-src** allowlist. + +== Step 5: Pass variables to your script via Visual Embed SDK + +To execute the script properly, in your embed code, pass the variables in `init ()` configuration. To pass the variables to your script, use the link:https://developers.thoughtspot.com/docs/Interface_EmbedConfig#_customvariablesforthirdpartytools[customVariablesForThirdPartyTools] object in the Visual Embed SDK. + +Add the following variables in the `init()` configuration: + +* `pendoClientKey` +* `pendoVisitorConfig` +* `pendoAccountConfig` + +[source,JavaScript] +---- +init({ + //...embedConfig, + customVariablesForThirdPartyTools: { + { + pendoKey: 'your-key', + pendoVisitorConfig: { + id: 'user-id', + name: 'user-name' + }, + pendoAccountConfig: { + id: 'account-id', + name: 'account-name' + } + } + } +} +}); +---- + +Note that these variables include private information such as credentials or keys. Your Pendo integration 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. + +[source,JavaScript] +---- +const pendoKey = window.tsEmbed.pendoKey; +const pendoVisitorConfig = window.tsEmbed.pendoVisitorConfig; // Make sure to pass atleast id and name in the customVariablesForThirdPartyTools +const pendoAccountConfig = window.tsEmbed.pendoAccountConfig; // Make sure to pass atleast 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 6: Validate and test Pendo integration +To validate and test Pendo integration in your embed: + +. Log in to your embedded ThoughtSpot application as an end user. +. Confirm that the Pendo script loads and initializes as expected. +. Check if custom variables are passed and used correctly. +. Access Pendo and create a Pendo tour or guide using the Pendo dashboard and verify whether the guides appear inside the embedded ThoughtSpot instance. + +== Troubleshooting + +If the script is not loading: + +* Check the browser console for CSP or network errors. +* Check if the domain hosting the script is added to the CSP allowlist in ThoughtSpot. + +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 has access to `window.tsEmbed` after the embed has initialized. + +== Additional resources + +* link:https://github.com/thoughtspot/developer-examples/blob/524ef13121fcae4756a951648e3e6dc4bb29aa26/visual-embed/pendo-integration/pendoIntegrationScript.js[ThoughtSpot Developer examples GitHub repository, window=_blank] +* link:https://www.pendo.io/resources/getting-started-with-pendo/[Pendo Getting Started Guide] +* link:https://support.pendo.io/hc/en-us/articles/360046272771-Developer-s-guide-to-implementing-Pendo-using-the-install-script[Pendo Documentation, window=_blank] From 762abab131a1c557f0bd5be068f775335703570f Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Fri, 4 Jul 2025 11:43:47 +0530 Subject: [PATCH 2/6] edits --- modules/ROOT/pages/common/nav.adoc | 4 +- modules/ROOT/pages/pendo-integration.adoc | 53 ++++++++++++----------- 2 files changed, 30 insertions(+), 27 deletions(-) diff --git a/modules/ROOT/pages/common/nav.adoc b/modules/ROOT/pages/common/nav.adoc index e01bc0305..35229a706 100644 --- a/modules/ROOT/pages/common/nav.adoc +++ b/modules/ROOT/pages/common/nav.adoc @@ -152,8 +152,8 @@ include::generated/typedoc/CustomSideNav.adoc[] *** link:{{navprefix}}/prefetch[Prefetch static resources] *** link:{{navprefix}}/prerender[Prerender components] ** link:{{navprefix}}/security-settings[Security settings] -*** link:{{navprefix}}/external-tool-script-integration[Integrate external tools and scripts] -**** link:{{navprefix}}/pendo-integration[Pendo integration with embed] +** link:{{navprefix}}/external-tool-script-integration[Integrate external tools and scripts] +*** link:{{navprefix}}/pendo-integration[Pendo integration with embed] ** Other embedding methods *** link:{{navprefix}}/embed-without-sdk[Embed without SDK] *** link:{{navprefix}}/custom-viz-rest-api[Create a custom visualization] diff --git a/modules/ROOT/pages/pendo-integration.adoc b/modules/ROOT/pages/pendo-integration.adoc index 06e92383c..ba4270030 100644 --- a/modules/ROOT/pages/pendo-integration.adoc +++ b/modules/ROOT/pages/pendo-integration.adoc @@ -6,37 +6,38 @@ :page-pageid: pendo-integration :page-description: This document describes how to intregate Pendo in your embed experience. -To launch Pendo guides and analytics within your ThoughtSpot embedded instance, you must integrate Pendo with your ThoughtSpot embed environment. This integration typically requires adding a custom JavaScript to enable product tours, feature announcements, and usage tracking within the embedded experience. +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. -==== == Before you begin -Before you begin, make sure your application environment has the following: +Pendo integration with ThoughtSpot embed requires the following: -* Admin access to your ThoughtSpot instance. If Orgs are enabled on your instance, ensure that you have logged in to the All Orgs context. -* A publicly accessible URL to host your integration script. -* Approval from ThoughtSpot Support to enable integration. -* Review and understand potential security risks. + -Malicious scripts introduce XSS risks and can compromise user data and application integrity. Therefore, both ThoughtSpot Support and the customer must explicitly enable and approve the integration to ensure that only vetted and trusted script URLs are allowed. +* Access to Pendo + +If you do not have a Pendo account, link:https://app.pendo.io/register[sign up for a trial, window=_blank] Pendo account. +* Admin access to your ThoughtSpot instance. If your instance has Orgs, ensure that you are in the *All Orgs* context. +* Approval from ThoughtSpot Support for Pendo integration. +* A publicly accessible domain to host your integration script. + +[IMPORTANT] +==== +ThoughtSpot strongly recommends that you review and understand potential security risks with custom scripts and third-party tool integration. Malicious scripts introduce XSS risks and can compromise user data and application integrity. Therefore, both ThoughtSpot Support and the customer must explicitly enable and approve the integration to ensure that only vetted and trusted script URLs are allowed. +==== == Step 1: Sign in to your Pendo Account -If you have a Pendo account, sign in to Pendo. + -If you have not installed Pendo or do not have a Pendo account, link:https://app.pendo.io/register[sign up for a trial, window=_blank] Pendo account. +Sign in to your Pendo account. -For integration with ThoughtSpot embed, you'll need to use a custom script. For this, you need to identify the information you want to capture, define visitors and accounts, and segment data. This information will be used as metadata for the variables in the Pendo install script. For more information, see link:https://support.pendo.io/hc/en-us/articles/21326198721563-Choose-IDs-and-metadata[Pendo documentation]. +For integration with ThoughtSpot embed, you'll need to use a custom script. Identify the information you want to capture, define visitors and accounts, and segment data. This information will be used as metadata in the Pendo install script. For more information, see link:https://support.pendo.io/hc/en-us/articles/21326198721563-Choose-IDs-and-metadata[Pendo documentation]. == Step 2: Create an integration script -To integrate Pendo with ThoughtSpot embed, you'll need a custom JavaScript that is designed to install and initialize the Pendo agent in your ThoughtSpot embed environment. +To integrate Pendo with ThoughtSpot embed, you need a custom JavaScript that is designed to install and initialize the Pendo agent within your embed environment. The script typically includes the following components: -* The Pendo app key -The Pendo app key is unique to a customer accounts. It maps the data that the agent collects to the product in your Pendo subscription. You must also include a variable for this app key in the Visual Embed SDK. +* The Pendo app key, which is unique to each customer account. It maps collected data to your Pendo subscription. Include a variable for this app key in the Visual Embed SDK. + * A JavaScript function that includes the initialize method required to retrieve, activate, and load the Pendo agent, `pendo.js`. You can either create your own integration script or use the xref:pendo-integration.adoc#_sample_javascript_for_pendo_integration[sample JavaScript] provided by ThoughtSpot. @@ -49,7 +50,7 @@ For more information about the script creation and components, refer to the foll === Sample JavaScript for Pendo integration To assist you with the Pendo integration process, ThoughtSpot provides a sample JavaScript, `pendoIntegrationScript.js` for app integration. You can access this sample JavaScript in the link:https://github.com/thoughtspot/developer-examples/blob/524ef13121fcae4756a951648e3e6dc4bb29aa26/visual-embed/pendo-integration/pendoIntegrationScript.js[ThoughtSpot Developer examples, window=_blank] GitHub repository. -The script performs the following actions: +The `pendoIntegrationScript.js` script is designed to perform the following actions: * Access custom variables defined in the SDK. It waits for the Visual Embed SDK to initialize and load. + * Listen for authentication. + @@ -61,23 +62,23 @@ The script initializes Pendo with the user and context data, so that Pendo can t * Update Pendo on navigation + Whenever the user navigates to a new page or context within the embedded ThoughtSpot app, the script updates Pendo with the new context information. -== Step 3: Host the script on a public domain +== Step 3: Host the script -When your integration script is ready, host it on a publicly accessible domain; For example, for AWS S3, Azure Blob, or a trusted CDN. +When your integration script is ready, host it on a publicly accessible domain, such as AWS S3, Azure Blob, or a trusted CDN. -Note the domain URL. You need to send this URL to ThoughtSpot Support and add it to your CSP allowlist later. +Note the hosting domain URL. You will need to send this URL to ThoughtSpot Support and later add it to your CSP allowlist in ThoughtSpot. == 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 domains that will host your script in the embedding environment. Make sure that you send the full URL path, including the `.js` extension at the end. +* Specify the domains 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 will ensure that only scripts from the trusted and vetted domains are allowed to run scripts in your embed environment. -== Step 5: Verify feature enablement +== Step 5: Add the Script source to the CSP Allowlist After ThoughtSpot enables the integration for your instance: @@ -87,9 +88,9 @@ After ThoughtSpot enables the integration for your instance: . Check if the *CSP script-src domains* setting is visible on the *Security Settings* page. . Add the domain that hosts your script to the **CSP script-src** allowlist. -== Step 5: Pass variables to your script via Visual Embed SDK +== Step 5: Define custom variables in the Visual Embed SDK -To execute the script properly, in your embed code, pass the variables in `init ()` configuration. To pass the variables to your script, use the link:https://developers.thoughtspot.com/docs/Interface_EmbedConfig#_customvariablesforthirdpartytools[customVariablesForThirdPartyTools] object 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 link:https://developers.thoughtspot.com/docs/Interface_EmbedConfig#_customvariablesforthirdpartytools[customVariablesForThirdPartyTools] object in the Visual Embed SDK. Add the following variables in the `init()` configuration: @@ -118,7 +119,9 @@ init({ }); ---- -Note that these variables include private information such as credentials or keys. Your Pendo integration 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. +Note that these variables include private information such as credentials or keys. + +Your Pendo integration 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. [source,JavaScript] ---- From dc2af709a70a1bb0f7de2bae5a51a900f21bb9bc Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Fri, 4 Jul 2025 11:48:02 +0530 Subject: [PATCH 3/6] edits --- modules/ROOT/pages/pendo-integration.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/pendo-integration.adoc b/modules/ROOT/pages/pendo-integration.adoc index ba4270030..5d66683f0 100644 --- a/modules/ROOT/pages/pendo-integration.adoc +++ b/modules/ROOT/pages/pendo-integration.adoc @@ -62,7 +62,7 @@ The script initializes Pendo with the user and context data, so that Pendo can t * Update Pendo on navigation + Whenever the user navigates to a new page or context within the embedded ThoughtSpot app, the script updates Pendo with the new context information. -== Step 3: Host the script +== 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, or a trusted CDN. From 12829adf17371645d534b51e20f2b048f4749515 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Fri, 4 Jul 2025 11:50:50 +0530 Subject: [PATCH 4/6] edits --- modules/ROOT/pages/pendo-integration.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/pendo-integration.adoc b/modules/ROOT/pages/pendo-integration.adoc index 5d66683f0..92788365a 100644 --- a/modules/ROOT/pages/pendo-integration.adoc +++ b/modules/ROOT/pages/pendo-integration.adoc @@ -66,7 +66,7 @@ Whenever the user navigates to a new page or context within the embedded Thought When your integration script is ready, host it on a publicly accessible domain, such as AWS S3, Azure Blob, or a trusted CDN. -Note the hosting domain URL. You will need to send this URL to ThoughtSpot Support and later add it to your CSP allowlist in ThoughtSpot. +Note the hosting domain URL. You will need to send this URL to ThoughtSpot Support and add it to the CSP allowlist on your ThoughtSpot instance. == Step 4: Contact ThoughtSpot Support to enable integration From 6a0137c4f56a27245896c8c9cdef1356bcba8179 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Mon, 7 Jul 2025 19:28:48 +0530 Subject: [PATCH 5/6] edits for review comments --- modules/ROOT/pages/pendo-integration.adoc | 56 +++++++++++++---------- 1 file changed, 32 insertions(+), 24 deletions(-) diff --git a/modules/ROOT/pages/pendo-integration.adoc b/modules/ROOT/pages/pendo-integration.adoc index 92788365a..e551560bd 100644 --- a/modules/ROOT/pages/pendo-integration.adoc +++ b/modules/ROOT/pages/pendo-integration.adoc @@ -21,53 +21,61 @@ If you do not have a Pendo account, link:https://app.pendo.io/register[sign up f [IMPORTANT] ==== -ThoughtSpot strongly recommends that you review and understand potential security risks with custom scripts and third-party tool integration. Malicious scripts introduce XSS risks and can compromise user data and application integrity. Therefore, both ThoughtSpot Support and the customer must explicitly enable and approve the integration to ensure that only vetted and trusted script URLs are allowed. +ThoughtSpot strongly recommends that you review the security guidelines of your organization and assess the 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. Therefore, both ThoughtSpot Support and the customer must explicitly enable and approve the integration to ensure that only vetted and trusted script URLs are allowed in the embed app. ==== == Step 1: Sign in to your Pendo Account Sign in to your Pendo account. -For integration with ThoughtSpot embed, you'll need to use a custom script. Identify the information you want to capture, define visitors and accounts, and segment data. This information will be used as metadata in the Pendo install script. For more information, see link:https://support.pendo.io/hc/en-us/articles/21326198721563-Choose-IDs-and-metadata[Pendo documentation]. +For integration with ThoughtSpot embed, you'll need to use a custom script. Identify the information you want to capture, define visitors and accounts, and segment data. This information will be used as metadata in the Pendo install script. For more information, refer to the link:https://support.pendo.io/hc/en-us/articles/21326198721563-Choose-IDs-and-metadata[Pendo Documentation, window=_blank]. == Step 2: Create an integration script -To integrate Pendo with ThoughtSpot embed, you need a custom JavaScript that is designed to install and initialize the Pendo agent within your embed environment. +To integrate Pendo with ThoughtSpot embed, you need a custom JavaScript that is designed to install and initialize the Pendo agent within your embed environment. You can either create your own integration script or use the xref:pendo-integration.adoc#_sample_javascript_for_pendo_integration[sample JavaScript] provided by ThoughtSpot. The script typically includes the following components: -* The Pendo app key, which is unique to each customer account. It maps collected data to your Pendo subscription. Include a variable for this app key in the Visual Embed SDK. - * 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 -You can either create your own integration script or use the xref:pendo-integration.adoc#_sample_javascript_for_pendo_integration[sample JavaScript] provided by ThoughtSpot. +The client key and configuration metadata for Pendo visitor and account must be passed to the script via the xref:pendo-integration.adoc#_step_6_define_custom_variables_in_the_visual_embed_sdk[customVariablesForThirdPartyTools object in the Visual Embed SDK] to identify users and accounts for tracking, segmentation, and personalized experiences within Pendo. -For more information about the script creation and components, refer to the following articles in Pendo documentation: +For more information about the Pendo configuration metadata, script creation and its components, refer to the following articles in the Pendo documentation: -* link:https://support.pendo.io/hc/en-us/articles/360046272771-Developer-s-guide-to-implementing-Pendo-using-the-install-script[Developer's guide to implementing Pendo using the install script] -* link:https://support.pendo.io/hc/en-us/articles/21362607464987-Components-of-the-install-script#01H6S2EXET8C9FGSHP08XZAE4F[Components of the install script]. +* link:https://support.pendo.io/hc/en-us/articles/360046272771-Developer-s-guide-to-implementing-Pendo-using-the-install-script[Developer's guide to implementing Pendo using the install script, window=_blank] +* link:https://support.pendo.io/hc/en-us/articles/21362607464987-Components-of-the-install-script#01H6S2EXET8C9FGSHP08XZAE4F[Components of the install script, window=_blank] +* link:https://support.pendo.io/hc/en-us/articles/21326198721563-Choose-IDs-and-metadata[Pendo configuration metadata, window=_blank] === Sample JavaScript for Pendo integration To assist you with the Pendo integration process, ThoughtSpot provides a sample JavaScript, `pendoIntegrationScript.js` for app integration. You can access this sample JavaScript in the link:https://github.com/thoughtspot/developer-examples/blob/524ef13121fcae4756a951648e3e6dc4bb29aa26/visual-embed/pendo-integration/pendoIntegrationScript.js[ThoughtSpot Developer examples, window=_blank] GitHub repository. The `pendoIntegrationScript.js` script is designed to perform the following actions: -* Access custom variables defined in the SDK. It waits for the Visual Embed SDK to initialize and load. + -* Listen for authentication. + -It waits for the user to authenticate with ThoughtSpot. -* Fetches user and context data + -When the user authentication is successful, the script retrieves the current user's information, such as user ID, name, email, and groups from the SDK. It also listens for navigation events within the embedded ThoughtSpot app to capture the current page or context. -* Initialize Pendo + -The script initializes Pendo with the user and context data, so that Pendo can track the user and their actions within the embedded app. +* 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. + +//// * Update Pendo on navigation + Whenever the user navigates to a new page or context within the embedded ThoughtSpot app, the script updates Pendo with the new context information. +It also listens for navigation events within the embedded ThoughtSpot app to capture the current page or context. +//// + == 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, or a trusted CDN. Note the hosting domain URL. You will need to send this URL to ThoughtSpot Support and add it to the CSP allowlist on your ThoughtSpot instance. +[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. @@ -85,10 +93,10 @@ After ThoughtSpot enables the integration for your instance: . Log in to your ThoughtSpot instance as an administrator. . Go to **Develop** > **Security Settings**. . Make sure that you are in the *All Orgs* context. -. Check if the *CSP script-src domains* setting is visible on the *Security Settings* page. +. Check whether the *CSP script-src domains* setting is visible on the *Security Settings* page. . Add the domain that hosts your script to the **CSP script-src** allowlist. -== Step 5: Define custom variables in the Visual Embed SDK +== 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 link:https://developers.thoughtspot.com/docs/Interface_EmbedConfig#_customvariablesforthirdpartytools[customVariablesForThirdPartyTools] object in the Visual Embed SDK. @@ -126,18 +134,18 @@ Your Pendo integration script will include the following code to access these va [source,JavaScript] ---- const pendoKey = window.tsEmbed.pendoKey; -const pendoVisitorConfig = window.tsEmbed.pendoVisitorConfig; // Make sure to pass atleast id and name in the customVariablesForThirdPartyTools -const pendoAccountConfig = window.tsEmbed.pendoAccountConfig; // Make sure to pass atleast id and name in the customVariablesForThirdPartyTools +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 6: Validate and test Pendo integration +== Step 7: Validate and test Pendo integration To validate and test Pendo integration in your embed: . Log in to your embedded ThoughtSpot application as an end user. -. Confirm that the Pendo script loads and initializes as expected. -. Check if custom variables are passed and used correctly. +. If have implemented a check using `pendo.validateEnvironment()` in your integration script, verify the logs in the console to confirm if the script is executed successfully and initializes as expected. + +For more information about `pendo.validateEnvironment()`, see the "Verify the installation" section in the link:https://support.pendo.io/hc/en-us/articles/360046272771-Developer-s-guide-to-implementing-Pendo-using-the-install-script[Pendo Documentation, window=_blank] or the link:https://github.com/thoughtspot/developer-examples/blob/524ef13121fcae4756a951648e3e6dc4bb29aa26/visual-embed/pendo-integration/pendoIntegrationScript.js#L108[sample script provided by ThoughtSpot, window=_blank]. . Access Pendo and create a Pendo tour or guide using the Pendo dashboard and verify whether the guides appear inside the embedded ThoughtSpot instance. == Troubleshooting @@ -145,7 +153,7 @@ To validate and test Pendo integration in your embed: If the script is not loading: * Check the browser console for CSP or network errors. -* Check if the domain hosting the script is added to the CSP allowlist in ThoughtSpot. +* Check the CSP allowlist in ThoughtSpot to ensure the domain hosting URL is allowed. If the variables are not available: From e4e18c7fb02a39405ad7e6d904a67033b8e0b199 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Wed, 9 Jul 2025 11:07:07 +0530 Subject: [PATCH 6/6] review comments --- modules/ROOT/pages/pendo-integration.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/pendo-integration.adoc b/modules/ROOT/pages/pendo-integration.adoc index e551560bd..ea5f56105 100644 --- a/modules/ROOT/pages/pendo-integration.adoc +++ b/modules/ROOT/pages/pendo-integration.adoc @@ -81,7 +81,7 @@ If you anticipate frequent updates to the script, choose a hosting service that Create a ThoughtSpot Support request to enable Pendo integration with your ThoughtSpot Embed. In your support request: -* Specify the domains that will host your script in the embedding environment. Send the full URL path, including the `.js` extension. +* 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 will ensure that only scripts from the trusted and vetted domains are allowed to run scripts in your embed environment.