🚧

Basic requirements

Before you start, make sure that you meet the basic requirements:

1. You are using Android Classic as your integration method.
2. You are using Taboola SDK 4.0.29 or higher.
3. Your Taboola Account Manager has instructed you to go ahead with the Deeper Dive integration.

---

Need a hand? Please reach out to your Taboola Account Manager.

Overview

Deeper Dive adds an AI-powered question-and-answer unit to your page. Users can tap suggested questions or submit their own questions and continue the experience in a full-screen bottom sheet, while staying inside your app flow.

First steps

Complete the Basic Integration steps first.

Page type behavior

The Deeper Dive experience depends on the page type that you set on TBLClassicPage:

📘

Page type behavior

• article - The unit includes suggested questions.
• homepage - The unit loads without suggested questions.

Set the page type before creating the Deeper Dive unit:

classicPage.setPageType("article");   // With suggested questions
classicPage.setPageType("homepage"); // Without suggested questions

classicPage.setPageType("article")    // With suggested questions
classicPage.setPageType("homepage") // Without suggested questions

Enable the feature

Create Deeper Dive using the TBLClassicPage instance that you have already created.

Use createDeeperDiveUnit for a classic Android View hierarchy, or createDeeperDiveComposeUnit when the unit is hosted inside Jetpack Compose.

Views and XML layout

TBLClassicDeeperDiveUnit deeperDiveUnit = classicPage.createDeeperDiveUnit(
    fragmentManager,
    listener
);

val deeperDiveUnit = classicPage.createDeeperDiveUnit(
    fragmentManager,
    listener
)

Jetpack Compose

val deeperDiveComposeUnit = classicPage.createDeeperDiveComposeUnit(
    fragmentManager,
    listener
)

The Compose API returns a TBLClassicComposeDeeperDiveUnit, a subclass of TBLClassicDeeperDiveUnit that embeds the same classic view through AndroidView. You still use the same TBLClassicDeeperDiveListener, fetchContent(), and shouldCloseDeeperDiveOnOrganicClick behavior as with the view-based unit.

Inside a @Composable, add the unit with GetDeeperDiveComposeView. You can pass an optional Modifier (for example fillMaxWidth()).

setContent {
    Column {
        deeperDiveComposeUnit.GetDeeperDiveComposeView(
            modifier = Modifier.fillMaxWidth()
        )
        // Other composables
    }
}

📘

Parameters (both factory methods)

• fragmentManager - The FragmentManager used to display the Deeper Dive bottom sheet.
• listener - A class instance that implements TBLClassicDeeperDiveListener.

Placement and mode are configured internally by the SDK for Deeper Dive. You should not set them manually.

Add the unit to your layout (Views)

Add the returned TBLClassicDeeperDiveUnit view to a parent container in your screen.

<FrameLayout
    android:id="@+id/deeper_dive_container_view"
    android:layout_width="match_parent"
    android:layout_height="wrap_content" />

FrameLayout container = findViewById(R.id.deeper_dive_container_view);
container.addView(deeperDiveUnit);

val container = findViewById<FrameLayout>(R.id.deeper_dive_container_view)
container.addView(deeperDiveUnit)

For Compose, you do not call addView; use GetDeeperDiveComposeView as shown above.

Load content

Call fetchContent() when your screen is ready to show the unit (after it is attached for views, or when your composable tree will display it for Compose).

deeperDiveUnit.fetchContent();

deeperDiveUnit.fetchContent()

deeperDiveComposeUnit.fetchContent()

🚧

Important

For Views, call fetchContent() once the unit is in the view hierarchy (for example, right after addView).

For Compose, call fetchContent() when the hosting UI is ready (you may call it before or after setContent, as long as the unit is shown shortly afterward).

Event handling

The following applies to both TBLClassicDeeperDiveUnit and TBLClassicComposeDeeperDiveUnit.

TBLClassicDeeperDiveListener

To get notified about Deeper Dive events, implement TBLClassicDeeperDiveListener:

TBLClassicDeeperDiveListener listener = new TBLClassicDeeperDiveListener() {
    @Override
    public void onDeeperDiveLoaded() {
        super.onDeeperDiveLoaded();
        // Called when Deeper Dive content is loaded
    }

    @Override
    public boolean onDeeperDiveReceiveClick(String url, boolean isOrganic) {
        super.onDeeperDiveReceiveClick(url, isOrganic);
        // Return true: SDK opens click URL
        // Return false: publisher handles click
        return true;
    }

    @Override
    public void onDeeperDiveLoadFailedWithError(String error) {
        super.onDeeperDiveLoadFailedWithError(error);
        // Handle error here
    }
};

val listener = object : TBLClassicDeeperDiveListener() {
    override fun onDeeperDiveLoaded() {
        super.onDeeperDiveLoaded()
        // Called when Deeper Dive content is loaded
    }

    override fun onDeeperDiveReceiveClick(url: String, isOrganic: Boolean): Boolean {
        super.onDeeperDiveReceiveClick(url, isOrganic)
        // Return true: SDK opens click URL
        // Return false: publisher handles click
        return true
    }

    override fun onDeeperDiveLoadFailedWithError(error: String) {
        super.onDeeperDiveLoadFailedWithError(error)
        // Handle error here
    }
}

📘

Automatic bottom sheet behavior

The SDK opens the Deeper Dive bottom sheet automatically when the user taps a question in the unit.

Click override behavior

onDeeperDiveReceiveClick(url, isOrganic) controls who handles clicks from the Deeper Dive full-screen answer view:

• return true: SDK handles the click and opens the URL.
• return false: publisher handles the click.

Optional: close full-screen on organic click

You can configure Deeper Dive to close the full-screen dialog when the click is handled by the publisher:

deeperDiveUnit.shouldCloseDeeperDiveOnOrganicClick = true;

deeperDiveUnit.shouldCloseDeeperDiveOnOrganicClick = true

For a TBLClassicComposeDeeperDiveUnit, assign the same property on your Compose unit instance (for example deeperDiveComposeUnit.shouldCloseDeeperDiveOnOrganicClick = true).

📘

Notes

• Default is false.
• This applies only when your listener returns false (publisher-handled click path).
• If your listener returns true, the SDK handles click opening and this flag is ignored.