Visual Embed SDK changelog

The Visual Embed SDK 1.50.0 introduces the SpotterVizConfig interface and SpotterVizStarterPrompt interface to allow embed developers to customize the SpotterViz panel on embedded Liveboards and full-application embeds.

A new SpotterVizConfig interface is available on LiveboardViewConfig and AppViewConfig for the spotterViz object. This object provides branding customization controls for customizing the SpotterViz panel experience.

To customize app interactions, visibility of the UI elements, and style and appearance of the SpotterViz panel, the SDK also introduces CSS variables, action IDs, and embed and host event identifiers. For more information, see SpotterViz in embedded Liveboards.

For full application embedding, ThoughtSpot provides a focused and streamlined home page experience. To enable this feature, use the HomePage.Focused option with the homePage attribute in the discoveryExperience object.

For more information, see Customize full application embedding.

The SDK introduces the visualOverrides object in SearchViewConfig and AppViewConfig, enabling embed developers to apply chart and table display customizations to the new answers from an embedded Search data interface at initialization time.

The visualOverrides object provides the following customization controls to modify the chart and table display:

For more information, see Visualization overrides.

For embedded Liveboards, the SDK provides enableLiveboardDataCache to clear browser cache and fetch new data for the visualizations on the Liveboard.

The SDK also provides the following events and action ID to programmatically trigger cache refresh and control the visibility of the Refresh button.

For more information, see Enable Liveboard refresh.

The SDK introduces the following configuration parameters in SpotterChatConfig object to enable and control file uploads in the embedded Spotter chat interface.

For more information, see Allowing file uploads in Spotter chats.

The SDK includes the following new features and enhancements in Liveboard embedding.

The SDK introduces the following action IDs to control the visibility of specific UI components in chat panel of the embedded Spotter interface:

Note the following changes:

Spotter chat history sidebar customization

The SDK introduces the SpotterSidebarViewConfig interface and the spotterSidebarConfig object with configuration controls to customize the appearance and contents of the chat history panel. Developers can use the following properties in the spotterSidebarConfig object to enable or disable chat history panel and customize the contents of the sidebar when enabled:

Standalone enablePastConversationsSidebar attribute in Spotter embed

The standalone enablePastConversationsSidebar property on SpotterEmbedViewConfig and AppViewConfig is deprecated from SDK 1.47.0 and ThoughtSpot 26.4.0.cl.

Use enablePastConversationsSidebar in the spotterSidebarConfig instead. When both are defined, the property in the spotterSidebarConfig object takes precedence.

enablePastConversationsSidebar: false,

spotterSidebarConfig: {
    enablePastConversationsSidebar: true,
    //... other config properties
}

Spotter chat UI branding

The SDK introduces the SpotterChatViewConfig interface for customizing branding in Spotter tool response cards. You can pass these parameters as the spotterChatConfig object properties in SpotterEmbed, AppEmbed, or LiveboardEmbed where Spotter interface is used.

Liveboard embed enhancements

Option to include current period in rolling date filters

If the current period inclusion in rolling date filters feature is enabled on your instance, the rolling date filters options such as Last <N> <period> and Next <N> <period> for the Liveboards and Answers in the embed view will allow you to include current period. For example, when you define a date range such as "Last 2 months", the date filter interface displays the Include this month checkbox. To disable this feature, use the isThisPeriodInDateFiltersEnabled setting. To hide, show, or disable this option in the embed view, use the action ID, Action.IncludeCurrentPeriod.

Host events with page context framework

The Visual Embed SDK introduces the HostEvent V2 framework for improved handling and execution of host events in embedded ThoughtSpot experiences with multi-layer UI interactions. The v2 framework supports the page context feature, which tracks the top-most active layer in the user’s current context. Developers can use this feature to route events based on the user’s current context or set a specific target context for precise and predictable handling of host events.

For more information, refer to the Host events documentation.

dataPanelV2

The dataPanelV2 parameter is deprecated and can no longer be used to switch between the classic and new data panel experience. By default, the new data panel v2 experience is enabled on all ThoughtSpot embedded instances.

Spotter experience The SDK includes the following parameters, action IDs, and events to customize the Spotter embed experience.

Liveboard experience enhancements

Spotter enhancements

You can now embed the Spotter 3 experience in your application and use features such as Auto mode for automatic data model selection, chat history, and a new chat prompt interface.

For more information, see Embedding Spotter and Features available with Spotter 3 experience.

Liveboard experience enhancements

Publishing objects

The following action IDs are available for the data publishing menu actions in the Data workspace page:

Error handling improvements

