Andriod Embed SDK for Andriod apps

Table of Contents

Before you begin
Install the SDK
XML Layout
Initialize the SDK
Add the Liveboard and customize the embed view
Customize your embed
Render the embedded object
Code sample
Test your embed
Known limitations
Additional resources

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:

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:

<!-- 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🔗

In your application class or MainActivity, add the embedView.

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

Specify the ThoughtSpot application URL, authentication attributes, and token fetching method.

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"
    }
}

Initialize the SDK.

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

Add the Liveboard and customize the embed view🔗

Add the Liveboard GUID.

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

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

 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
Customize the styles and UI layout of the embedded view
Handling events and app interactions

Customize menu actions🔗

By default, the mobile embed SDKs include a specific set of menu actions for Liveboard embeds in mobile view.

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

 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.

 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 listeners.

// 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.

// 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🔗

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.

Additional resources🔗

Android Embed SDK GitHub repo