# Embed Spotter experience

> For the complete documentation index, see [llms.txt](https://developers.thoughtspot.com/docs/llms.txt)

Source: https://developers.thoughtspot.com/docs/embed-spotter

# Embed Spotter experience

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]({{navprefix}}/{{embed-ai-analytics}}#_feature_status_and_availability_in_embed_mode) on your instance.
    
-   Your host application domain is added to [ThoughtSpot CSP and CORS allowlists]({{navprefix}}/{{security-settings}}).
    
-   Your application project has access to the [latest version of the Visual Embed SDK]({{navprefix}}/{{api-changelog}}).
    

> **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**

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

**ES6**

```JavaScript
<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]({{navprefix}}/{{faqs}}#tsHostName) of your ThoughtSpot application instance.
    
-   `authType`  
    Authentication type. For testing purposes, you can use `AuthType.None`. For information about other authentication options, see [Authentication]({{navprefix}}/{{embed-authentication}}).
    

```JavaScript
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.

```JavaScript
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.

```JavaScript
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]({{navprefix}}/{{embed-spotter}}#configControls).

### Register event listeners

To listen to the events emitted by the embedded ThoughtSpot component, register [embed event]({{navprefix}}/{{event-embedEvents}}) handlers.

The following example shows how to register [EmbedEvent.Init]({{navprefix}}/{{EmbedEvent}}#_init) and [EmbedEvent.Load]({{navprefix}}/{{EmbedEvent}}#_load) listeners.

```JavaScript
// 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
```

```JavaScript
// 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]({{navprefix}}/{{HostEvent}}).

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

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

### Render the embedded object

```JavaScript
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]({{navprefix}}/{{customize-spotter-embed}}).

## Code samples

**Code sample for embedding Spotter Classic and Spotter 2 experience**

```JavaScript
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**

```JavaScript
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);
    });
}
```

## Additional resources

-   [Spotter features and embedding options]({{navprefix}}/{{embed-ai-analytics}})
    
-   [SpotterEmbed classes and methods](https://developers.thoughtspot.com/docs/Class_SpotterEmbed)
    
-   [Configuration options for Spotter interface customization](https://developers.thoughtspot.com/docs/Interface_SpotterEmbedViewConfig)
    
-   [Developer examples](https://github.com/thoughtspot/developer-examples/tree/main/visual-embed/spotter/spotter-embed)
    
-   [Spotter Product Documentation](https://docs.thoughtspot.com/cloud/latest/spotter)