To handle errors in the embedding workflows, the SDK includes the following features:

For more information, see EmbedErrorCodes and ErrorDetailsTypes.

Intercepting API calls
The SDK provides the following attributes to intercept API calls and handle interception via events and custom workflows:

For more information, see Intercept API calls and search requests.

Code-based custom actions

The following enumerations are available for code-based custom actions:

Runtime overrides in Spotter embed

The Visual Embed SDK now supports runtime overrides in Spotter embed.

PNG images in Liveboard schedule notifications
To enable embedding PNG images of Liveboards in scheduled job notifications sent to subscribers, the SDK provides the isPNGInScheduledEmailsEnabled boolean parameter. When set to true, scheduled emails will include a PNG image of the Liveboard.

The SDK also provides the following action IDs:

Spotter embed

React component for Spotter Agent embed

The Visual Embed SDK now supports embedding Spotter Agent feature without a body or Spotter interface in a React app. For ease of implementation, the SDK also provides a custom React hook, useSpotterAgent.

For more information, see Spotter Agent embedding in a React app.

Event handlers for Spotter embed

The following event handlers are now available for Spotter embed:

For more information, see EmbedEvent and HostEvent.

Event handlers for Spotter Agent embed

You can now use the following host events in Spotter Agent embedding:

For more information, see HostEvent.

Lazy loading of visualizations on an embedded Liveboard

You can now use the lazyLoadingForFullHeight parameter with the fullHeight to progressively load visualizations on an embedded Liveboard. When both these attributes are enabled, only the visualizations in the current viewport are loaded initially, while the other visualizations load as the user scrolls the Liveboard page.

You can also set the margin property for lazy loading to define when the visualization should load.

For more information, see Lazy loading of visualizations in an embedded Liveboard.

Full application embed

You can now enable the persona-based left navigation panel and home page experience on your ThoughtSpot instance. This feature is disabled by default on ThoughtSpot instances and is available for Early Access. When it’s enabled on your ThoughtSpot instance, you can roll out the new experience on embedding applications by configuring the discoveryExperience attribute.

When enabled, the left navigation panel organizes the application menu into persona-based contextual sections. For example, the Insights icon for business users, the Data Workspace icon for Analysts and Data engineers, and the Develop icon for developers. Your application users can navigate to each option using the tabs in the left navigation panel. The new interface also provides a slider to allow users to view or hide the left navigation panel.

Fullscreen presentation mode controls for embedded Liveboards and visualizations
Developers can now control whether a visualization or Liveboard can be presented in full screen mode using the disableFullscreenPresentation attribute. By default, the full screen mode is disabled on embedded Liveboards and visualizations.

PDF download settings
Developers can now control the display of Include cover page and Include filter page(s) options on the Download PDF dialog for Liveboards. The Include cover page and Include filter page(s) options are disabled by default on ThoughtSpot instances. When this feature is enabled, developers can use the coverAndFilterOptionInPDF attribute to show or hide these options for the Liveboard users in their embedding app.

Parameter for overriding a default primary action

If Spotter is enabled on your instance, the Spotter button appears by default as the primary action on embedded Liveboard charts; if Spotter is not enabled, the Explore button is set as the primary action. If you want to replace the primary action with a different action, you can now use the primaryAction attribute.

For more information, see Override default primary action.

Full application embed experience enhancements

The SDK now includes the hideObjectSearch property, which allows developers to hide the object search button in the navigation bar when embedding the full application.

Host events

In this version, the SDK introduces the following host event handlers:

For more information, see HostEvent.

Events support for Spotter embed

You can now use the following host events in Spotter embed:

For more information, see HostEvent.

Lazy loading with full height

The SDK introduces lazyLoadingForFullHeight parameter, which enables progressive loading of visualizations on an embedded Liveboard. This parameter works in conjunction with the fullHeight attribute. When both these attributes are enabled, only the visualizations in the current viewport are loaded initially, while the other visualizations load as the user scrolls the Liveboard page.

Spotter embed components with new names
The following Spotter embed components are now deprecated and replaced with new components in the SDK and Visual Embed Playground:

The deprecated components with old names in the existing Spotter embed implementations will continue to function until further notice. For code samples with new component names, see Spotter embed documentation.

Action ID for Spotter in-conversation training
For ThoughtSpot instances that have the new Spotter in-conversation training workflow enabled, the SDK provides the action ID Action.InConversationTraining to manage the visibility of the Add to Coaching button on Answers generated from Spotter prompts.

Events support for Spotter embed

The following embed events are also supported in Spotter embed:

For more information, see EmbedEvent.

