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.

🚧

This integration requires you to connect JavaScript code (in your web content) with Java code (within your Android application).

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");
Taboola.init(publisherInfo);

📘

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

🚧

This initialization is required once per application. It should be done as early as possible - preferably in a sub-class of Application.

Add Taboola JS tags

1. Add the following meta tag to the section of your web content:

<meta name='viewport' content='width=device-width, user-scalable=no'/>

2. Add the following JS script to the section of your web content, and edit the default text:

<script type="text/javascript">
     window._taboola = window._taboola || [];
     _taboola.push({page_type:'auto', url:'page-url'});
     !function (e, f, u, i) {
          if (!document.getElementById(i)){
               e.async = 1;
               e.src = u;
               e.id = i;
               f.parentNode.insertBefore(e, f);
          }
     }(document.createElement('script'),document.getElementsByTagName('script')[0],
     'https://cdn.taboola.com/libtrc/publisher-id/mobile-loader.js',
'tb_mobile_loader_script');
</script>

Editing instructions:

3. For each placement, add the following JS tag to the of your web content, and edit the param values:

<div id="<<containerId>>"></div>
<script type="text/javascript">
     window._taboola = window._taboola || []; 
     _taboola.push({mode: 'mode-here',
     	container: 'container-id-here',
     	placement: 'placement-here',
     	target_type: '<<targetType>>'});

 // Notice - this part is unique to mobile SDK JS integrations!
_taboola["mobile"] = window._taboola["mobile"] || [];
_taboola["mobile"].push({
   publisher:'publisher-id-here'
});
_taboola.push({
   flush: true
});
</script>

📘

Params

• mode - The UI Mode ID of the placement, as provided by Taboola - e.g. '<<mode>>'.
• container - The ID of your HTML element that contains the Taboola content - e.g. '<<containerId>>'.
• placement - The placement name, as provided by Taboola - e.g. '<<placementName>>'.
• target_type - The target type, as provided by Taboola - e.g. '<<targetType>>'.
• publisher - Your Publisher ID (aka Account ID) - a unique, alphabetic string, as provided by Taboola - e.g. '<<publisherID>>'.

4. Load the content within your web view - e.g.:

...

// Build a Taboola WebView - and pass it a reference to your own WebView:
TBLWebPage tblWebPage = Taboola.getWebPage();
TBLWebUnit tblWebUnit = tblWebPage.build(webView, new TBLWebListener() {
    ...
});

// Load content within your own WebView:
String htmlContent = null;
try {
    htmlContent = TBLAssetUtil.getHtmlTemplateFileContent(getApplicationContext(), HTML_CONTENT_FILE_TITLE);
} catch (Exception e) {
    ...
}

webView.loadDataWithBaseURL(base_url, htmlContent, "text/html", "UTF-8", "");

🚧

WebView

If you use loadDataWithBaseUrl(), make sure to set a base URL.

🚧

Flow

If you load content within your own web view - and then register it with the Taboola web view - make sure to refresh its content.

Build Taboola content instances

🚧

Guidelines

1. The goal is to wrap your web view with Taboola services.
2. For each page, initialize 1 TBLWebPage instance, and create 1 TBLWebUnit instance only.
3. Each placement is implemented via a JS tag (not via a TBLWebUnit instance). These JS tags inject Taboola content into your own content.

In your Activity/Fragment Java file:

1. Obtain a Taboola WebPage instance:

TBLWebPage tblWebPage = Taboola.getWebPage();

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

TBLWebUnit tblWebUnit = tblWebPage.build(<yourWebView>, new TBLWebListener() {});

📘

For more detail about TBLWebListener, see: Advanced Options.

3. Obtain a WebSettings instance for your Web View - and add the following settings:

WebSettings settings = <yourWebView>.getSettings();
settings.setJavaScriptEnabled(true);

// (Optional) Enable WebView debugging in your 'debug' builds.
// This makes debugging easier for any issues related to WebViews.
// See: https://developers.google.com/web/tools/chrome-devtools/remote-debugging/webviews
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.KITKAT) {
    WebView.setWebContentsDebuggingEnabled(true);
}

4. Once you have created the single TBLWebUnit instance, your integration is complete. The rest of the work is done by the JS tags. However, if you are using ViewPager, see the instructions below.

Working with ViewPager

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

1. For each JS tag in the of your web content, add lazyFetch: true:

<script type="text/javascript"> 

...
  
_taboola["mobile"].push( {
    lazyFetch: true // If you are using `ViewPager` 
});
</script>

2. Because you added a lazyFetch directive within the JS tag, you must fetch Taboola content via your Java code:

@Override
public void onPageSelected() {
    mWebUnit.fetchContent(); // When using `ViewPager`
}

🚧

ViewPager

If you prefetch more than 1 page using ViewPager:

1. Fetch Taboola content when the next page is visible to the user - i.e. in the onPageSelected method.
2. If the onPageSelected method is fired 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 dark-mode placements, 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:
tblWebUnit.setUnitExtraProperties(extraProperties);

The Click Event

Each time you build a TBLWebUnit, you pass a subclass of TBLWebListener 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:

TBLWebUnit tblWebUnit = 
tblWebPage.build(<Context>, <placementName>, <mode>, <placementType>, new TBLWebListener(){
  
    @Override
    onItemClick(String placementName, String itemId, String clickUrl, boolean isOrganic, @Nullable 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 In our forum.

What's Next?

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