Basic Integration

📍

You are viewing the V3 docs. Note that v4 is now the preferred version for Android.

---

(For the V2 docs, go here.)

✅

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

Initialize Taboola

📘

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

1. Create a TBLPublisherInfo object and initialize Taboola:

TBLPublisherInfo publisherInfo = new TBLPublisherInfo("publisher-id");

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

Taboola.init(publisherInfo);

🚧

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.

📘

Your Publisher ID (aka Publisher Name) is a unique, alphabetic String. It might contain dashes - e.g. "<<publisherID>>" - but not spaces.

📘

During onboarding, Taboola will provide you with your Publisher ID, as well as any other param values needed for your integration.

Build Taboola content instances

Flow 1: Build Taboola content instances via code (recommended)

🚧

Overview

1. For each screen, obtain a TBLClassicPage instance.
2. For each placement on that screen:
   1. Use the Page instance to build a Unit. Make sure to use a unique placement name for each Unit.
   2. Add the Unit instance to the layout via code.

---

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

In your Activity/Fragment Java file:

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

TBLClassicPage classicPage = 
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>>".

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

TBLClassicUnit classicUnit = 
classicPage.build(<Context>, <placementName>, <mode>, <placementType>, new 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. Add the Taboola Unit to your layout:

FrameLayout frameLayout = <Activity/Fragment>.findViewById(R.id.parent_layout);
frameLayout.addView(classicUnit);

4. Fetch content for the Taboola Unit:

classicUnit.fetchContent();

Flow 2: Add Taboola content instances via XML

🚧

Overview

1. For each screen, obtain a TBLClassicPage instance in your Activity/Fragment Java file
2. For each placement on that screen:
   1. In the corresponding layout file, add a TBLClassicUnit XML element. Make sure to assign a unique placement name to each element.
   2. In your Activity/Fragment Java file, use the addUnitToPage() method to attach the TBLClassicUnit instance to the TBLClassicPage instance.

---

Invoke the addUnitToPage() method for each TBLClassicUnit XML element that you defined.

In your Activity/Fragment Java file:

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

TBLClassicPage classicPage = 
Taboola.getClassicPage(<pageUrl>, <pageType>);

📘

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

In the corresponding layout file:

2. Add the Taboola namespace to the top-level View:

<LinearLayout
xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:taboola="http://schemas.android.com/apk/res-auto"
...
>

    ...
    
</LinearLayout>

3. Add a com.taboola.android.TBLClassicUnit element, and edit the attribute values:

<com.taboola.android.TBLClassicUnit
    android:id="@+id/taboola_view"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    taboola:tb_mode="<mode>"
    taboola:tb_placement="<placement-name>"
    taboola:tb_target_type="<target-type>"
/>

📘

• taboola:tb_mode - The UI Mode ID of the widget, as provided by Taboola - e.g. "<<mode>>", "thumbnails-feed", etc.
• taboola:tb_placement - The placement name, as provided by Taboola - e.g. "<<placementName>>", "stories-prod", etc.
• taboola:tb_target_type - The target type, as provided by Taboola - e.g. "mix".

🚧

The Unit will resize itself when it loads. Make sure to set the height to "wrap_content".

In your Activity/Fragment Java file:

4. Add the Unit to the relevant Page instance, by invoking the addUnitToPage() method.

TBLClassicUnit classicUnit = view.findViewById(R.id.taboola_view);

// Invoke the 'addUnitToPage()' method for Units that were built via XML:
classicPage.addUnitToPage(widgetUnit, <placementName>, <mode>, <placementType>, new 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.

5. Fetch content for the Taboola Unit:

classicUnit.fetchContent();

🚧

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

Ideally, this should be done in onCreate() for an Activity - or in onCreateView() for a Fragment.

Multiple Units on 1 screen

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

// Create a Page
TBLClassicPage classicPage = Taboola.getClassicPage(<pageUrl>, <pageType>);

// Use the Page to create the 1st Unit - e.g. mid-article Widget:
TBLClassicUnit widgetUnit = classicPage.build(<Context>, <placementName1>, <mode1>, <placementType1>, new TBLClassicListener() {});
// Add the 1st Unit to the layout:
FrameLayout frameLayout = <Activity/Fragment>.findViewById(R.id.parent_layout);
frameLayout.addView(widgetUnit);
// Fetch content for the 1st Unit:
widgetUnit.fetchContent();

// Use the same Page to create the 2nd Unit - e.g. below-article Feed:
TBLClassicUnit feedUnit = classicPage.build(<Context>, <placementName2>, <mode2>, <placementType2>, new TBLClassicListener() {});
// Add the 2nd unit to the layout:
FrameLayout frameLayout = <Activity/Fragment>.findViewById(R.id.parent_layout);
frameLayout.addView(feedUnit);
// Fetch content for the 2nd Unit:
feedUnit.fetchContent();

📘

For this example, the Units are created via code.

To step through the code, line-by-line, click on the recipe below:

🚧

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 TBLClassicUnit, 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:

TBLClassicUnit tblClassicUnit = 
tblClassicPage.build(<Context>, <placementName>, <mode>, <placementType>, new TBLClassicListener(){
  
    @Override
    public boolean onItemClick(String placementName, String itemId, String clickUrl, boolean isOrganic, String customData) {
        // 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.

    }
});

🚧

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 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