Embed Spotter experience

Table of Contents

Before you begin
Import the SDK package
Initialize the SDK
Create an instance of the SpotterEmbed object
Customizing the embedded Spotter interface
Code samples
Additional resources

You can embed the full Spotter experience in your applications using the SpotterEmbed component in the Visual Embed SDK. Using the customization settings available in the SDK for each Spotter version, you can configure the Spotter interface to suit the needs of your embedding application.

Before you begin🔗

To embed Spotter, you need the following access and setup:

Access to a ThoughtSpot instance with the Spotter feature. If you want a specific version of Spotter enabled, work with your ThoughtSpot administrator to enable the required features and settings on your instance.
Your host application domain is added to ThoughtSpot CSP and CORS allowlists.
Your application project has access to the latest version of the Visual Embed SDK.

Note

For Spotter embedding that uses cookieless authentication, use Visual Embed SDK version 1.45.0 or later with ThoughtSpot Cloud version 26.2.0.cl or later. To enable proactive token refresh, set the refreshAuthTokenOnNearExpiry parameter to true.
Spotter workflows may run longer at times. To prevent authorization errors, set the authentication token expiration to at least 10 minutes.

Import the SDK package🔗

Import the SpotterEmbed SDK library to your application environment:

npm

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

ES6

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

Initialize the SDK🔗

To initialize the SDK, the following information is required:

thoughtSpotHost
The hostname of your ThoughtSpot application instance.
authType
Authentication type. For testing purposes, you can use AuthType.None. For information about other authentication options, see Authentication.

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

Create an instance of the SpotterEmbed object🔗

Create an instance of the SpotterEmbed object.

If you are embedding the Spotter Classic or Spotter 2 experience, the data source ID is required. If Spotter 3 experience is enabled on your instance, you can either specify the data source ID or enable the Auto mode to allow Spotter to automatically discover and select data sources.

Important

Auto mode is disabled by default on ThoughtSpot Embedded instances. To enable this feature on your instance, contact ThoughtSpot Support.

const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), {
    frameParams: {
        width: '100%',
        height: '100%',
    },
    worksheetId: '<%=datasourceGUID%>', // ID of the data source object. To use the Auto mode, set the ID to 'auto_mode',
    //... other attributes
});

Customize your embed (Optional)🔗

The SDK provides configuration settings to customize the embedded Spotter interface. For example, you can hide sample questions or disable data source selection using the hideSampleQuestions and disableSourceSelection parameters.

const conversation = new SpotterEmbed(document.getElementById('ts-embed'), {
    //...other embed configuration attributes
    hideSampleQuestions: true,
    disableSourceSelection: true
});

For more information and examples, see Customizing the embedded Spotter interface.

Register event listeners🔗

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.

// Register event listeners
spotterEmbed.on(EmbedEvent.Init, showLoader); // Show loader when initialization starts
spotterEmbed.on(EmbedEvent.Load, hideLoader); // Hide loader when embed is fully loaded

// Use EmbedEvent.Subscribed to safely trigger a HostEvent on initial load
spotterEmbed.on(EmbedEvent.Subscribed, (eventData) => {
    if (eventData.data.hostEventType === 'ResetSpotterConversation') {
        spotterEmbed.trigger(HostEvent.ResetSpotterConversation);
    }
});

To trigger actions on the embedded interface, use the Host events.

The following example shows the host event to reset a Spotter conversation session:

// Example: Add a host event to reset the Spotter conversation
document.getElementById('resetBtn').addEventListener('click', () => {
    spotterEmbed.trigger(HostEvent.ResetSpotterConversation);
});

Render the embedded object🔗

spotterEmbed.render();

Verify your embed🔗

Load the embedded object.
- If the embedding is successful, you’ll see the Spotter page.
- Initiate a chat session, ask a question, and view the results.
- If you see a blank screen:
  - Verify that your embed code has the correct ThoughtSpot host URL. Ensure that your ThoughtSpot instance is accessible.
  - Verify whether the authentication credentials used in your code are valid.