String IDs for text customization
Developers can now customize a specific occurrence of a visible text string in the ThoughtSpot UI using the stringIDs object in the customization interface.

To locate the string IDs, SDK provides the exposeTranslationIds attribute. By setting exposeTranslationIds to true in the Playground, you can find the string ID of the UI text and use it in your customization code.

Additionally, the SDK provides the StringIDsUrl attribute to allow using a JSON file with string IDs and custom strings to override the visible text in the UI.

For more information, see Customize text strings.

Hide columns on list pages

In full app embedding, you can now hide the following columns on the Liveboards and Answers listing pages using the hiddenListColumns array:

For more information, see Customize full application embed.

The SDK now provides the customVariablesForThirdPartyTools setting to pass custom variables when integrating third-party tools and running custom scripts in your embed. Developers can define this object in the init() function and add variables as key-value pairs. This feature is available only if third-party integration is enabled on your instance and the script hosting domain URL is added to the CSP allowlist.

For more information, see Integrate third-party tools and allow custom scripts.

You can now exclude search token string from the application URL by setting excludeSearchTokenStringFromURL to true in your embed with ThoughtSpot token-based Search or Search bar.

This version of the SDK supports the following embed and host events:

The following HostEvents now allow custom parameters to set object properties programmatically:

For more information, see Host Events documentation.

For more information about Spotter customization, see Customize styles.

The SDK now provides the isUnifiedSearchExperienceEnabled setting to customize the Search experience on ThoughtSpot Home page for embedding application users:

For more information, see Search interface on the Home page in full application embedding.

The overrideOrgId parameter in the SDK provides the ability to override Org context for embedding application users. This parameter allows users authenticated to an Org to temporarily view content from another Org. Before specifying the Org ID for override, make sure the Per Org URL feature is enabled on your ThoughtSpot instance. To enable Per Org URL on your instance, contact ThoughtSpot Support.

You can now embed the following ThoughtSpot Spotter components in your app:

For more information, see Embed Spotter and Integrate Spotter into your chatbot.

The following parameters and enumerations are available for customizing Liveboard experience:

The following parameters are available for customizing Search experience:

The following settings are available for customizing the new home page and navigation experience in full app embedding:

You can now customize the search experience for the embedded ThoughtSpot Home page using homePageSearchBarMode. By default, the Home page includes the Object Search bar, which allows finding popular Liveboards and Answers.

You can set the homePageSearchBarMode property to one of the following options:

The SDK now allows you to set the focus on the Search bar or outside the Search bar when rendering the embedded Search page. Use the focusSearchBarOnRender property to set the position of the cursor focus.

The SDK includes the following Event and Action enumeration members:

The following new action enumerations are available in this version:

You can now enable enable2ColumnLayout on a Liveboard to adjust the page view according to the width and resolution of users' devices.

Runtime filters

CSS variables for new homepage experience

For more information, see CSS variables and overrides.

Ask Sage

With Ask Sage ^Beta embedded application users can ask follow-up questions on a visualization generated from a Natural Language Search query, converse with AI analyst, and refine results. To enable this feature, set enableAskSage to true.

The SDK includes the following new enumeration members in v1.28.0:

To access the new Home page and global navigation experience in the full application embedding, you can use the modularHomeExperience property in the SDK. The modular homepage experience is turned off by default and is available as an Early Access feature in 9.12.5.cl release. When modularHomeExperience is set to true, you can use the following parameters in the SDK to control the application experience:

For more information, see Customize full application embedding and AppViewConfig.

The following embed event is available from the v1.28.0 onwards:

EmbedEvent.Rename
Emits when an embedded Liveboard or visualization is renamed.

TML actions

The following TML menu actions are now grouped under TML sub-menu of the More menu on Answer page.

To show, hide, or disable these actions in the embedded mode, use the following format:

 // to show the TML menu and its sub-menu options
visibleActions: [Action.TML, Action.ExportTML, Action.EditTML]

 // to hide all TML actions
hiddenActions: [Action.TML]

 // to disable all TML actions
disabledActions: [Action.TML]

The following action enumeration members are available from v1.27.9 and v1.27.10:

For more information, see Action.

You can now use HostEvent.GetAnswerSession to get Answer session data for a Search Answer or Liveboard Visualization in the embedded view.

The SageEmbed package is now available on all clusters. You can use this SDK package to embed Natural Language Search capabilities and assist users with AI-suggested queries and AI-generated answers. This SDK package also allows you to customize the Natural Language Search experience in the embedded view.

For a complete list of methods, functions, interface objects, and properties, see the following pages:

