📍

This page presumes that you are using Jetpack Compose.

✅

Sample App

While reading the documentation, take a look at our Sample App.

Initialize Taboola

📘

The initialization steps in this section are the same for Classic, Web, and Compose integrations.

1. Create a TBLPublisherInfo object and initialize Taboola:

val publisherInfo = TBLPublisherInfo("publisher-id")

// (Optional) Set the desired log level: 
Taboola.setLogLevel(logLevel)

Taboola.init(publisherInfo)

📘

Params

publisher-id - a unique, machine-readable string (without spaces), as provided by Taboola.

E.g. "<<publisherID>>"

🚧

IMPORTANT

1. Initialization is required once per application. It should be done as early as possible - preferably in a subclass of Application.
2. Failure to initialize successfully will result in Taboola recommendations not being displayed. Make sure that all paths within your application logic result in a successful initialization.

Build Taboola content instances

🚧

Overview

1. For each screen, obtain a TBLClassicPage instance.
2. For each placement on that screen:
   1. Use the Page instance to build a Compose Unit. Make sure to use a unique placement name for each Unit.
   2. Add the Compose Unit to your Compose UI using GetClassicUnitView().

---

Do not invoke the addUnitToPage() method - the Compose Unit instance returned already belongs to that Page instance.

In your Activity/Fragment containing the Compose content:

1. Obtain a TBLClassicPage instance for that screen, passing the relevant pageUrl and pageType (e.g. "<<pageType>>"):

val tblClassicPage = Taboola.getClassicPage(<pageUrl>, <pageType>)

📘

• pageUrl - A fully-qualified, public URL, with the same content as the current screen. E.g. "https://www.example.com/articles?id=123".
• pageType - The page type, as provided by Taboola - e.g. "<<pageType>>".

  Possible values: "video", "article", "photo", "search", "category", "home".

2. Build a Taboola Compose Unit instance, for that Page:

val tblClassicComposeUnit = tblClassicPage.buildComposeUnit(
    context,
    <placementName>,
    <mode>,
    <placementType>,
    object : TBLClassicListener() {}
)

📘

• placementName - The placement name, as provided by Taboola - e.g. "<<placementName>>", "stories-prod", etc.
• mode - The UI Mode ID of the widget, as provided by Taboola - e.g. "<<mode>>", "thumbnails-feed", etc.
• placementType - The Unit type that the Taboola SDK should return - see below.
• TBLClassicListener - An abstract class used for event handing - see: Event Handing.

Possible values for placementType

📘

For information about the TBLClassicListener abstract class and event handing, see: Event Handing.

3. Fetch content for the Taboola Compose Unit:

tblClassicComposeUnit.fetchContent()

4. Add the Taboola Compose Unit to your Compose UI by invoking the tblClassicComposeUnit.GetClassicUnitView() method:

// Add Taboola unit
tblClassicComposeUnit.GetClassicUnitView() // For SDK 4.0.10 or higher, no param is passed

// For older verions, pass the relevant param:

// For a Column:
// tblClassicComposeUnit.GetClassicUnitView(state = scrollState)

// for a LazyColumn:
// tblClassicComposeUnit.GetClassicUnitView(state = lazyListState)

📘

Params

For SDK 4.0.10 and higher, invoke GetClassicUnitView() without any params.

---

For older versions, pass the relevant param:

• For a Column, pass scrollState.
• For a LazyColumn, pass lazyListState.

👍

Complete Example

For a full, working implementation, see ClassicComposeWidget.kt in our sample app.

For a code snippet demonstrating multiple Units on 1 screen, see below.

🚧

Make sure to fetch content and add the Taboola Compose Unit to your layout as soon as the screen loads.

Ideally, this should be done when the Composable enters the composition.

Multiple Units on 1 screen

The following code snippet illustrates how you might implement multiple Compose Units on 1 screen.

@Composable
fun ArticleWithFeedScreen() {
    val context = LocalContext.current
    val scrollState = rememberScrollState()
    
    // Create a Page
    val tblClassicPage = Taboola.getClassicPage(<pageUrl>, <pageType>)
    
    // Create the 1st Unit - e.g. mid-article Widget:
    val widgetUnit = tblClassicPage.buildComposeUnit(
        context, <placementName1>, <mode1>, <placementType1>, 
        object : TBLClassicListener() {}
    )
    
    // Create the 2nd Unit - e.g. below-article Feed:
    val feedUnit = tblClassicPage.buildComposeUnit(
        context, <placementName2>, <mode2>, <placementType2>, 
        object : TBLClassicListener() {}
    )
    
    // Fetch content for both Units
    LaunchedEffect(Unit) {
        widgetUnit.fetchContent()
        feedUnit.fetchContent()
    }
    
    // Add both Units to the UI
    Column(
        modifier = Modifier
            .fillMaxSize()
            .verticalScroll(scrollState)
    ) {
        // Article content
        Text("Article content...")
        
        // Mid-article Widget
        widgetUnit.GetClassicUnitView()
        // Prior to 4.0.10:
        // widgetUnit.GetClassicUnitView(state = scrollState)
        
        Text("More article content...")
        
        // Below-article Feed
        feedUnit.GetClassicUnitView()
        // Prior to 4.0.10:
        // feedUnit.GetClassicUnitView(state = scrollState)
    }
}

🚧

Sequential vs Parallel

By default, if a given screen/page contains multiple Taboola Units, each Unit loads sequentially, after a fixed interval of time. This enables Taboola to prevent duplications across Units.

To customize this behavior, refer to Advanced Options.

The Click Event

Each time you build a TBLClassicComposeUnit, you pass a subclass of TBLClassicListener that listens for events.

If desired, you can use this listener object to intercept the item click event, and open organic content directly within your app:

val tblClassicComposeUnit = tblClassicPage.buildComposeUnit(
    context, <placementName>, <mode>, <placementType>, 
    object : TBLClassicListener() {
        override fun onItemClick(
            placementName: String, 
            itemId: String, 
            clickUrl: String, 
            isOrganic: Boolean, 
            customData: String?
        ): Boolean {
            // Insert your code here...
            // Return 'false' if you are handling the click event yourself, 
            // or 'true' if you want Taboola SDK to handle the click event.
            // Note: you can override the default behavior for *organic* content only.
            return if (isOrganic) {
                // Handle organic clicks in your app
                navigateToArticle(clickUrl)
                false
            } else {
                true
            }
        }
    }
)

private fun navigateToArticle(clickUrl: String?) {
    // Implement your navigation logic here
    // e.g., use Navigation Compose to navigate to article screen
}

🚧

You can override the default behavior for organic content only

📘

For more information, see Event Handling and onItemClick.

Well Done!

You have completed the basic Compose integration steps!

If everything is working smoothly, take a look at the What's Next section below.

🙈

Taboola content not rendering?

1. Test with the same params as the sample app, and see if those work.
2. Still stuck? Submit a question on our forum.

What's next?

1. For handling clicks and other important events, see Event Handling.
2. To use advanced options while working with the Taboola SDK, see Advanced Options.
3. In order to provide personalized recommendations for impressions in the EU and California, make sure to implement GDPR & CCPA respectively.
4. If you have not already done so, make sure to look at our sample app.
5. Once you are complete, submit your app for review - see the App Verification section.

🚧

IMPORTANT

Prior to launch, you must provide Taboola with a test app for verification. Skipping this step may result in a significant loss of revenue.

See: App Verification