# Andriod Embed SDK for Andriod apps

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

Source: https://developers.thoughtspot.com/docs/embed-ts-android

# Andriod Embed SDK for Andriod apps

Your application developers can embed a ThoughtSpot Liveboard in your native Android app using the ThoughtSpot Android Embed SDK.

## Before you begin

Before you begin, ensure that your development environment has the following setup:

-   Access to a ThoughtSpot instance with administrator and developer privileges.  
    
-   Access to the Liveboard object that you want to embed.
    
-   Android Studio is installed.  
    

## Install the SDK

To download the Android Embed SDK from Maven Central to your project and install the libraries, add the following code to your app-level `build.gradle.kts`:

```kotlin
implementation("io.github.thoughtspot:android-embed-sdk:1.0.0")
```

-   `implementation`  
    Instructs Gradle to add the dependency for compile and runtime usage in your Android project.
    
-   `com.github.thoughtspot`  
    GitHub reference ID
    
-   `android-embed-sdk`  
    The GitHub repository of the Android Embed SDK package.
    
-   `Tag`  
    Indicates the version of the SDK to use. Replace this with a specific release tag from the GitHub repository. For example,1.0.0.
    

The SDK may require network access to communicate with your ThoughtSpot instance. Ensure your app’s `AndroidManifest.xml` includes the following:

## XML Layout

In the `activity_main.xml` of your project, add the following elements to create a custom Android view component for Liveboard embedding:

```xml
<!-- res/layout/activity_main.xml -->
<com.thoughtspot.android.embedsdk.LiveboardEmbed
    android:id="@+id/liveboard_embed_view"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    app:layout_constraintTop_toTopOf="parent"
    app:layout_constraintBottom_toTopOf="@id/another_view"
    app:layout_constraintStart_toStartOf="parent"
    app:layout_constraintEnd_toEndOf="parent" />
```

-   `<com.thoughtspot.android.embedsdk.LiveboardEmbed …​ />`  
    Declares a custom view to render the Liveboard in the app.
    
-   `android:id="@+id/liveboard_embed_view"`  
    Assigns a unique ID to this view so you can reference it in your Kotlin/Java code.
    
-   `android:layout_width="match_parent"` and `android:layout_height="wrap_content"`  
    These elements set the width and height of the layout for the embed view.
    
-   The `app:layout_constraint…​` attributes  
    Positions the view relative to the other UI elements.
    

In the next step, we’ll add a reference to this view and then load a specific Liveboard into it.

## Initialize the SDK

1.  In your application class or MainActivity, add the embedView.
    
    ```kotlin
     val embedView = findViewById<LiveboardEmbed>(R.id.liveboard_embed_view)
    ```
    
2.  Specify the ThoughtSpot application URL, authentication attributes, and token fetching method.
    
    ```kotlin
    val embedConfig = EmbedConfig(
        thoughtSpotHost = "https://your.thoughtspot.instance",  // Replace it with your ThoughtSpot application URL
        authType = AuthType.TrustedAuthTokenCookieless
    )
    
    val getAuthToken: () -> String = {
        runBlocking {
            // Replace with real token retrieval logic
            "your-auth-token"
        }
    }
    ```
    
3.  Initialize the SDK.
    
    ```Kotlin
    embedView.initialize(
        viewConfig = viewConfig,
        embedConfig = embedConfig,
        getAuthToken = getAuthToken
    )
    ```
    

## Add the Liveboard and customize the embed view

Add the Liveboard GUID.

```Kotlin
 val viewConfig = LiveboardViewConfig(
     liveboardId = "your-Liveboard-id" // Replace with your Liveboard ID
 )
```

You can also add optional parameters as shown in this example:

```Kotlin
 val viewConfig = LiveboardViewConfig(
     liveboardId = "your-Liveboard-id", // Replace with your Liveboard ID
     enable2ColumnLayout = true, // sets column layout and breakpoint width
     activeTabId = "your-tab-guid", // Set a specific tab as a home tab
 )
```

## Customize your embed

To customize the embedded view, the following customization settings are available:

-   Control the [visibility of menu actions in the embedded view]({{navprefix}}/{{mobile-embed-android}}#_customize_menu_actions)
    
-   [Customize the styles and UI layout]({{navprefix}}/{{mobile-embed-android}}#_customize_styles_and_interface_elements) of the embedded view
    
-   [Handling events and app interactions]({{navprefix}}/{{mobile-embed-android}}#_3_advanced_handling_events_and_app_interactions)
    

### Customize menu actions

By default, the mobile embed SDKs include a [specific set of menu actions]({{navprefix}}/{{mobile-embed}}#_menu_customization) for Liveboard embeds in mobile view.

To disable or hide a menu action, use the `disabledActions`, `visibleActions`, or `hiddenActions` array:

```Kotlin
 val viewConfig = LiveboardViewConfig(
     liveboardId = "your-Liveboard-id" // Replace with your Liveboard ID
     // Show only these actions
     visibleActions = listOf(
        Action.AddFilter, //Add filter menu action
        Action.Share,  // Share action
        Action.DrillDown, // Drill down action
        Action.AxisMenuFilter,  // Filter action on chart axis
        Action.AxisMenuTimeBucket,  // Time bucket option in the chart axis
     ),
     // These actions will be grayed out and not clickable
     disabledActions = listOf(Action.Download),
     // Optionally, add a tooltip text for disabled actions
     disabledActionReason = "Contact your administrator to enable this action"
 )
```

> **NOTE:** To show or hide menu actions, use either visibleActions or hiddenActions.

### Customize styles

Define CSS variables to apply custom styles.

```Kotlin
 val viewConfig = LiveboardViewConfig(
     liveboardId = "Your-Liveboard-id",
     enable2ColumnLayout = true,
     customizations = CustomisationsInterface(
        style = CustomStyles(
            customCSS = customCssInterface(
                variables = mapOf(
                    "--ts-var-primary-color" to "#0055ff",
                    "--ts-var-max-width" to "1200px",
                    "--ts-var-enable-2-column-layout" to "true",
                    "--ts-var-root-background" to "#fef4dd",
                 )
             )
         )
     )
 )
```

### Handle events and app interactions

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

```Kotlin
// Register an event listener for authentication failures and custom actions
embedView.getController()?.on(EmbedEvent.AuthInit) { payload ->
    println("Auth initialized: $payload")
}
```

To trigger actions on the embedded ThoughtSpot interface, use [Host events]({{navprefix}}/{{events-hostEvents}}).

```Kotlin
// Trigger reload action
embedView.getController()?.trigger(HostEvent.Reload)
```

## Render the embedded object

Render your embed and build your app to verify the changes.

## Code sample

```Kotlin
import kotlinx.coroutines.runBlocking
// Import other necessary ThoughtSpot SDK classes

val embedView = findViewById<LiveboardEmbed>(R.id.liveboard_embed_view)

val viewConfig = LiveboardViewConfig(
    liveboardId = "Your-Liveboard-id", // Replace with your Liveboard ID
    enable2ColumnLayout = true,
    visibleActions = listOf(
        Action.AddFilter,           // Add filter menu action
        Action.Share,               // Share action
        Action.DrillDown,           // Drill down action
        Action.AxisMenuFilter,      // Filter action on chart axis
        Action.AxisMenuTimeBucket   // Time bucket option in the chart axis
    ),
    // These actions will be grayed out and not clickable
    disabledActions = listOf(Action.Download),
    // Optionally, add a tooltip text for disabled actions
    disabledActionReason = "Contact your administrator to enable this action",
    customizations = CustomisationsInterface(
        style = CustomStyles(
            customCSS = customCssInterface(
                variables = mapOf(
                    "--ts-var-primary-color" to "#0055ff",
                    "--ts-var-liveboard-dual-column-breakpoint" to "1100px",
                    "--ts-var-max-width" to "1200px",
                    "--ts-var-enable-2-column-layout" to "true",
                    "--ts-var-root-background" to "#fef4dd",
                    "--ts-var-root-color" to "#4a4a4a",
                    "--ts-var-viz-title-color" to "#8e6b23",
                    "--ts-var-viz-title-font-family" to "'Georgia', 'Times New Roman', serif",
                    "--ts-var-viz-title-text-transform" to "capitalize",
                    "--ts-var-viz-description-color" to "#6b705c",
                    "--ts-var-viz-description-font-family" to "'Verdana', 'Helvetica', sans-serif",
                    "--ts-var-viz-border-radius" to "6px",
                    "--ts-var-viz-box-shadow" to "0 3px 6px rgba(0, 0, 0, 0.15)",
                    "--ts-var-viz-background" to "#fffbf0",
                    "--ts-var-viz-legend-hover-background" to "#ffe4b5",
                    "--ts-var-liveboard-single-column-breakpoint" to "320px"
                    // Add more variables as needed
                )
            )
        )
    )
)

val embedConfig = EmbedConfig(
    thoughtSpotHost = "https://your.thoughtspot.instance",
    authType = AuthType.TrustedAuthTokenCookieless
)

val getAuthToken: () -> String = {
    runBlocking {
        // Replace with real token retrieval logic
        "your-auth-token"
    }
}

embedView.initialize(
    viewConfig = viewConfig,
    embedConfig = embedConfig,
    getAuthToken = getAuthToken
)

// Example: Listen to AuthInit event
embedView.getController()?.on(EmbedEvent.AuthInit) { payload ->
    println("Auth initialized: \$2ayload")
}

// Trigger reload action
embedView.getController()?.trigger(HostEvent.Reload)
```

## Test your embed

-   Check your app and verify if the embedded object loads. If you see a blank screen:
    
    -   Ensure that your ThoughtSpot host URL is correct and accessible.
        
    -   Check if the authentication credentials in your code are valid.
        
    
-   Check if your Liveboard renders with all its charts and tables. If the content is not loading, check if your code has the correct Liveboard ID. Additionally, you can add a listener for `EmbedEvent.Error` and verify the logs.
    
-   In case of rendering issues, adjust the frame size constraints and rerun your app.
    
-   Check if your custom CSS specifications are applied correctly.
    
-   Verify if custom styles are applied correctly.
    

## Known limitations

For information about supported features and known limitations, see [Mobile embed limitations]({{navprefix}}/{{mobile-embed}}#_known_limitations).

## Additional resources

-   [Android Embed SDK GitHub repo](https://github.com/thoughtspot/android-embed-sdk)