The HostEvent.DrillDown now supports the vizId parameter to trigger a drill-down action on a specific visualization of a Liveboard. For more information, see DrillDown.

The new version of the SDK introduces the following new enumeration members:

The SDK provides AnswerService class to trigger the answer service with a custom action payload. You can use this service to run GraphQL queries in the context of the Answer with a custom action trigger. For more information, see AnswerService. Recommended ThoughtSpot application version is 9.10.0.cl.

The following object properties and feature flags are introduced in the LiveboardEmbed and AppEmbed SDK packages:

The new version of the SDK supports the following events:

The SDK introduces the following action enumeration members:

For more information, see Actions.

The SDK introduces the following action enumeration members:

For more information, see Actions.

ThoughtSpot now provides the SageEmbed package to embed the ThoughtSpot Search page with Sage features such as natural language search and AI-suggested search examples. This feature is in beta and not available in the Visual Embed Playground.

The HostEvent.SetActiveTab event in the upcoming version of the SDK allows you to set a tab as an active tab on a Liveboard.

The SDK supports the following performance optimization enhancements:

The new version of the SDK introduces the TrustedAuthTokenCookieless authType property to allow Cookieless embedding. The Cookieless authentication method allows using a bearer token to identify the signed-in user instead of session cookies.

For more information, see Cookieless authentication.

The new version of the SDK allows you to block user access to the non-embedded instance of the ThoughtSpot application. In full app embed deployments, you can use the blockNonEmbedFullAppAccess property in the SDK to restrict or allow your application users from accessing ThoughtSpot pages in the non-embed mode.

For more information, see Block access to non-embedded ThoughtSpot pages.

The new version of the SDK introduces the following action enumeration members:

For more information, see Action reference.

The SDK introduces the following events:

For more information, see Events.

The following events are deprecated from version 1.21.0 onwards.

You can use the DownloadAsPng, DownloadAsXlsx, DownloadAsCsv and DownloadAsPdf events for download actions.

For more information, see Events reference.

The SDK includes new attributes to customize the experience for embedded app users:

The dataSources property in SearchEmbed and SearchBarEmbed is deprecated and replaced with the dataSource attribute. The SDK supports searching from a single data source only.

The embed SDK packages now include the insertAsSibling property. This attribute can be used to insert the embedded object as a sibling to the element inside the target container.

The customCSS property in the customizations object supports new variables to customize the styles for dialogs, search bar, search navigation and search suggestions panels. For more information, see Customize CSS.

The new Liveboard experience mode introduces changes to the data format of the JSON response payload triggered by callback custom actions. For example, the reportBookData, and vizData attributes are modified, and the custom action id now is part of the data attribute. These changes may break your current custom action event handlers. For interoperability, we recommend adding the data attribute to payload in your code as shown in the example here:

liveboardEmbed.on(EmbedEvent.CustomAction, payload => {
    if (payload.id === "callback-action-id" || payload.data.id === "callback-action-id") {
        console.log('Custom Action event:', payload.data);
    }
})

You may also want to update the data classes in your scripts to process the JSON response payload and handle complex data. For more information, see Callback custom actions.

The new version of the SDK introduces the following Host events:

For more information, see Host events.

The noRedirect property in the SDK is deprecated and replaced with the inPopup attribute. When set to true, the inPopup attribute allows the SAML SSO authentication flow in a pop-up window.

For more information, see SAML Redirection.

The new version of the SDK provides the SearchBarEmbed JavaScript package to embed only the ThoughtSpot Search bar in your app.

For more information, see Embed ThoughtSpot search bar.

The customCSS property in the customizations object supports new variables to customize the UI elements on Liveboard, visualization, and Answer pages. You can also use these variables to define custom styles in the CSS file.
For more information, see Customize CSS.

The new version of the SDK introduces the following enums in the Action object:

You can use these enums to show, hide, or disable Sync to sheets, Sync to other apps, and Manage pipelines menu actions on a Liveboard visualization or Answer.

For more information, see Actions.

The AuthType property is modified and supports new enums.

To use your current SAML or OIDC authentication setup and redirect users to the IdP for authentication within the embedded iFrame, you can now use AuthType.EmbeddedSSO.
For more information, see Authentication.

The new version of the SDK supports firing events for Liveboard menu actions from the host application. The SDK introduces the following host event enumeration members for Liveboard objects:

For more information, see Events reference.

The new version of SDK includes the following new events:

For more information about how to register and handle these events, see Events and app integration.

The new version of SDK supports the showAlerts attribute, using which you can show or hide alerts and error messages in the embedded view.

