📍

This page presumes that you are using Jetpack Compose.

✅

Sample App

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

Multiple Taboola Units on 1 page

By default, if a given screen/page contains multiple Taboola Units, each Unit loads sequentially, with a preset timeout value. This flow enables Taboola to prevent duplicate content across Units.

You can customize this default behavior at the Page level - as described below.

Custom timeout for serial loading

During serial loading, Taboola SDK loads each Unit sequentially: as soon as a given Unit has loaded, the next one starts loading.

A default timeout of 10,000 ms is applied. If a given Unit has not loaded within that time, Taboola SDK will move onto the next one.

To adjust this timeout value, invoke the setSerialFetchTimeout method at the Page level.

After initializing TBLClassicPage:

tblClassicPage.setSerialFetchTimeout(2000)

Parallel loading

By default, Taboola SDK uses serial loading. To load units in parallel, set the setFetchPolicy extra property at the Page level:

🚧

When loading Units in parallel, Taboola cannot guarantee unique content across Units.

After initializing TBLClassicPage:

val extraProperties = hashMapOf("setFetchPolicy" to "1")
tblClassicPage.setPageExtraProperties(extraProperties)

📘

Possible values:

• "0" - serial loading of Units (default).
• "1" - parallel loading of Units.

🚧

Pass the param value as a String.

Same placement across multiple screens

If you need to detach a Unit and re-attach it to a different section of your UI, invoke the setPageUrl() method on the new Unit instance.

Horizontal Scrolling

Taboola SDK supports apps with horizontal navigation between screens.

To enable horizontal navigation, activate the enableHorizontalScroll flag. This allows the Feed to intercept horizontal scroll gestures and navigate between screens.

// Define a map with extra properties
val extraProperties = hashMapOf("enableHorizontalScroll" to "true")

// Set the extra properties in the Unit 
tblClassicUnit.setUnitExtraProperties(extraProperties)

📘

By default, enableHorizontalScroll is turned off.

Working with HorizontalPager

When working with HorizontalPager, make sure to fetch Taboola content when the next page is visible to the user (not before).

@Composable
fun TaboolaPagerScreen() {
    val pagerState = rememberPagerState(pageCount = { 3 })
    val taboolaViewModel: TaboolaClassicViewModel = viewModel()
    
    HorizontalPager(
        state = pagerState,
        modifier = Modifier.fillMaxSize()
    ) { page ->
        when (page) {
            0 -> FirstPageContent()
            1 -> TaboolaClassicScreen(placementInfo = placementInfo, viewModel = taboolaViewModel)
            2 -> ThirdPageContent()
        }
    }
    
    // Handle lazy loading for Taboola page
    LaunchedEffect(pagerState.currentPage) {
        if (pagerState.currentPage == 1) { // Taboola page index
            taboolaViewModel.fetchContent()
        }
    }
}

🚧

HorizontalPager

If you prefetch more than 1 page using HorizontalPager:

1. Fetch Taboola content when the next page is visible to the user - i.e. when pagerState.currentPage changes.
2. If the page change is triggered more than once, make sure to fetch content once only.

Dark Mode

🚧

Dark mode is not supported by default. For dark-mode placements, contact your Taboola Account Manager.

Once Taboola has configured your placements for dark mode, you can use the following code in your ViewModel:

// In your ViewModel
fun enableDarkMode() {
    val extraProperties = hashMapOf("darkMode" to "true")
    tblClassicUnit?.setUnitExtraProperties(extraProperties)
}

Or directly in your Composable:

@Composable
fun TaboolaClassicScreen(
    placementInfo: PlacementInfo,
    isDarkMode: Boolean = false,
    viewModel: TaboolaClassicViewModel = viewModel()
) {
    // ... existing code ...
    
    LaunchedEffect(isDarkMode) {
        viewModel.setDarkMode(isDarkMode)
    }
    
    // ... rest of implementation ...
}

🚧

Swapping Between Dark & Light Themes

Setting extraProperties with "darkMode" "true" will send a request for "dark" content.
For light content do not set the extra Property and avoid using ("darkMode", "false")

💁🏻

Need a hand?

Go ahead! Ask a question in our Support Forum.

Tip: Provide as much detail as possible, including your platform and SDK version.