Verify whether the customization settings are applied.

Customizing the embedded Spotter interface🔗

When you embed Spotter, you’ll notice that the embedded component loads an initial page with a prompt interface. The look and feel of this page vary depending on the Spotter version used for embedding. To learn about the customization options available with the Visual Embed SDK, see Customizing the Spotter embed view.

Code samples🔗

Code sample for embedding Spotter Classic and Spotter 2 experience

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

// Initialize the ThoughtSpot Visual Embed SDK with your ThoughtSpot URL and authentication type.
init({
    thoughtSpotHost: 'https://your-thoughtspot-host', // Replace with your ThoughtSpot application URL
    authType: AuthType.None, // Use the appropriate AuthType for your setup
});

//Define event handler to show a loading indicator when the embed is initializing.
function showLoader() {
    // Show loading indicator
}

// Define event handler to hide the loading indicator when the embed has loaded.
function hideLoader() {
    // Hide loading indicator
}

// Find the container element in your HTML where the SpotterEmbed will be rendered.
const container = document.getElementById('ts-embed');
if (container) {
    // Create and configure the SpotterEmbed
    const spotterEmbed = new SpotterEmbed(container, {
        frameParams: {
            height: '100%', // Set the height of the embedded frame
            width: '100%', // Set the width of the embedded frame
        },
        worksheetId: 'your-worksheet-id', // ID of the data source object to query data from
        //... other configuration attributes
    });

    // Register event listeners
    spotterEmbed.on(EmbedEvent.Init, showLoader); // Show loader when initialization starts
    spotterEmbed.on(EmbedEvent.Load, hideLoader); // Hide loader when embed is fully loaded

    // Render the SpotterEmbed in the container.
    spotterEmbed.render();
    // Example: Add a host event to reset the Spotter conversation
    document.getElementById('resetBtn').addEventListener('click', () => {
        spotterEmbed.trigger(HostEvent.ResetSpotterConversation);
    });
}

Code sample for embedding Spotter 3 experience

import {
    SpotterEmbed,
    AuthType,
    init,
    EmbedEvent,
    HostEvent
} from '@thoughtspot/visual-embed-sdk';
// Initialize the ThoughtSpot Visual Embed SDK with your ThoughtSpot URL and authentication type.
init({
    thoughtSpotHost: 'https://your-thoughtspot-host', // Replace with your ThoughtSpot application URL
    authType: AuthType.None, // Use the appropriate AuthType for your setup
});

//Define event handler to show a loading indicator when the embed is initializing.
function showLoader() {
    // Show loading indicator
}

// Define event handler to hide the loading indicator when the embed has loaded.
function hideLoader() {
    // Hide loading indicator
}

// Find the container element in your HTML where the SpotterEmbed will be rendered.
const container = document.getElementById('ts-embed');
if (container) {
    // Create and configure the SpotterEmbed
    const spotterEmbed = new SpotterEmbed(container, {
        frameParams: {
            height: '100%', // Set the height of the embedded frame
            width: '100%', // Set the width of the embedded frame
        },
        worksheetId: 'your-worksheet-id', // ID of the data source object to query data from. For automatic model discovery and selection (Auto mode), specify 'auto_mode'
        updatedSpotterChatPrompt: true, // Enable new chat interface
        enablePastConversationsSidebar: true, // Enable chat history
        //... other configuration attributes
    });

    // Register event listeners
    spotterEmbed.on(EmbedEvent.Init, showLoader); // Show loader when initialization starts
    spotterEmbed.on(EmbedEvent.Load, hideLoader); // Hide loader when embed is fully loaded

    // Render the SpotterEmbed in the container.
    spotterEmbed.render();
    // Example: Add a host event to reset the Spotter conversation
    document.getElementById('resetBtn').addEventListener('click', () => {
        spotterEmbed.trigger(HostEvent.ResetSpotterConversation);
    });
}