Advanced Options

✅

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

Introduction

In this section, we look at more advanced options for working with the Taboola SDK.

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:

HashMap<String, String> extraProperties = new HashMap<>();
extraProperties.put("setFetchPolicy", "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.

Progress Bar

When the user scrolls down in your app and encounters a Taboola Feed, the SDK automatically switches the scroll from your app to the Feed (i.e. to the Feed's WebView).

Each time this occurs, a progress bar displays.

📘

The progress bar ensures a better UX.

It applies for both automatic scroll switch (default) and manual scroll switch (see below).

🚧

The progress bar applies to Feed only.

You can control the progress bar visibility and color, using the following functions.

After building the TBLClassicUnit instance, set the desired progress bar properties:

// Sets the *color* of the Feed's progress bar. (Default is dark blue.)
// Pass any color that complies with @ColorInt.
tblClassicUnit.setProgressBarColor(Color.BLUE);

// Sets the Feed's progress bar *duration*, in seconds. (Default is 0.7 seconds.)
tblClassicUnit.setProgressBarDuration(1);

// Activate/deactivate the Feed's progress bar.
// Default value is 'true'.
tblClassicUnit.setProgressBarEnabled(true);

// Shows the Feed's progress bar at the bottom of the screen. 
// Applies to: *manual scroll switch* (see below).
tblClassicUnit.showProgressBar();

Manual Scroll Switch

When the user scrolls down in your app and encounters a Taboola Feed, the SDK automatically switches the scroll from your app to the Feed (i.e. to the Feed's WebView). By default, this scroll switch is handled automatically by Taboola SDK, without any action on your part.

You can override this default behavior and implement the scroll switch yourself.

1. Define a convenience method for enabling/disabling scrolling of content within the Feed:

public class MyClass {

    private TBLClassicUnit mClassicUnit;

    // To scroll content *within* the Feed, pass 'true'.
    // To scroll content *outside* the Feed, pass 'false'.
    public void enableFeedContentScrolling(boolean enableWidgetScroll) {
        if (mClassicUnit != null) {
            mClassicUnit.setInterceptScroll(enableWidgetScroll);
            mClassicUnit.setScrollEnabled(enableWidgetScroll);
            mClassicUnit.showProgressBar(); // (Optional) If you want a scrollbar
        }
    }

}

2. When the user scrolls down and reaches the end of your content (i.e. the top of the Feed), enable scrolling within the Feed:

// User has scrolled down to the end of your content and reached the Feed:
enableFeedContentScrolling(true);

3. When the user scrolls up and reaches the top of the Feed, disable scrolling within the Feed.

In the TBLClassicListener assigned to the new Unit instance, override the onTaboolaWidgetOnTop event:

public class MyClass {
  
  private TBLClassicUnit mClassicUnit;
  
  ...

  // Override the 'onTaboolaWidgetOnTop' event:
  TBLClassicListener tblClassicListener = new TBLClassicListener() {
       @Override
       public void onTaboolaWidgetOnTop() {
            enableFeedContentScrolling(false);
       }
  }

  // Create the new Unit instance (with tblClassicListener):
  mClassicUnit = 
  tblClassicPage.build(<Context>, <placementName>, <mode>, <placementType>, tblClassicListener);

}

📘

onTaboolaWidgetOnTop is called when the user scrolls up and reaches the top of the Feed content.

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
HashMap<String, String> extraProperties = new HashMap<String, String>() {{ put("enableHorizontalScroll", "true"); }};

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

📘

By default, enableHorizontalScroll is turned off.

Working with ViewPager

1. In your Activity, add the following code to the OnCreate method:

public class MyClass {

    private TBLClassicPaqe mClassicPage;

    @Override
    public View onCreate(Bundle savedInstanceState) {
        mClassicPage = Taboola.getClassicPage(<pageUrl>, <pageType>);
    }

}

2. In each Fragment, add the following code to the onCreateView method:

@Override
public View onCreateView(@NonNull LayoutInflater inflater, ViewGroup container, Bundle savedInstanceState) {
    TBLClassicUnit tblClassicUnit = mClassicPage.build(<Context>, <placementName>, <mode>, <placementType>, new TBLClassicListener() {...});
    tblClassicUnit.fetchContent();
}

Dark Mode

🚧

Configuring Dark Mode

Dark mode is not supported by default. To configure your placements for dark mode, contact your Taboola Account Manager.

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

// Define a map with extra properties:
HashMap<String, String> extraProperties = new HashMap<String, String>() {{ put("darkMode", "true"); }};

// Set the extra properties within the Unit instance:
tblClassicUnit.setUnitExtraProperties(extraProperties);

🚧

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.