Embed Spotter

ThoughtSpot supports Natural Language Search queries and AI-generated Answers. With ThoughtSpot Spotter, this experience is further enhanced to a full conversational interface that users can interact with, ask follow-up questions, and get insights.

Visual Embed SDK offers several options to seamlessly embed conversational analytics within your applications and customize the interface and experience as per your organization’s branding guidelines.

To integrate Spotter capabilities into your application environment, the following components are available:

ConversationEmbed
Allows embedding the full Spotter interface with a conversation panel and body.
BodylessConversation
Allows integrating Spotter capabilities into a chatbot.

Additionally, you can also use REST APIs to create a conversation session, ask follow-up questions, and generate Answers.

This article describes how to embed Spotter with a conversation panel and body in your app.

Spotter components🔗

The ConversationEmbed package adds the following components to your embedding application:

A conversation panel and prompt button to interact with Spotter.
The data source selector that allows application users to select a data source for Spotter analysis.
The Preview data button to allow users to preview the data source used for Spotter analysis.
The Reset button to reset the ongoing conversation.

After a conversation session is created, the interface shows the prompt panels, charts and tables, Spotter feedback widget, and menu actions to Pin, Save, Modify, or Download the result.

Before you begin🔗

Before you begin, check the following:

Spotter is enabled on your ThoughtSpot instance.
Your environment has Visual Embed SDK v1.33.1 or later version.

Import the SDK package🔗

Import the ConversationEmbed SDK library to your application environment:

npm

import {
    ConversationEmbed,
    AuthType,
    init,
    prefetch,
}
from '@thoughtspot/visual-embed-sdk';

ES6

<script type = 'module'>
    import {
        ConversationEmbed,
        AuthType,
        init,
        prefetch,
    }
from 'https://cdn.jsdelivr.net/npm/@thoughtspot/visual-embed-sdk/dist/index.js';

Initialize the SDK🔗

To initialize the SDK, the following information is required:

thoughtSpotHost
The hostname of your ThoughtSpot application instance. See FAQs to know how to find the hostname of your application instance.
authType
Authentication type. ThoughtSpot supports a variety of Authentication types. For testing purposes, you can use AuthType.None. For other authentication options, see Authentication.

init({
    thoughtSpotHost: '<%=tshost%>',
    authType: AuthType.None,
});

Create an instance of ConversationEmbed object🔗

Create an instance of the ConversationEmbed object and specify the data source ID. Optionally, you can specify the search query string to generate a chart or table at load time.

const conversation = new ConversationEmbed(document.getElementById('ts-embed'), {
    frameParams: {
        width: '100%',
        height: '100%',
    },
    worksheetId: '<%=datasourceGUID%>',
    searchOptions: {
        searchQuery: 'sales by region',
    },
});

const conversation = new ConversationEmbed(document.getElementById('ts-embed'), {
    frameParams: {
        width: '100%',
        height: '100%',
    },
    worksheetId: '<%=datasourceGUID%>',
    searchOptions: {
        searchQuery: 'sales by region',
    },
});

Additional configuration controls (Optional)🔗

The embed package for Spotter includes the additional configuration flags to customize the Spotter interface.

disableSourceSelection
Disables data source selection panel for embed users when set to true.
hideSourceSelection
Hides data source selection panel when set to true
locale
Sets the locale and language for Spotter interface.
showSpotterLimitations
Shows functional limitations of Spotter when set to true
hideSampleQuestions
Hides sample questions that appear on the default Spotter page.

Customize your embed (Optional)🔗

To customize the Spotter interface, use the configuration attributes and properties available for ConversationEmbed in the SDK.

Customize style, icons, and text🔗

To customize the look and feel of the Spotter page, you can use the customizations settings in the SDK. The customizations object allows you to add custom CSS definitions, text strings, and icons.

Icon overrides🔗

To override the default Spotter icon, locate the icon ID and create an SVG file with the icon ID. The following example uses the alternate-spotter-icon.svg file hosted on https://cdn.jsdelivr.net/ to override the Spotter icon.

 init({
     //...
     customizations: {
         // rd-icon-spotter
         iconSpriteUrl: "https://cdn.jsdelivr.net/gh/thoughtspot/custom-css-demo/alternate-spotter-icon.svg"
     }
 });

Note	When customizing icons, ensure that the hosting server is added to the CSP allowlist on the Develop > Security Settings page. For more information, see Customize icons.

Text string customization🔗

Similarly, you can replace the text strings on the Spotter interface as shown in this example:

 init({
     //...
     customizations: {
         content: {
             strings: {
                 "Spotter": "dataAnalyzer",
                 "Preview data": "View data",
                 "Edit": "Modify"
             }
         }
     }
 });

CSS customization🔗

There are several CSS variables available for customizing Spotter interface. You can customize the background color of the conversation and prompt panels, button elements, and the components of the charts generated by Spotter. For more information, see Spotter interface customization.

Customize menu actions and elements🔗

The SDK provides action IDs to disable, show, or hide the following elements and menu actions via disabledActions, visibleActions, or hiddenActions array:

Preview data and Reset actions on the conversation panel
Edit and delete icons on the prompt panel
Pin, Save, Download and Modify actions on charts
Spotter feedback widget and chart switcher icon on charts

The following example shows how to disable actions and menu elements using disabledActions array:

 //...
 disabledActions:[Action.PreviewDataSpotter,Action.Edit]
 visibleActions: [Action.Pin,Action.Save,Action.Edit,Action.PreviewDataSpotter,Action.ResetSpotterChat,Action.SpotterFeedback,Action.EditPreviousPrompt,Action.DeletePreviousPrompt]

For a complete list of supported actions, see Spotter menu actions.

Register, handle, and trigger events🔗

 conversation.on(EmbedEvent.Init, showLoader)
 conversation.on(EmbedEvent.Load, hideLoader)

For more information about event types, see the following pages:

Render the embedded object🔗

conversation.render();

Test your embedding🔗

Load the embedded object in your app. If the embedding is successful, you will see the following page:

Spotter page🔗

Spotter page with the preloaded query and search result🔗

Spotter page with custom icon🔗

The following figure shows the Spotter page with a custom icon sprite:

Spotter page with custom text🔗

The following figure shows the Spotter page with custom text strings: