Andriod Embed SDK for Andriod apps

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.
    Ensure that your host app embedding ThoughtSpot is added to the CSP and CORS allowlists in ThoughtSpot.

  • 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:0.0.1-beta")
  • 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,0.0.1-beta.

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πŸ”—

  1. In your application class or MainActivity, add the embedView.

     val embedView = findViewById<LiveboardEmbed>(R.id.liveboard_embed_view)
  2. 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"
        }
    }
  3. 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:

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.