diff --git a/modules/ROOT/pages/abac_rls-variables.adoc b/modules/ROOT/pages/abac_rls-variables.adoc index 29e167013..13155c0cf 100644 --- a/modules/ROOT/pages/abac_rls-variables.adoc +++ b/modules/ROOT/pages/abac_rls-variables.adoc @@ -109,7 +109,7 @@ To define RLS rules with variables for a Table: . Navigate to the Data workspace and click the Table for which to define RLS rules. . Click *Row security* and then click *+ Add row security*. -. In the *Row Security Editor*, define the rules. To reference the formula variable in the rule, use the `ts_var` function. For example, If you want to limit user access to data of a specific region, you can create a region-specific variable, `region = ts_var('region_var')`, and assign values in the token request. +. In the *Row Security Editor*, define the rules. To reference the formula variable in the rule, use the `ts_var` function. For example, If you want to limit user access to data of a specific region, you can create a region-specific variable, `region = ts_var(region_var)`, and assign values in the token request. === RLS rule with a single variable reference @@ -117,7 +117,7 @@ To define RLS rules with variables for a Table: In this formula example, `country` refers to the "country" column in the data table, and `country_var` is the variable. ---- -country = ts_var('country_var') +country = ts_var(country_var) ---- If `country_var` is assigned a single value, the user is permitted to view only rows where the `country` column matches that value. @@ -130,20 +130,20 @@ The RLS rules support the `AND` operator, which means that you can combine multi The following rule restricts data access to rows if the `country` column in the data table matches the value assigned to `country_var` and the `Department` column matches the value assigned to `department_var` for that user. ---- -country = ts_var('country_var') AND Department = ts_var('department_var') +country = ts_var(country_var) AND Department = ts_var(department_var) ---- The rule in this example restricts data access to rows where the `region` column in the table matches the value assigned to `region_var` and the `product` column matches the value assigned to `product_var`. ---- -region = ts_var('region_var') AND product = ts_var('product_var') +region = ts_var(region_var) AND product = ts_var(product_var) ---- === Allow all rule with a TS_WILDCARD_ALL variable In this example, `customer` represents the column `customer` in the table and `customer_var` represents variable. If the value of the customer_var variable is set to `TS_WILDCARD_ALL`, the user can access all customers in the column. ---- -customer = ts_var('customer_var') +customer = ts_var(customer_var) ---- === Group override rule with variable-based check @@ -152,7 +152,7 @@ In any security formula you build, you may want a clause that gives access to al In this example, users can access data if they are in the "data developers" group, or if the `Department` column matches the value assigned to their `department_var` variable. ---- -'data developers' in ts_groups OR Department = ts_var('department_var') +'data developers' in ts_groups OR Department = ts_var(department_var) ---- ==== Variables with numeric and Date data types @@ -160,13 +160,13 @@ In this example, users can access data if they are in the "data developers" grou The following rule enforces a numeric threshold and restricts access to rows where the Revenue value is less than or equal to the value provided by the `revenue_cap_var` variable. ---- -Revenue <= to_double(ts_var('revenue_cap_var')) +Revenue <= to_double(ts_var(revenue_cap_var)) ---- The following rule restricts access to rows where the `date_column` is within the range defined by the `start_date_var` and `end_date_var` variables. Only rows with dates greater than or equal to the start date and less than or equal to the end date specified for these variables will be visible for the user. ---- -(date_column >= ts_var('start_date_var')) AND (date_column <= ts_var('end_date_var')) +(date_column >= ts_var(start_date_var)) AND (date_column <= ts_var(end_date_var)) ---- == Create an ABAC token request with variable attributes @@ -362,8 +362,7 @@ ABAC details are sent in a JWT that can be used as a bearer token for cookieless ==== === Verify the variable assignment - -To verify the variable assignment, use the `POST /api/rest/2.0/users/search` API call and check `variable_values` in the user properties in the API response. +To retrieve user information and object properties, you can use the `POST /api/rest/2.0/users/search` API call. To include variable details in the response, set the `include_variable_values` parameter to `true` in the API request body. This allows you to fetch variable values associated with the user in the specified context. [source,JSON] ---- @@ -395,7 +394,10 @@ To verify the variable assignment, use the `POST /api/rest/2.0/users/search` API } ---- -To verify the security entitlements, start a user session using the JWT and inspect the generated SQL for your query or visualization. +You can also use the `POST /api/rest/2.0/template/variables/search` API call to xref:variables.adoc#_get_variables[get the list of variables] assigned to a specific user, Org, and Model. + +==== Updating variable values for a user +To update variable values for a user, you can use the `/api/rest/2.0/template/variables/update-values` endpoint, or `/api/rest/2.0/auth/token/custom` endpoint when logging in the user. Do not use the `/api/rest/2.0/users/{user_identifier}/update` endpoint, as it does not support updating variable values. == Verify the entitlements To verify the entitlements: diff --git a/modules/ROOT/pages/customize-homepage-full-embed.adoc b/modules/ROOT/pages/customize-homepage-full-embed.adoc index 3d4f40ac2..e97bdff66 100644 --- a/modules/ROOT/pages/customize-homepage-full-embed.adoc +++ b/modules/ROOT/pages/customize-homepage-full-embed.adoc @@ -8,26 +8,31 @@ Developers can customize the home page experience in full application embedding to show either the classic layout or the new modular home page. -In the classic (V1) experience, the home page has a static layout and does not support SDK modular customization settings. - -In the V2 and V3 experience modes, you can customize the home page by specifying which modules are visible, their order, and the overall layout using configuration options available in the SDK. - [div announcementBlock] -- [IMPORTANT] The classic (V1) experience and V2 experience modes will be deprecated in an upcoming release in 2026. Therefore, ThoughtSpot recommends upgrading the UI experience of your full application embedding to the V3 experience. -- +== Home page layout -== Home page layout in the V3 experience +In the classic (V1) experience, the home page has a static layout and does not support SDK modular customization settings. -In the V3 experience, the SDK provides the xref:HomePage.adoc[homePage] attribute that allows you to choose the desired home page layout: +In the V3 experience, the SDK provides the xref:HomePage.adoc[homePage] attribute to set the desired home page layout: * `homePage: HomePage.ModularWithStylingChanges` + -Enables the V3 modular home page experience with customizable components, styling options, and enhanced layout and visual elements. +Enables the V3 modular home page experience with customizable components, styling options, and enhanced layout. * `homePage: HomePage.Modular` + Enables the basic modular home page experience with customizable components. +After migrating from V2 to V3 experience, the home page experience shows the following changes: + +* The **Watchlist** module is vertically arranged, includes menu actions to remove the KPI charts from the watchlist and create alerts, and allows drag-and-drop reordering of charts. +* The **Trending** module displays separate lists for Liveboards and Answers objects. Both these lists show the objects trending for the last 15 days, or based on the overall views, or both. +* The **Favorites** and **Learning** modules have enhanced visual styles and improved look and feel. + +In both V2 and V3, the SDK allows customization to include or exclude modules, change their order, and adjust the overall layout. + == Customization settings for home page The following customization settings are available for the modular home page in the V2 and V3 experience modes. diff --git a/modules/ROOT/pages/full-app-customize.adoc b/modules/ROOT/pages/full-app-customize.adoc index 8fb5f3670..a63084aa0 100644 --- a/modules/ROOT/pages/full-app-customize.adoc +++ b/modules/ROOT/pages/full-app-customize.adoc @@ -46,33 +46,22 @@ A dynamic left navigation menu that adjusts its contents according to the applic |===== -- -//// -[width="100%", cols="2,8,8,8"] -[options='header'] -|===== -||V1 (Legacy) |V2 experience |V3 experience - -|Navigation style a|* Top navigation bar for application menu. + -* Separate left navigation panels only for specific application context, such as *Data*, *Admin* and *Develop* modules a| -* Persona-based app selector on the top navigation bar + -* A separate left navigation panel for each persona-based application context a| -* Sliding left navigation panel -* Persona-based tabs on the left panel to switch between application context. -* Separate left navigation panel for each application context. -|Home page experience| Basic | Modular and customizable home page | Modular -|Enablement| The default, legacy ThoughtSpot UI. a| Disabled by default. + -Can be enabled by setting `modularHomeExperience: true` in the Visual Embed SDK a| Disabled by default. + -Can be enabled by setting the `discoveryExperience` properties in the Visual Embed SDK. -|Migration considerations| If you want to continue using the classic experience, no migration is required. -If you plan to switch to the new navigation and modular home page experience, ThoughtSpot recommends migrating to the new v3 experience. -| The v2 navigation experience can be enabled by setting `modularHomeExperience` to `true` in the Visual Embed SDK. However, the new v3 experience with left navigation panel provides an improved experience and more customizable components for home page, therefore, we recommend using the v3 experience. -If you are already on v2 experience and want to switch to the new v3 experience, contact ThoughtSpot Support to enable this feature on your instance. -Once enabled, configure the `discoveryExperience` properties and customize your home page experience as per your embedding requirements. -|Contact ThoughtSpot Support to enable the v3 experience on your ThoughtSpot instance. -Once enabled, configure the `discoveryExperience` properties and customize your home page experience as per your embedding application requirements. -|||| -|===== -//// + +**V3 navigation and home page experience** +[.bordered] +[.widthAuto] +image::./images/v3-experience.png[V3 UI experience] + +**V2 navigation and home page experience** +[.bordered] +[.widthAuto] +image::./images/v2-experience.png[V2 UI experience] + +**V1 Classic experience** +[.bordered] +[.widthAuto] +image::./images/v1-experience.png[Classic experience] + == Customize the embedded application UI for your users @@ -194,13 +183,15 @@ const embed = new AppEmbed("#embed", { After you enable the V3 experience: * Ensure the UI shows the V3 navigation and home page. + +//// + The following figure shows the user interface with the V3 experience: + [.bordered] [.widthAuto] image::./images/new-nav3.png[New home page] - +//// * Verify that all the customization settings are applied correctly. * If you have set up custom routes for navigation within your embedded app, verify navigation workflows and check for breaking changes. diff --git a/modules/ROOT/pages/locale-setting.adoc b/modules/ROOT/pages/locale-setting.adoc index 00e49b0b0..1c43f2a14 100644 --- a/modules/ROOT/pages/locale-setting.adoc +++ b/modules/ROOT/pages/locale-setting.adoc @@ -23,30 +23,30 @@ If you want to set your embedded app view to a specific locale for your applicat [options="header"] |==================== | Locale | Language -| `ar-EG` | Egyptian Arabic | `da-DK` | Dansk | `de-DE` | Deutsch -| `de-CH` | German (Switzerland) +| `de-CH` | Deutsch (Switzerland) | `en-AU` | English (Australia) | `en-CA` | English (Canada) | `en-DE` | English (Germany) | `en-IN` | English (India) +| `en-NZ` | English (New Zealand) | `en-GB` | English (United Kingdom) | `en-US` | English (United States) -| `en-NZ` | English (New Zealand) +| `es-ES` | Español | `es-US` | Español (Latinoamérica) -| `es-ES` | Español (España) -| `es-MX` | Spanish (Mexico) -| `fi-FI` | Suomi +| `es-MX` | Español (Mexico) | `fr-CA` | Français (Canada) | `fr-FR` | Français (France) +| `ja-JP` | 日本語 +| `ko-KR` | 한국어 | `it-IT` | Italiano -| `ja-JP` | Japanese (Japan)/ 日本語 | `nb-NO` | Norsk | `nl-NL` | Nederland | `pt-BR` | Português (Brasil) | `pt-PT` | Português (Portugal) -| `ru-RU` | Russian (Russia) +| `ru-RU` | Pусский (ограниченный выпуск) +| `fi-FI` | Suomi | `sv-SE` | Svenska | `zh-CN` | 中文(简体) | `zh-HANT`| 中文 (繁體) diff --git a/modules/ROOT/pages/mobile-embed-android.adoc b/modules/ROOT/pages/mobile-embed-android.adoc index 153fbc0c3..b7a3a6ad4 100644 --- a/modules/ROOT/pages/mobile-embed-android.adoc +++ b/modules/ROOT/pages/mobile-embed-android.adoc @@ -13,7 +13,6 @@ Your application developers can embed a ThoughtSpot Liveboard in your native And Before you begin, ensure that your development environment has the following setup: * Access to a ThoughtSpot instance with administrator and developer privileges. + -Ensure that your host app embedding ThoughtSpot is added to the xref:security-settings.adoc[CSP and CORS allowlists] in ThoughtSpot. * Access to the Liveboard object that you want to embed. * Android Studio is installed. + diff --git a/modules/ROOT/pages/mobile-embed-qs-flutter.adoc b/modules/ROOT/pages/mobile-embed-qs-flutter.adoc index 926b091d8..2a8306a72 100644 --- a/modules/ROOT/pages/mobile-embed-qs-flutter.adoc +++ b/modules/ROOT/pages/mobile-embed-qs-flutter.adoc @@ -18,7 +18,6 @@ Before you begin, check if your setup has the following: * A Flutter application project setup. For information about creating a Flutter app, see link:https://docs.flutter.dev/reference/create-new-app[Flutter documentation, window=_blank]. * Access to a ThoughtSpot instance with administrator and developer privileges. + -Ensure that your host app embedding ThoughtSpot is added to the xref:security-settings.adoc[CSP and CORS allowlists] in ThoughtSpot. * Access to the Liveboard object that you want to embed. == Get started with embedding diff --git a/modules/ROOT/pages/mobile-embed-qs-swift.adoc b/modules/ROOT/pages/mobile-embed-qs-swift.adoc index 63f3c3ff8..105fe8e4c 100644 --- a/modules/ROOT/pages/mobile-embed-qs-swift.adoc +++ b/modules/ROOT/pages/mobile-embed-qs-swift.adoc @@ -14,7 +14,6 @@ Before you begin, ensure that your development setup includes the following: * Xcode 13 or later is installed. For information about Xcode and SwiftUI, see link:https://developer.apple.com/documentation/Xcode[Xcode documentation, window=_blank]. * iOS 14.0 or later is installed on your device to test your embed. * Access to a ThoughtSpot instance with administrator and developer privileges. + -Ensure that your host app embedding ThoughtSpot is added to the xref:security-settings.adoc[CSP and CORS allowlists] in ThoughtSpot. * Access to the Liveboard object that you want to embed. == Install the Swift Embed Package diff --git a/modules/ROOT/pages/mobile-embed.adoc b/modules/ROOT/pages/mobile-embed.adoc index dfcdfa3b1..7d22aa27a 100644 --- a/modules/ROOT/pages/mobile-embed.adoc +++ b/modules/ROOT/pages/mobile-embed.adoc @@ -18,15 +18,7 @@ Allows developers to embed ThoughtSpot content in an iOS native app. Allows developers to embed ThoughtSpot content in an Android native app. == Authentication and security settings -Currently, Mobile Embed SDKs support only cookieless authentication (`AuthType.TrustedAuthCookieless`) method to authenticate embed users. To handle authentication, you may have to token provider function or use your backend app to fetch a token for trusted authentication. For more information, see the Mobile Embed SDK quickstart guides. - -You must also add your embedding app domain to the following allowlists on the **Develop** > **Customizations** > **Security Settings** page in the ThoughtSpot UI. - -* CSP visual embed hosts -* Permitted iFrame domains -* CORS whitelisted domains - -For information about how to add your domains to CSP and CORS allowlists, see xref:security-settings.adoc[Security Settings]. +Currently, Mobile Embed SDKs support only cookieless authentication (`AuthType.TrustedAuthCookieless`) method to authenticate embed users. To handle authentication, you may have to token provider function or use your backend app to fetch a token for trusted authentication. For more information, see the respective Mobile Embed SDK quickstart guides. == Mobile embed customization diff --git a/modules/ROOT/pages/mobilesdk-quick-start.adoc b/modules/ROOT/pages/mobilesdk-quick-start.adoc index 68508c237..1d8935f6e 100644 --- a/modules/ROOT/pages/mobilesdk-quick-start.adoc +++ b/modules/ROOT/pages/mobilesdk-quick-start.adoc @@ -17,7 +17,6 @@ Before you begin, check the following: * link:https://docs.npmjs.com/downloading-and-installing-node-js-and-npm[NPM and Node.js are installed, window=_blank] on your system. * Your link:https://reactnative.dev/docs/environment-setup[React Native environment, window=_blank] is set up. * You can access a ThoughtSpot instance with administrator and developer credentials. + -Ensure that your host app embedding ThoughtSpot is added to the xref:security-settings.adoc[CSP and CORS allowlists] in ThoughtSpot. * You have access to the Liveboard object that you want to embed * If you are using Expo to build your application: @@ -410,7 +409,6 @@ Additionally, you can add a listener for `EmbedEvent.Error` and verify the logs. * In case of rendering issues, adjust the frame size constraints and rerun your app. * Check if your custom CSS specifications are applied correctly. - == Known limitations For information about supported features and known limitations, see xref:mobile-embed.adoc#_known_limitations[Mobile embed limitations]. diff --git a/modules/ROOT/pages/pendo-integration.adoc b/modules/ROOT/pages/pendo-integration.adoc index 94d40dd0b..d08c3afd2 100644 --- a/modules/ROOT/pages/pendo-integration.adoc +++ b/modules/ROOT/pages/pendo-integration.adoc @@ -177,7 +177,7 @@ To validate and test Pendo integration in your embed: image::./images/pendo-dev-console.png[Dev console verification] -- . 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 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 refer to the link:https://github.com/thoughtspot/developer-examples/blob/524ef13121fcae4756a951648e3e6dc4bb29aa26/visual-embed/pendo-integration/pendoIntegrationScript.js#L108[sample script provided by ThoughtSpot, window=_blank]. + +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 refer to the link:https://github.com/thoughtspot/developer-examples/blob/main/visual-embed/pendo-integration/pendoIntegrationScript.js[sample script provided by ThoughtSpot, window=_blank]. . Log in to Pendo to create a sample guide for your ThoughtSpot application instance. . In the ThoughtSpot UI, verify if the Pendo guide is published. + @@ -203,7 +203,7 @@ If the variables are not available: == 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://github.com/thoughtspot/developer-examples/tree/main/visual-embed/pendo-integration[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] * link:https://codesandbox.io/p/devbox/optimistic-mcclintock-lw2qq8[Code sandbox, window=_blank] diff --git a/modules/ROOT/pages/security-api.adoc b/modules/ROOT/pages/security-api.adoc index 5a4adb304..b703b5852 100644 --- a/modules/ROOT/pages/security-api.adoc +++ b/modules/ROOT/pages/security-api.adoc @@ -125,7 +125,16 @@ Response code [#shareviz] == Share a visualization with another user or user group -If you want to share a specific visualization from a Liveboard with another user or user group, use the `/tspublic/v1/security/shareviz` API. This API lets you share the visualization with specific user IDs and provide read-only access. +If you want to share a specific visualization from a Liveboard with another user or user group, use the `/tspublic/v1/security/shareviz` API. + +[IMPORTANT] +==== +* Sharing a visualization implicitly shares the entire Liveboard with the recipient. +* If email notifications for object sharing are enabled, a notification with a link to the shared visualization will be sent to the recipient’s email address. Although this link opens the shared visualization, recipients can also access other visualizations in the Liveboard. +* The `/tspublic/v1/security/shareviz` API endpoint provides only read-only access to the shared visualization. +==== + + === Resource URL ---- diff --git a/modules/ROOT/pages/trusted-auth-sdk.adoc b/modules/ROOT/pages/trusted-auth-sdk.adoc index eb3b02805..56275764a 100644 --- a/modules/ROOT/pages/trusted-auth-sdk.adoc +++ b/modules/ROOT/pages/trusted-auth-sdk.adoc @@ -13,10 +13,12 @@ When `init()` is called, the SDK checks if there is an existing ThoughtSpot sess Cookieless authentication, specified using `AuthType.TrustedAuthTokenCookieless`, uses the token as a bearer token for all subsequent requests to ThoughtSpot, without establishing a session in the browser. -Cookie-based authentication, specified using `AuthType.TrustedAuthToken`, uses the token to create a session in the browser immediately, and does not use the token afterward, instead relying on the established session with the ThoughtSpot instance. +Cookie-based authentication, specified using `AuthType.TrustedAuthToken`, uses the token to create a session in the browser immediately. It does not use the token afterward; instead, it relies on the established session with the ThoughtSpot instance. For the request to be *secure*, the user in the browser cannot modify the request or make their own valid request to the *token request service* in a way that requests a token for any other user. +The `autoLogin: true` property in the `init()` function causes the Visual Embed SDK to request a new token before the current token or the session expires, so that a user never sees the embedded ThoughtSpot component in a signed-out state. + == Define token request service There are two options in the `init()` function to define the request to the *token request service*: `authEndpoint` or `getAuthToken`. @@ -25,9 +27,9 @@ The `authEndpoint` parameter of the `init()` function specifies a URL for a dire Any authentication details must be included by the browser in this automated GET request, typically in the cookies. -It is *insecure* to allow specifying the username of the desired login token in the URL called by `authEndpoint`, because any user could request tokens for other users. Instead, the *token request service* itself must be able to determine which user is logged in from the backend. +It is *insecure* to allow specifying the username of the desired login token in the URL called by `authEndpoint`, because any user could request tokens for other users. Instead, the *token request service* must determine the logged-in user from the backend. -Cookies are not sent across domains (only to sub-domains), so your *token request service* must be *hosted in the same domain* as the embedding application. +Cookies are not sent across domains (only to subdomains), so your *token request service* must be *hosted in the same domain* as the embedding application. If you need more control beyond a GET request, use `getAuthToken` instead to define a customized request. @@ -40,8 +42,8 @@ The callback function must return a *Promise* that resolves with the *login toke ---- init({ thoughtSpotHost: "<%=tshost%>", - authType: AuthType.TrustedAuthToken, - username: "UserA", + authType: AuthType.TrustedAuthTokenCookieless, + autoLogin: true, getAuthToken: () => { // fetch() returns a Promise naturally. Assumes a JSON response from the token request service with a 'token' property return fetch('https://my-backend.app/ts-token') @@ -51,14 +53,13 @@ init({ }); ---- -You can even use the callback function to reference a hard-coded login token, in a testing or other appropriate situation. Remember, it must return a Promise that resolves with the token: +You can even use the callback function to reference a hard-coded login token in a testing or other appropriate situation. Remember, it must return a Promise that resolves with the token: [source,JavaScript] ---- init({ thoughtSpotHost: "<%=tshost%>", - authType: AuthType.TrustedAuthToken, - username: "", + authType: AuthType.TrustedAuthTokenCookieless, getAuthToken: () => { let tsToken = '{long-lived-token}'; return Promise.resolve(tsToken); @@ -90,7 +91,7 @@ The Visual Embed SDK provides a link:https://developers.thoughtspot.com/docs/Fun Please see the documentation on xref:rest-apiv2-js.adoc[REST API V2.0 within a browser] for further explanation and example code. === Multiple user sessions in one browser -Cookieless authentication is also useful for scenarios where the embedding application allows for being logged into multiple user accounts in different tabs, or quick switches between users. Cookie-based authentication restricts the whole browser to a single logged-in user per ThoughtSpot instance, while cookie-less allows each tab to use a different token without conflicts. +Cookieless authentication is also useful for scenarios where the embedding application allows for being logged into multiple user accounts in different tabs, or quick switches between users. Cookie-based authentication restricts the whole browser to a single logged-in user per ThoughtSpot instance, while cookieless allows each tab to use a different token without conflicts. == Code examples The only difference between cookie-based trusted authentication and cookieless authentication in the `init()` function is the value used for the `authType` property. @@ -104,38 +105,39 @@ The following example shows a custom callback function with a custom request usi let tsToken; // global scope to store token for other REST API requests init({ thoughtSpotHost: tsURL, - authType: AuthType.TrustedAuthTokenCookieless, - getAuthToken: getAuthToken - }); + authType: AuthType.TrustedAuthTokenCookieless, + getAuthToken: getAuthToken, + autoLogin: true +}); function async getAuthToken { - const tokenURL = tokenServiceURL + "/gettoken/"; - console.log("calling token server at " + tokenURL); - - const timeoutSecs = 5 * 1000; // seconds to milliseconds - - const response = await timeout(timeoutSecs, fetch( - tokenURL, - { - method: 'POST', - mode: 'cors', - cache: 'no-cache', - headers: { - // This Token Request Service returns the token as a plain-text string - 'Content-Type': "text/plain", - // Custom header for passing a JWT with auth details from the web app to the token request service - // Instead the token request service may have access to a user session with the details - 'X-Auth-Token': authJWT - }, - credentials: 'include' - } - )) - - // Token request service returns plain-text string of the token - // set the global tsToken variable for using the token for separate REST API requests - tsToken = response.text(); - // Must return for the Promise to be completed - return response.text() + const tokenURL = tokenServiceURL + "/gettoken/"; + console.log("calling token server at " + tokenURL); + + const timeoutSecs = 5 * 1000; // seconds to milliseconds + + const response = await timeout( + timeoutSecs, + fetch(tokenURL, { + method: 'POST', + mode: 'cors', + cache: 'no-cache', + headers: { + // This Token Request Service returns the token as a plain-text string + 'Content-Type': "text/plain", + // Custom header for passing a JWT with auth details from the web app to the token request service + // Instead the token request service may have access to a user session with the details + 'X-Auth-Token': authJWT + }, + credentials: 'include' + }) + ) + + // Token request service returns plain-text string of the token + // set the global tsToken variable for using the token for separate REST API requests + tsToken = response.text(); + // Must return for the Promise to be completed + return response.text() } ---- @@ -146,8 +148,8 @@ function async getAuthToken { init({ thoughtSpotHost: "", authType: AuthType.TrustedAuthToken, - username: "", authEndpoint: "https://authenticator-server:/endpoint", + autoLogin: true }); ---- @@ -156,12 +158,12 @@ init({ init({ thoughtSpotHost: "", authType: AuthType.TrustedAuthToken, - username: "", + autoLogin: true, getAuthToken: () => { return fetch('https://my-backend.app/ts-token') .then((response) => response.json()) .then((data) => data.token); - }); +}); ---- === Cookieless authentication examples @@ -172,6 +174,7 @@ init({ thoughtSpotHost: "", authType: AuthType.TrustedAuthTokenCookieless, authEndpoint: "https://authenticator-server:/endpoint", + autoLogin: true }); ---- @@ -181,10 +184,11 @@ init({ init({ thoughtSpotHost: "", authType: AuthType.TrustedAuthTokenCookieless, + autoLogin: true, getAuthToken: () => { return fetch('https://my-backend.app/ts-token') .then((response) => response.json()) .then((data) => data.token); } - }); +}); ---- diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index 40437acc7..d7955f3a7 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -8,6 +8,10 @@ This page lists new features, enhancements, and deprecated functionality in ThoughtSpot Embedded instances. +== Version 26.2.0.cl + +The ThoughtSpot Cloud 26.2.0.cl version is now available for ThoughtSpot Embedded instances. For information about the new features and enhancements introduced in this release, see link:https://developers.thoughtspot.com/docs/26.2.0.cl?pageid=whats-new[26.2.0.cl Developer Documentation, window=_blank]. + == Version 10.15.0.cl === Theme Builder diff --git a/modules/tutorials/pages/react-components/react-components_intro.adoc b/modules/tutorials/pages/react-components/react-components_intro.adoc index 4cdc5e771..de5cfe70e 100644 --- a/modules/tutorials/pages/react-components/react-components_intro.adoc +++ b/modules/tutorials/pages/react-components/react-components_intro.adoc @@ -23,7 +23,11 @@ There are many great resources for understanding React itself, including the lin React projects almost always use many different packages on top of the baseline "React" install. -Within the tutorial, all packages will be given a brief explanation, with links to the respective project documentation. +Primarily, the example app is built using link:https://nextjs.org/[Next.js], one of the most widely used React frameworks. The structure of the app, including routing, takes into account the features and patterns of Next.js, but using Next.js is not a requirement to use ThoughtSpot's React components. + +The example app also uses link:https://flowbite-react.com/[Flowbite, window=_blank] for pre-defined UI components and link:https://tailwindcss.com/docs/installation/framework-guides/nextjs[Tailwind CSS, window=_blank] as a unified styling system. + +Most of the `className` references in the example app are specific to Tailwind's predefined classes and can be removed when adding code into your own application. Nothing within the example related to ThoughtSpot depends on Tailwind or the Flowbite components. == Routes and pages *Routes* are URLs that load different "pages" within the app. @@ -91,6 +95,11 @@ link:https://github.com/thoughtspot/embed-example-react-app/blob/main/src/lib/co The `constants` const is declared and exported with several properties, the most important of which is `tsURL`, because it configures the ThoughtSpot instance from which the content will load. +[WARNING] +==== +You must include *https://* in the `tsURL` string to avoid browser redirect issues. +==== + [source,typescript] ---- export const constants = { diff --git a/modules/tutorials/pages/react-components/react-components_lesson-01.adoc b/modules/tutorials/pages/react-components/react-components_lesson-01.adoc index ba0d4a6ff..572cbcc5e 100644 --- a/modules/tutorials/pages/react-components/react-components_lesson-01.adoc +++ b/modules/tutorials/pages/react-components/react-components_lesson-01.adoc @@ -32,7 +32,9 @@ return ( ); ---- -The `tsInitialize()` function wraps around the entire process of calling the `init()` function from the Visual Embed SDK (note that authentication has not been implemented in this example): +The `tsInitialize()` function wraps around the entire process of calling the `init()` function from the Visual Embed SDK. + +Please note that authentication has not been implemented in this example. You must be signed into ThoughtSpot already in another tab in your browser. Production-level xref:embed-authentication.adoc[authentication methods] are covered elsewhere in the documentation. [source,typescript] ---- @@ -43,13 +45,11 @@ The `tsInitialize()` function wraps around the entire process of calling the `in // See https://developers.thoughtspot.com/docs/Interface_EmbedConfig for all configurations const ee = init({ thoughtSpotHost: constants.tsURL, - authType: AuthType.None, - username: constants.username, - getAuthToken: () => { - return getAuthToken(constants.username); - }, callPrefetch: true, customizations: {}, + authType: AuthType.None + // getAuthToken: () => { return Promise.resolve('{tokenCopiedFromPlayground}'); } , + // autoLogin: true, } as EmbedConfig); // Checks for Auth process completed as expected @@ -67,6 +67,11 @@ The `tsInitialize()` function wraps around the entire process of calling the `in }; ---- +[NOTE] +==== +When running the tutorial app locally, it is expected behavior to see duplicated calls and messages in the browser Developer Tools. Next.js is running in development mode using React Strict Mode, which automatically renders components twice, causing the duplication. +==== + == Common customizations in the init As mentioned above, link:https://developers.thoughtspot.com/docs/Interface_EmbedConfig[many configuration options] can be specified as part of the `init()` function. diff --git a/modules/tutorials/pages/react-components/react-components_lesson-03.adoc b/modules/tutorials/pages/react-components/react-components_lesson-03.adoc index 1340166f2..9baf18f7b 100644 --- a/modules/tutorials/pages/react-components/react-components_lesson-03.adoc +++ b/modules/tutorials/pages/react-components/react-components_lesson-03.adoc @@ -245,7 +245,7 @@ When this page renders, there is now a dynamic menu to get to any Liveboard the == Spotter embed pages and menu The example app contains an equivalent menu and component display page for Spotter content, under the link:https://github.com/thoughtspot/embed-example-react-app/tree/main/src/app/datachat[/app/datachat/^] subdirectory. -Spotter conversations are started against Models (formerly Worksheets), so the set of UI components and filters differs within the link:https://github.com/thoughtspot/embed-example-react-app/blob/main/src/app/datachat/page.tsx[menu page^]. +Spotter conversations are started against Models, so the set of UI components and filters differs within the link:https://github.com/thoughtspot/embed-example-react-app/blob/main/src/app/datachat/page.tsx[menu page^]. The basic concepts from the entire tutorial apply regardless of which component you are using. diff --git a/scripts/Converter/index.ts b/scripts/Converter/index.ts index 955ad1be6..05a35fb45 100644 --- a/scripts/Converter/index.ts +++ b/scripts/Converter/index.ts @@ -155,32 +155,29 @@ const _indent = ( // All the parse functions are to be used internally (its used to get sub content) class TypeDocInternalParser { - static convertToItalic = (name: string | undefined) => - name ? `_${name}_` : ''; + static convertToItalic = (name: string | undefined) => (name ? `_${name}_` : ''); - static convertNameToLink: ( - node: string | undefined, - includeParent?: boolean, - ) => string; + static convertNameToLink: (node: string | undefined, includeParent?: boolean) => string; - static GITHUB_LINK = - 'https://github.com/thoughtspot/visual-embed-sdk/blob/main/src'; + static GITHUB_LINK = 'https://github.com/thoughtspot/visual-embed-sdk/blob/main/src'; static covertTypeDocText = (text: string) => { - // convert all {@link Name.hash} - // to xref:Name.adoc#hash[Name] - const matches = text.match(/{@link\s[^{]+}/g); - if (!matches) return text; - const updatedText = matches?.reduce((prevUpdatedText, curLinkText) => { - const linkTo = curLinkText.split(/\s/)[1].replace('}', ''); - const newLinkText = this.convertNameToLink(linkTo, true); + // 1) Convert Markdown links -> AsciiDoc links + const updated = text.replace( + /\[([^\]]+)\]\((https?:\/\/[^)]+)\)/g, + 'link:$2[$1]', + ); - if (!newLinkText) return prevUpdatedText; + // 2) Existing logic: convert {@link Name.hash} -> xref:... + const matches = updated.match(/{@link\s[^{]+}/g); + if (!matches) return updated; + return matches.reduce((prevUpdatedText, curLinkText) => { + const linkTo = curLinkText.split(/\s/)[1].replace(/}/g, ''); + const newLinkText = this.convertNameToLink(linkTo, true); + if (!newLinkText) return prevUpdatedText; return prevUpdatedText.replace(curLinkText, newLinkText); - }, text); - - return updatedText; + }, updated); }; // function to parse a tag @@ -195,7 +192,7 @@ class TypeDocInternalParser { if (tag.tag === 'example') return `${tag.text}\n`; if (tag.tag === 'param') { - return `\nParameter::\n${tag.text}\n`; + return `\nParameter::\n${this.covertTypeDocText(tag.text)}\n`; } if (tag.tag === 'deprecated') { return `[deprecated]#Deprecated : ${tag.text.replace( diff --git a/src/components/AnnouncementBanner/index.scss b/src/components/AnnouncementBanner/index.scss new file mode 100644 index 000000000..bff42281f --- /dev/null +++ b/src/components/AnnouncementBanner/index.scss @@ -0,0 +1,38 @@ +.announcementBanner { + width: 100%; + border-bottom: 1px solid var(--border-color); + background: #dce5f9; + color: var(--primary-color); +} + +.announcementBanner__inner { + display: flex; + gap: 12px; + align-items: center; + justify-content: center; + padding-top: 10px; + padding-bottom: 10px; +} + +.announcementBanner__content { + font-size: 15px; + line-height: 21px; + text-align: center; + flex: 1 1 auto; + font-weight: 500; + color: #4b5563; +} + +.announcementBanner__link { + color: #1a73e8; + text-decoration: underline; + font-size: 15px; +} + +@media screen and (max-width: 767px) { + .announcementBanner__inner { + flex-direction: column; + align-items: flex-start; + } +} + diff --git a/src/components/AnnouncementBanner/index.tsx b/src/components/AnnouncementBanner/index.tsx new file mode 100644 index 000000000..e88c22e38 --- /dev/null +++ b/src/components/AnnouncementBanner/index.tsx @@ -0,0 +1,24 @@ +import React from 'react'; +import './index.scss'; + +type AnnouncementBannerProps = { + enabled?: boolean; + message: React.ReactNode; +}; + +const AnnouncementBanner = (props: AnnouncementBannerProps) => { + const { enabled = true, message } = props; + + if (!enabled) return null; + + return ( +
+
+
{message}
+
+
+ ); +}; + +export default AnnouncementBanner; + diff --git a/src/components/DevDocTemplate/index.tsx b/src/components/DevDocTemplate/index.tsx index be6ea8441..03d1b953e 100644 --- a/src/components/DevDocTemplate/index.tsx +++ b/src/components/DevDocTemplate/index.tsx @@ -23,6 +23,7 @@ import { getAlgoliaIndex } from '../../configs/algolia-search-config'; import RenderPlayGround from './playGround/RESTAPI'; import GraphQLPlayGround from './playGround/GraphQL'; import { AskDocs } from './askDocs'; +import AnnouncementBanner from '../AnnouncementBanner'; import { TS_HOST_PARAM, TS_ORIGIN_PARAM, @@ -34,6 +35,7 @@ import { DEFAULT_PREVIEW_HOST, DEFAULT_APP_ROOT, HOME_PAGE_ID, + HOME_ANNOUNCEMENT_BANNER, CUSTOM_PAGE_ID, BUILD_ENVS, VERSION_DROPDOWN, @@ -251,6 +253,10 @@ const DevDocTemplate: FC = (props) => { } url.searchParams.set('pageid', e.data.params.pageid); + const hash = e.data.subsection; + if (hash) { + url.hash = hash; + } window.history.replaceState({}, '', url.toString()); } } @@ -487,6 +493,82 @@ const DevDocTemplate: FC = (props) => { return cName; }; + const getCloudLatestVersion = () => { + const cloudLatest = VERSION_DROPDOWN?.find( + (v) => v?.subLabel && v.subLabel.toLowerCase().includes('cloud (latest)'), + ); + return cloudLatest?.label; + }; + + const extractVersionString = (text: string | undefined | null) => { + if (!text) return undefined; + // Matches versions like 26.2.0.cl or 10.15.0.cl / 10.10.0.sw + const match = text.match(/\b\d+\.\d+\.\d+\.(?:cl|sw)\b/i); + return match?.[0]?.toLowerCase(); + }; + + const getVersionFromPath = (pathname?: string) => { + if (!pathname) return undefined; + const normalizedPath = pathname.toLowerCase(); + + const versionFromOptions = VERSION_DROPDOWN?.find((option) => { + const link = option?.link?.trim(); + if (!link || link === '') return false; + + const linkPath = link.startsWith('/') ? link : `/${link}`; + const hyphenPath = link.replace(/\./g, '-'); + const hyphenPathWithSlash = hyphenPath.startsWith('/') + ? hyphenPath + : `/${hyphenPath}`; + + return ( + normalizedPath.includes(linkPath.toLowerCase()) || + normalizedPath.includes(hyphenPathWithSlash.toLowerCase()) + ); + }); + + const optionVersion = + extractVersionString(versionFromOptions?.label) || + extractVersionString(versionFromOptions?.link); + if (optionVersion) return optionVersion; + + return extractVersionString(normalizedPath.replace(/-/g, '.')); + }; + + const getVersionFromHost = (hostname?: string) => { + if (!hostname) return undefined; + return extractVersionString(hostname.replace(/-/g, '.').toLowerCase()); + }; + + const getCurrentDocVersion = () => + getVersionFromPath(location?.pathname) || getVersionFromHost(location?.hostname); + + const shouldShowAnnouncementBanner = () => { + if (!isPublicSiteOpen) return false; + if (!HOME_ANNOUNCEMENT_BANNER?.enabled) return false; + + const cloudLatest = extractVersionString(getCloudLatestVersion()); + const bannerVersion = + extractVersionString(HOME_ANNOUNCEMENT_BANNER?.linkText) || + extractVersionString(HOME_ANNOUNCEMENT_BANNER?.message) || + extractVersionString(HOME_ANNOUNCEMENT_BANNER?.linkHref); + const currentDocVersion = getCurrentDocVersion(); + + // Only hide when we can confidently compare and they match. + if (cloudLatest && bannerVersion && cloudLatest === bannerVersion) return false; + if (currentDocVersion && bannerVersion && currentDocVersion === bannerVersion) { + return false; + } + return true; + }; + + const isExternalLink = (href?: string) => /^https?:\/\//i.test(href || ''); + const shouldOpenBannerLinkNewTab = (href?: string) => + Boolean(HOME_ANNOUNCEMENT_BANNER?.openInNewTab) || isExternalLink(href); + const bannerLinkOpensInNewTab = shouldOpenBannerLinkNewTab( + HOME_ANNOUNCEMENT_BANNER?.linkHref, + ); + return ( <> @@ -511,6 +593,38 @@ const DevDocTemplate: FC = (props) => { : { height: '0px' } } > + {shouldShowAnnouncementBanner() && ( + + {HOME_ANNOUNCEMENT_BANNER?.linkHref && + HOME_ANNOUNCEMENT_BANNER?.linkText && ( + + {HOME_ANNOUNCEMENT_BANNER.linkText} + + )} + {(HOME_ANNOUNCEMENT_BANNER?.linkHref && + HOME_ANNOUNCEMENT_BANNER?.linkText) && ' '} + {HOME_ANNOUNCEMENT_BANNER?.message || + (VERSION_DROPDOWN?.[0]?.label + ? `Version ${VERSION_DROPDOWN[0].label} is now available!` + : 'A new version is now available!')} + + } + /> + )}
} diff --git a/src/components/VersionIframe/index.tsx b/src/components/VersionIframe/index.tsx index fa818aaae..e6e23eaa3 100644 --- a/src/components/VersionIframe/index.tsx +++ b/src/components/VersionIframe/index.tsx @@ -34,11 +34,14 @@ const VersionIframe: React.FC = ({ } else if (mainUrlParams.has('pageId')) { url.searchParams.set('pageid', mainUrlParams.get('pageId')); } + if (location?.hash) { + url.hash = location?.hash; + } url.searchParams.set('_iframe', '1'); } return url.toString(); - }, [iframeUrl, isDarkMode, location?.search]); + }, [iframeUrl, isDarkMode, location?.search, location?.hash]); return (
diff --git a/src/configs/doc-configs.js b/src/configs/doc-configs.js index 783645484..96855667b 100644 --- a/src/configs/doc-configs.js +++ b/src/configs/doc-configs.js @@ -13,6 +13,19 @@ module.exports = { NOT_FOUND_PAGE_ID: '404-error', HOME_PAGE_ID: 'introduction', NOT_FOUND_GO_HOME_PAGE_ID: 'introduction', + HOME_ANNOUNCEMENT_BANNER: { + enabled: true, + message: + 'is now available. Read about the new features and enhancements.', + // Swap this between: + // - Pre-GA: release-specific URL (full http(s) URL), ex: + // 'https://developers.thoughtspot.com/docs/26.2.0.cl?pageid=whats-new' + // - GA: ' /docs/whats-new' + //linkHref: '/docs/whats-new', + linkHref: '/docs/26.2.0.cl?pageid=whats-new', + linkText: 'Version 26.2.0.cl', + openInNewTab: true, + }, TYPE_DOC_PREFIX: 'typedoc', DEFAULT_HOST: 'https://try-everywhere.thoughtspot.cloud', DEFAULT_PREVIEW_HOST: 'https://try-everywhere.thoughtspot.cloud/v2', @@ -63,7 +76,12 @@ module.exports = { subLabel: 'Software', iframeUrl: 'https://visual-embed-sdk-10-1.vercel.app/docs/', }, - + { + label: '26.2.0.cl', + link: '26.2.0.cl', + subLabel: 'Coming soon', + iframeUrl: 'https://developer-docs-26-2-0-cl.vercel.app/docs/', + }, ], CUSTOM_PAGE_ID: { API_PLAYGROUND: 'restV2-playground', diff --git a/src/intl/en.json b/src/intl/en.json index 5ba29665c..1e395a360 100644 --- a/src/intl/en.json +++ b/src/intl/en.json @@ -13,7 +13,7 @@ "CODE_COPY_BTN_HOVER_TEXT": "Copy to clipboard", "CODE_COPY_BTN_AFTER_CLICK_TEXT": "Copied!", "RIGHT_NAV_SIDERBAR_TITLE": "On this page", - "COPYRIGHT_TEXT": "© 2025 ThoughtSpot Inc. All Rights Reserved.", + "COPYRIGHT_TEXT": "© 2026 ThoughtSpot Inc. All Rights Reserved.", "KEYWORD_NOT_FOUND_MSG": "Sorry. We could not find a match for", "HEADER_BANNER_MAIN": "ThoughtSpot Embedded Documentation", "SEARCH_HINT_1": "Press", diff --git a/static/doc-images/images/v1-experience.png b/static/doc-images/images/v1-experience.png new file mode 100644 index 000000000..9777eb044 Binary files /dev/null and b/static/doc-images/images/v1-experience.png differ diff --git a/static/doc-images/images/v2-experience.png b/static/doc-images/images/v2-experience.png new file mode 100644 index 000000000..00c403ad6 Binary files /dev/null and b/static/doc-images/images/v2-experience.png differ diff --git a/static/doc-images/images/v3-experience.png b/static/doc-images/images/v3-experience.png new file mode 100644 index 000000000..3f988376c Binary files /dev/null and b/static/doc-images/images/v3-experience.png differ