Embed Spotter

Embed Spotter

ThoughtSpot supports Natural Language Search queries and AI-generated Answers. With ThoughtSpot Spotter, this experience is further enhanced to provide a conversational interface for users to query data, 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 other apps, ThoughtSpot provides the following components:

  • To embed the full Spotter interface with a conversation panel that allows natural language text strings, data source selection, and interactions with AI generated Answers, use the SpotterEmbed component.

  • To integrate Spotter Agent capabilities in a chatbot, use the SpotterAgentEmbed component.

Note

The ConversationEmbed and BodylessConversation components are deprecated and replaced with SpotterEmbed and SpotterAgentEmbed respectively in Visual Embed SDK v1.38.0 and later.

This article describes how to embed the Spotter interface using the SpotterEmbed component. For information about how to integrate Spotter Agent capabilities without body in a chatbot, see Integrate Spotter into your chatbot.

Before you begin🔗

Before you begin, check the following:

  • Spotter is enabled on your ThoughtSpot instance.

  • You have access to the latest version of the Visual Embed SDK or at least v1.33.1.

Import the SDK package🔗

Import the SpotterEmbed SDK library to your application environment:

npm

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

ES6

<script type = 'module'>
    import {
        SpotterEmbed,
        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: 'https://your-thoughtspot-host', // Replace with your ThoughtSpot application URL
    authType: AuthType.None,
});

Create an instance of the SpotterEmbed object🔗

Create an instance of the SpotterEmbed 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 SpotterEmbed(document.getElementById('ts-embed'), {
    frameParams: {
        width: '100%',
        height: '100%',
    },
    worksheetId: '<%=datasourceGUID%>', // ID of the data source object to query data
    searchOptions: {
        searchQuery: 'sales by region', // Optional: initial search query string to pass on load
    },
});

Optional configuration controls for embed view🔗

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

The following code sample sets the locale to English (United Kingdom) and enables viewing Spotter feature limitations.

const conversation = new SpotterEmbed(document.getElementById('ts-embed'), {
    frameParams: {
        width: '100%',
        height: '100%',
    },
    worksheetId: '<%=datasourceGUID%>', // ID of the data source object to query data
    searchOptions: {
        searchQuery: 'sales by region', // Optional: initial search query string to pass on load
    },
    locale: 'en-GB',
    showSpotterLimitations: true,
});

Customize your embed view🔗

To customize your embedded Spotter views, the following options are available with the Visual Embed SDK:

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.

The following menu actions are available by default in the embedded Spotter interface:

  • Preview data and Reset actions on the conversation panel

  • Edit and delete icons on the prompt panel

  • Pin, Save, Download, Modify on Spotter-generated Answers

  • Spotter feedback widget and chart switcher icon on Spotter-generated Answers

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

 // Show these actions
 visibleActions: [Action.Pin,Action.Save,Action.Edit,Action.PreviewDataSpotter,Action.ResetSpotterChat,Action.SpotterFeedback,Action.EditPreviousPrompt,Action.DeletePreviousPrompt],
 // Disable these actions
 disabledActions:[Action.PreviewDataSpotter,Action.Edit],
 disabledActionReason: "Contact your administrator to enable this feature"

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

Customize styles and interface elements🔗

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

Override icons🔗

To override the icons, you must first identify the icon ID, create an SVG file to replace this icon, and add the SVG hosting URL to your embed customization code.

The most common icon ID to override is rd-icon-spotter, the default Spotter icon.

The following example uses the alternate-spotter-icon.svg file hosted on https://cdn.jsdelivr.net/ to override the Spotter icon.

 init({
     //...
     customizations: {
         // Specify the SVG hosting URL to overide the icon, for example Spotter (`rd-icon-spotter`) icon
         iconSpriteUrl: "https://cdn.jsdelivr.net/gh/thoughtspot/custom-css-demo/alternate-spotter-icon.svg"
     }
 });
Note

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

Customize text strings🔗

To replace text strings, you can use the stringsIDs and strings properties in the content customization object.

The following example shows how to replace "Spotter" and other text strings on the Spotter interface.

// Initialize the SDK with custom text string replacements
init({
    // ...
    customizations: {
        content: {
            // Use the strings object to replace the visible UI text with custom labels.
            strings: {
                // Change all instances of "Liveboard" to "Dashboard"
                "Liveboard": "Dashboard",
                // Change all instances of "Answer" to "Reports"
                "Answer": "Reports",
                // Change all instances of "Spotter" to "dataAnlyzer"
                "Spotter": "dataAnlyzer",
                // Change all instances of "Search" to "Analyze"
                "Search": "Analyze",
            }
        }
    }
});

Customize styles🔗

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.

// Initialize the SDK with CSS variables with custom style definitions
init({
  // ...
  customizations: {
    style: {
      // Use CSS variables to customize styles
      customCSS: {
        variables: {
          "--ts-var-button--primary-background": "#008000",
          "--ts-var-spotter-prompt-background": "#F0EBFF",
          "--ts-var-root-color": "#E3D9FC",
          "--ts-var-root-background": "#F7F5FF",
        },
      },
    },
  },

For more information about CSS variables for style customization, see Spotter interface customization.

Customize app interactions with events🔗

To listen to the events emitted by the embedded ThoughtSpot component, register embed event handlers.

The following example shows how to register EmbedEvent.Init and EmbedEvent.Load listeners.

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

Similarly, to trigger actions on the embedded ThoughtSpot interface, use Host events.

Render the embedded object🔗

conversation.render();

Code sample🔗

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

// Initialize the SDK
init({
  thoughtSpotHost: 'https://your-thoughtspot-host', // Replace with your ThoughtSpot application URL
  authType: AuthType.None,
});

// Find the container element in your HTML
const container = document.getElementById('ts-embed');
if (container) {
  // Create and render the SpotterEmbed component
  const spotterEmbed = new SpotterEmbed(container, {
    worksheetId: 'your-worksheet-id', // ID of the data source object to query data
    searchOptions: {
      searchQuery: 'Sales by year', // Optional: initial search query string to pass on load
    },
    frameParams: {
      width: '100%',
      height: '600px',
    },
    // Add more configuration options as needed
  });

  spotterEmbed.render();
}

Test your embed🔗

  • Build your app and load the embedded object.

    • If the embedding is successful, you’ll see the Spotter page with a conversation panel.

      Spotter embed

    • Add a query, click the prompt button, and view the results.

      Spotter embed

    • If you see a blank screen:

      • Check if your code has the correct ThoughtSpot host URL. Ensure that your instance is accessible.

      • Check if the authentication credentials in your code are valid

  • Verify the customized objects and elements.
    The following figures show the customized Spotter icon and text:

    Spotter icon customization
    Spotter customization

Additional resources🔗