Widget via JS

📍
DEPRECATION NOTICE
On March 31, 2025, Taboola will sunset SDK 2.
Before then, please make sure to migrate to SDK 4 for Android.

📘
Have you gone through the instructions of Getting started?

Make sure to complete the SDK installation before performing the procedures in the following article

Widget via Native supports Android API 14 and above

📘
See our code examples!
On our Github repository, you may find numerous code examples demonstrating the usage of our features.

📘
Stuck? Confused? Use our Support Forum!
If you need quick help in integrating Taboola SDK into your help, you can use our support forum. The forum is constantly monitored by Taboola Support and will respond within 24 business hours.

Step 1: Init Taboola

Create a PublisherInfo object and init Taboola

PublisherInfo publisherInfo = new PublisherInfo(<MyPublisherId>);
Taboola.init(publisherInfo);

publisherId - Your publisher ID as provided to you by Taboola account manager

Step 2: Init TaboolaJS

In your Application class, enter the following:

public class MyApplication extends Application {
  @Override
  public void onCreate() {
    super.onCreate();
    TaboolaJs.getInstance().init(getApplicationContext());
  }
}

📘
No Application Ending Class?
If your project does not have an Application extending class, create one and then init the TaboolaJs object.

Step 3: Register the WebView

Before loading the actual content in your webview, register the webview that is intended to contain the Taboola widget.

Make sure to unregister your webview before it is destroyed.

To register the Webview, enter the following in your Activity or Fragment code:

@Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        ...
        
        // The WebView must be registered before page is (re)loaded
        TaboolaJs.getInstance().registerWebView(<YOUR_WEBVIEW>);

        // TODO: Load Webview content.
        
        // Note: if you are loading the webview using <YOUR_WEBVIEW>.loadDataWithBaseURL(), baseUrl must be set.
    }

🚧
Important
Taboola recommends to register the webview before loading any content to it. If you register the webview after loading it. please refresh its content

Step 4: Adding HTML/JS Widget Within the WebView

Your HTML page loaded inside the webview should contain the Taboola mobile JS code. This is to bind with the TaboolaJS native SDK and actually display the widget.

If you are already familiar with the Taboola web JS code, notice that although the Taboola mobile JS code is mostly identical to the Taboola web JS code, there are a few minor modifications to be made.

Place this code in the <head> tag of the webview that will contain the Taboola asset. Make sure you replace the values as described below the code example.

<script type="text/javascript">
     window._taboola = window._taboola || [];
     _taboola.push({page-type:'auto', url:'pass-url-here'});
     !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>

page-type key - replace the "page-type" key string with the key that represents the type of the page (video, article, photo, search, category, and home). Please use the value given to you by your Taboola account manager
page-type value - use auto to assign an automated id to the current page. If you wish to pass your own internal ID for the current page, please pass the value instead of auto. For example: article: your_internal_id
pass-url-here: pass the canonical URL (web representation) of the app page - this is needed for Taboola to crawl the page to get contextual and metadata
publisher-id: replace it with the publisher ID received from your Taboola account manager

Place this code anywhere in the <body> tag of the webview that will contain the Taboola asset. Make sure you replace the values as described below the code example.

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

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

container-id: use any id for the actual widget container element
mode-name: replace it with the mode parameter received from your Taboola account manager
Placement Name: use the placement name received from your Taboola account manager
taboola_view_id: (optional) set view id to prevent duplicated between different placements (can use: new Date().getTime()). Make sure to use this value on any Taboola asset located on the same webview
publisher-id-goes-here: replace it with the publisher ID received from your Taboola account manager

🚧
Important!
Do not forget to register your webview with the native TaboolaJS object as described in Step 2

Step 5: Additional Integration Information (Optional)

Intercepting Organic Recommendation Clicks

The SDK enables app developers to change the default behavior when a user clicks on an organic item. For example, you might want to create a click-through or to override the default way of opening the organic recommended article which is opening the click using Chrome custom tab.

To intercept clicks, implement the interface com.taboola.android.api.TaboolaOnClickListener and set in the SDK:

// Implement the interface `com.taboola.android.api.TaboolaOnClickListener`
// `TaboolaOnClickListener` include the methods:
public boolean onItemClick(String placementName, String itemId, String clickUrl, boolean isOrganic);

//In the same Activity/Fragment as `TaboolaWidget` instance:
TaboolaOnClickListener taboolaOnClickListener = new TaboolaOnClickListener() {
 @Override
 public boolean onItemClick(String placementName, String itemId, String clickUrl, boolean isOrganic) {          
     //Code...
     return false;
 }};

//Connect the event listener to your `TaboolaJs` instance
TaboolaJs.getInstance().setOnClickListener(taboolaOnClickListener);