The Action.CreateMonitor enumeration is available in the SDK for embedded ThoughtSpot environments on which the Monitor feature is enabled. For more information, see Show or hide UI actions.

Note the following changes:

The AddRemoveColumns event is now available in the SDK. For more information, see Events reference.

The following events are now available in the SDK:

For more information, see Events reference.

The SDK now includes the following new enumerations for UI actions:

For more information, see Show or hide UI actions.

The SDK now supports the UpdateRuntimeFilters host event. For more information, see Events reference.

Embed events

The SDK includes the following new event:

For more information, see Events reference.

Visible actions

You can now configure a set of ThoughtSpot UI actions as visible actions and display these actions in the embedded UI. If your embedded instance requires only a few actions, you can use the visibleActions API to show only these actions in the embedded ThoughtSpot UI.

For more information, see Show or hide UI actions.

Embed events

The SDK supports the following new events:

For more information, see Events reference.

Liveboard embed

The pinboardEmbed package includes the defaultHeight attribute that sets a minimum height for embedded objects on a pinboard page, and the corresponding visualization pages that a user can navigate to.

For more information, see Embed a pinboard.

Embed events

The SDK EmbedEvent library includes the following new events:

For more information, see Events reference.

Prefetch API

The prefetch API fetches static resources from a given URL before your application loads. Web browsers can then cache the prefetched resources locally and serve them from a user’s local disk. You can use this API to load the embedded objects faster and improve your application response time.

For more information, see Prefetch static resources.

In-app page navigation

The navigateToPage method in the SDK lets you provide quick and direct access to a specific pinboard, saved Answer, or an application page. You can add a custom menu action or button in your application UI that calls the navigateToPage method and leads your users to the page specified in the path parameter.

For more information, see Add a custom action for in-app navigation.

Full application embedding

The appEmbed SDK package includes the following new attributes:

For more information, see Embed full application.

Embed events

The SDK EmbedEvent library includes the following events:

For more information, see Events and app integration.

searchOptions

The searchEmbed SDK package introduces the searchOptions parameter for setting search tokens. The searchOptions parameter includes the following attributes:

For more information, see Embed ThoughtSpot search.

searchQuery

The searchQuery parameter in the searchEmbed SDK package is deprecated in the Visual Embed SDK version 1.3.1. Instead, you can use the searchOptions parameter to define the search token string.

For more information about searchOptions, see Embed ThoughtSpot search.

autoLogin

The SDK now supports logging in users automatically after a user session has expired.

For more information, see Embed user authentication.

shouldEncodeUrlQueryParams

You can now convert query parameters in the ThoughtSpot generated URLs to base64-encoded format. You can enable this attribute to secure your cluster from cross-site scripting attacks.

Data structure changes in custom action response payloads

To view a sample response payload, see Custom action response payload.

preventPinboardFilterRemoval

The pinboardEmbed SDK package now includes the preventPinboardFilterRemoval attribute. You can use this attribute to disable the filter removal action and thus prevent users from removing the filter chips added on a pinboard page.

For more information, see Embed a pinboard and Embed a visualization.

suppressNoCookieAccessAlert

You can now set custom alerts for noCookieAccess events. By default, the SDK triggers a noCookieAccess event and generates an alert when a user’s browser blocks third-party cookies. The suppressNoCookieAccessAlert allows you to disable this alert.

Support for fetching callback custom action payload in batches

The Visual Embed SDK now supports processing data in batches for callback custom action responses. The callback custom action event in the SDK package supports defining batchSize and offset values to paginate the Answer payload and send the records in batches.

For more information, see Callback custom action workflow.

SAML authentication

The Visual Embed SDK packages now include the noRedirect attribute as an optional parameter for the SAMLRedirect SSO AuthType. If you want to display the SAML authentication workflow in a pop-up window, instead of refreshing the application web page to direct users to the SAML login page, you can set the noRedirect attribute to true.

For more information, see the instructions for embedding ThoughtSpot pages, search, pinboard, and visualizations.

Pinboard actions

The More menu in the embedded Pinboard page now shows the following actions for pinboard and visualizations.

Visualization actions

Visualizations on a pinboard:

NoCookieAccess event

When a user accesses the embedded application from a web browser that has third-party cookies disabled, the Visual Embed SDK emits the NoCookieAccess event to notify the developer. Cookies are disabled by default in Safari. Users can enable third-party cookies in Safari’s Preferences setting page or use another web browser. To know how to enable this setting by default on Safari for a ThoughtSpot embedded instance, contact ThoughtSpot Support.