Event: taboolaViewItemClickHandler
boolean taboolaViewItemClickHandler(String url, boolean isOrganic): This method is called every time a user clicks a Taboola Recommendation, immediately before it is handled by the operating system to resolve the relevant action. The return value of this method enables you to control further system behavior (after your own code executes).
URL: The original click URL
isOrganic: Indicates whether the item clicked was an organic Taboola content recommendation or not. Best practice is to suppress the default behavior for organic items and, instead, open the relevant screen in your app which shows that piece of content.
Return value:

Returning false aborts the click's default behavior. The app displays the Taboola Recommendation content on its own (for example, using an in-app browser).
Returning true means that the click is a standard one and that it is sent to the Android OS for default behavior.

Callbacks

If you want to receive an event about the render status, register the following listener in the TaboolaJs object.
Create an OnRenderListener:

OnRenderListener onRenderListener = new  OnRenderListener() {
        @Override
        public void onRenderSuccessful(WebView webView, String placementName, int height) {
                //Code...
        }

        @Override
        public void onRenderFailed(WebView webView, String placementName, String errorMessage) {
                //Code...
        }
    });

TaboolaJs.getInstance().setOnRenderListener(<YOUR_WEBVIEW>,  onRenderListener);

If you want to receive an event about the widget resize status, register the following listener in the TaboolaJs object.
Create an OnResizeListener:

public void onResize(WebView webView, String placementName, int height) {
    Log.d(TAG, "onResize() called with: placementName = [" + placementName + "], height = [" + height + "]");
}

//Register the above listener with the `TaboolaJs` object
TaboolaJs.getInstance().setOnResizeListener(mWebView, this);

You can see a code example of the OnResizeListener here

Listenning to errors within the JS tag

It is possible to listen to an error event, a case where Taboola does not serve ads, within the JS tag inside your webview (inside the <body> tag)

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

// Catch errors within the JS tag
_taboola.push({
   listenTo: "nocontent",
   handler: function (data) {
     // handle the error here  
   };
  
// Notice - this part is unique to mobile SDK JS integrations!
_taboola["mobile"] = window._taboola["mobile"] || [];
_taboola["mobile"].push({
   publisher:"publisher-id-goes-here"
});
</script>

Working with ViewPager

If your app is implementing ViewPager, it is important to load Taboola's content only when the next screen (page) becomes visible.

Add lazyFetch:true to the mobile JS tag inside the <body> tag (see Step 2 above)

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

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

Fetch content when view becomes visible (onPageSelected)

@Override
  public void onPageSelected() {
  	TaboolaJs.getInstance().fetchContent(mWebView);
}

Step 6: Unregister the webview

To unregister a Webview, in your Activity or Fragment code:

@Override
    protected void onDestroy() {
        super.onDestroy();
        TaboolaJs.getInstance().unregisterWebView(<YOUR_WEBVIEW>);
    }

Step 7: Testing and Examples

You can find code examples on our Github repository

You can use our Android SDK Integration Verifier special mode

You can use the following parameters for testing and development. Sponsored items are flagged with an SC: prefix in the title; organic items are flagged with an OC: prefix in the title.

	Mid article widget	Below article widget
`publisher`	"sdk-tester-demo"	"sdk-tester-demo"
`placement`	"Mid Article"	"Below Article"
`PageUrl`	"https://blog.taboola.com"	"https://blog.taboola.com"
`PageType`	"article"	"article"
`TargetType`	"mix"	"mix"
`mode`	"alternating-widget-without-video-1-on-1"	"alternating-widget-without-video-1x4"

Integration Support

Should you have any problems integrating the product, log a ticket with us by emailing your account manager. For non official SLA support you can also check our discussion forum

Widget via JS

📍

📘
Have you gone through the instructions of Getting started?

📘
See our code examples!

📘
Stuck? Confused? Use our Support Forum!

Step 1: Init Taboola

Step 2: Init TaboolaJS

📘
No Application Ending Class?

Step 3: Register the WebView

🚧
Important

Step 4: Adding HTML/JS Widget Within the WebView

🚧
Important!

Step 5: Additional Integration Information (Optional)

Intercepting Organic Recommendation Clicks

Callbacks

Listenning to errors within the JS tag

Working with ViewPager

Step 6: Unregister the webview

Step 7: Testing and Examples

Integration Support

📍

📘Have you gone through the instructions of Getting started?

📘See our code examples!

📘Stuck? Confused? Use our Support Forum!

Step 1: Init Taboola

Step 2: Init TaboolaJS

📘No Application Ending Class?

Step 3: Register the WebView

🚧Important

Step 4: Adding HTML/JS Widget Within the WebView

🚧Important!

Step 5: Additional Integration Information (Optional)

Intercepting Organic Recommendation Clicks

Callbacks

Listenning to errors within the JS tag

Working with ViewPager

Step 6: Unregister the webview

Step 7: Testing and Examples

Integration Support

📘
Have you gone through the instructions of Getting started?

📘
See our code examples!

📘
Stuck? Confused? Use our Support Forum!

📘
No Application Ending Class?

🚧
Important

🚧
Important!