Widget via Native

📍

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 monitored continuously by Taboola Support and will respond within 24 business hours.

Step 1: Update the AndroidManifest.xml

In addition to the SDK installation update, add the following tag to any activity intended to show the TaboolaWidget. It is important to include the following attribute to avoid reloading the Taboola recommendations multiple times unnecessarily:

<!-- Add to your activity section on the AndroidManifest.xml -->
<activity android:name=".MainActivity" 
   android:configChanges="orientation|screenSize|keyboardHidden">
</activity>

Step 2: Initialize 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 3: Displaying the TaboolaWidget

There are two options of adding TaboolaWidget to your layout. One is using the layout XML file and one is dynamically creating the object in the code.

Layout XML

In your Activityor Fragment layout xml file:

1. Include the Taboola XML declaration and include the TaboolaWidget tag
2. Configure the TaboolaWidget properties.
   In the XML below, replace the following attribute values with those provided by your Taboola account manager: publisher, mode, placement, url, page_type, and `target_type.

<!-- Android SDK 2.2.2 and below: -->
<com.taboola.android.TaboolaWidget
    android:id="@+id/taboola_view"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    taboola:publisher="<publisher-as-supplied-by-taboola>"
    taboola:mode="<mode-as-supplied-by-taboola>"
    taboola:placement="<placement-as-supplied-by-taboola>"
    taboola:url="<public-web-url-which-reflects-the-current-content>"
    taboola:page_type="<my-page-type>"
    taboola:target_type="<my-target-type>"
/>

<!-- Android SDK 2.2.3 and above: -->
<com.taboola.android.TaboolaWidget
    android:id="@+id/taboola_view"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    taboola:tb_publisher="<publisher-as-supplied-by-taboola>"
    taboola:tb_mode="<mode-as-supplied-by-taboola>"
    taboola:tb_placement="<placement-as-supplied-by-taboola>"
    taboola:tb_url="<public-web-url-which-reflects-the-current-content>"
    taboola:tb_page_type="<my-page-type>"
    taboola:tb_target_type="<my-target-type>"
/>

• taboola:tb_mode - Your mode parameter as provided by your Taboola account manager
• taboola:tb_page_type - Your page type parameter as provided by your Taboola account manager
• taboola:tb_placement - Your placement parameter as provided by your Taboola account manager
• taboola:tb_publisher - Your publisher parameter as provided by your Taboola account manager
• taboola:tb_target_type - Your target type parameter as provided by your Taboola account manager
• taboola:tb_url - The full URL of public web page which reflects the current screens content. If the view is used on other screens, please change this value using the setPageUrl function as described below in "Dynamically via the code" section

🚧

Note!

Taboola Widget will automatically resize itself to show its content. When defining the Widget via XML please set the height to wrap_content. The Widget will resize itself when it loads.

3. Import and init the TaboolaWidget.

// Import TaboolaWidget
import com.taboola.android.TaboolaWidget;

// Declare an class member instance TaboolaWidget
private TaboolaWidget taboolaWidget;

📘

Note!

• The TaboolaWidget object is used to define both the Feed and the Widget. The integration is different.
• TaboolaWidget subclass WebView behaves just like any other standard Android view

4. In your Activity's OnCreate() or Fragment's OnCreateView(), find the TaboolaWidget defined in the XML.

taboolaWidget = (TaboolaWidget) <Activity>.findViewById(R.id.taboola_view);

Dynamicly via the code

You can create TaboolaWidget in your code as early as possible in the app lifecycle.

• Your activity's onCreate() method
• Your fragmant's onCreateView() method

//Import TaboolaWidget
import com.taboola.android.TaboolaWidget;

//Declare an class member instance TaboolaWidget
private TaboolaWidget taboolaWidget;

//In your Activity's OnCreate() or Fragment's OnCreateView(), create a new TaboolaWidget instance
taboolaWidget = new TaboolaWidget(<Context>);

//Assign LayoutParams to TaboolaWidget
taboolaWidget.setLayoutParams(new FrameLayout.LayoutParams(FrameLayout.LayoutParams.MATCH_PARENT, FrameLayout.LayoutParams.WRAP_CONTENT));

//Add TaboolaWidget to your layout (This example assumes your parent layout is a FrameLayout with an arbitrary id parent_layout)
FrameLayout frameLayout = (FrameLayout) <Activity>.findViewById(R.id.parent_layout);
frameLayout.addView(taboolaWidget);

//Set the following parameters in your TaboolaWidget instance, before calling fetchContent()
taboolaWidget.setPublisher("<publisher-as-supplied-by-taboola>")
  .setMode("<mode-as-supplied-by-taboola>")
  .setPlacement("<placement-as-supplied-by-taboola>")
  .setPageUrl("<public-web-url-which-reflects-the-current-content>")
  .setPageType("<my-page-type>")
  .setTargetType("<my-target-type>")
	//Optional: sets an internal ID for the current page
  .setPageId("<your-internal-id-for-the-current-page>");

//fetch the content
taboolaWidget.fetchContent();

• setPublisher - Your publisher id parameter as provided by your Taboola account manager
• setMode - Your mode parameter as provided by your Taboola account manager
• setPlacement - Your placement parameter as provided by your Taboola account manager
• setPageUrl - The full URL of a public web page which reflects the current screen's content
• setPageType - Your page type parameter as provided by your Taboola account manager
• setTargetType - Your target type parameter as provided by your Taboola account manager
• setPageId (optional) - An internal identification for the current screen's content. Pass this along the page URL to set the item ID as your internal ID

📘

Missing Parameter Values

If you do not yet have production parameters, contact your Taboola account manager. For testing parameters see further down the page.

Step 4: Fetch content

1. To show TaboolaWidget recommendations, request fetchContent().
2. Adjust the Widget height according to the next step

taboolaWidget.fetchContent();

🚧

Important Note

• To maintain good UX - please fetch content as soon as the screen loads and not when the user reaches the Taboola area on the screen
• When working with ViewPager, Please fetch the widget content only when the next page is visible to the user. You can do it by using the ViewPager.OnPageChangeListener listener

Step 5: Adjust the Widget height

As described in step 2, TaboolaWidget adjusts it height automatically. The height of the widget may dynamically change according to the different UI mode that is loaded in Taboola Backstage. When the widget resizes itself it will also resize the cell the widget is in.

In order to adjust the app layout (the cell that contains the widget) to these changes you can call the taboolaViewResizeHandler method of the TaboolaEventListener.

If wish to adjust the size of Taboola Widget manually, you can do so by setting autoResizeHeight to false and set fixed height for TaboolaWidget manually. Please keep in mind that setting a fixed height for widget will require a code change in case the widget layout changes in the future. We recommend to use dynamic height.

taboolaWidget.setTaboolaEventListener(new TaboolaEventListener() {
 @Override
 public boolean taboolaViewItemClickHandler(String url, boolean isOrganic) {
  doLogic();
  return false; // See step 5 "Intercepting Recommendation Clicks"
 }

 @Override
 public void taboolaViewResizeHandler(TaboolaWidget widget, int height) {
  doResizeLogic();
   //Set the cell height according to the final height value...
 }
});

🚧

Important

In order to allow Taboola increase/decrease the widget size, please keep the Widget size definition as dynamic. Using fixed height can cause native code changes on your app size to reflect the changes

Step 6: Additional Integration Information (Optional)

This section describes some optional points in the integration.

Catching global notifications (broadcasts) from TaboolaWidget

Taboola fires app level broadcasts to notify registered objects within the app about certain events.

To catch those notifications, you can use the class `com.taboola.android.globalNotifications.GlobalNotificationReceiver

1. Create a new GlobalNotificationReceiver object in your Activity/Fragment
2. In onCreate() register GloablNotificationReceiver using the following code:

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    mGlobalNotificationReceiver.registerNotificationsListener(this);
    mGlobalNotificationReceiver.registerReceiver(getActivity());
}

3. Implement the interface OnGlobalNotificationsListener. you can use the following methods:

public void taboolaDidReceiveAd(TaboolaWidget widget);
public void taboolaViewResized(TaboolaWidget widget, int height);
public void taboolaItemDidClick(TaboolaWidget widget);
public void taboolaDidFailAd(TaboolaWidget widget, String reason);

4. Starting from Android SDK 2.5.0 and above we added two tools regarding the taboolaDidFailAd method;

detailedErrorCodes - a flag that activates an explained error reasons strings

• When set to true - the following strings are in use: NO_ITEMS (no fill by Taboola), WRONG_PARAMS (wrong "tb_mode" was used), RESPONSE_ERROR, TIMEOUT (connectivity issue), UNKNOWN_ERROR, and INTERNAL_1
• When set to false (default) - unorganized and unmaintained error reasons strings are in use

autoCollapseOnError - a flag that can add the ability to handle the collapsing/hiding of TaboolaWidget in case of an error.

• When set to false - Only the taboolaDidFailAd method will fire and the publisher handles the collapsing (recommended)
• When set to true (default) - Taboola will handle the collapse in case of an error and the taboolaDidFailAd is not fired

//when autoCollapseOnError=false, the publisher is handling the collapse of
//Taboola in case of an error
//when detailedErrorCodes=true an explained error reasons strings are in use
HashMap<String, String> extraProperties = new HashMap<>();
extraProperties.put("autoCollapseOnError", "false");
extraProperties.put("detailedErrorCodes", "true");
taboolaWidget.setExtraProperties(extraProperties);

5. Make sure you unregister the GloablNotificationReceiver on onDestroy() using this code:

@Override
public void onDestroy() {
    super.onDestroy();
    mGlobalNotificationReceiver.unregisterNotificationsListener();
    mGlobalNotificationReceiver.unregisterReceiver(getActivity());
}

You can see a code example of the GlobalNotificationReceiver here

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 organic clicks, implement the interface com.taboola.android.listeners.TaboolaEventListener:

//TaboolaEventListener include the methods:
public boolean taboolaViewItemClickHandler(String url, boolean isOrganic);
public void taboolaViewResizeHandler(TaboolaWidget widget, int height);

//Example implementation: In the same Activity/Fragment as TaboolaWidget instance:
TaboolaEventListener taboolaEventListener = new TaboolaEventListener() {
@Override
public boolean taboolaViewItemClickHandler(String url, boolean isOrganic) {
   //Code...
   return false;
}

@Override
public void taboolaViewResizeHandler(TaboolaWidget taboolaWidget, int height) {
   //Code...
}};

//Connect the event listener to your TaboolaWidget instance.
taboolaWidget.setTaboolaEventListener(taboolaEventListener);

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 organic Taboola Recommendation content 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 - the click's default behavior is aborted. The app should display the Taboola Recommendation content on its own (for example, using an in-app browser).
• Returning true - the click is a standard one and is sent to the Android OS for default behavior.
  Example:

@Override
public boolean taboolaViewItemClickHandler(String url, boolean isOrganic) {
    ...
    if (isOragnic){
        ...
        showInAppContent(url);
        return false;
    }
    return true;
}

Using more than one Taboola asset on the same screen

It is possible to add more than one Taboola asset on the same screen. For example, placing two Taboola widgets on a feed style screen. When doing so it is important to avoid duplicate items on each asset

To do so, please make sure you do the following:

1. Set the same viewId value for each taboolaWidget object before fetching content. The viewId value must be a string of digits. We recommend using the current epoch timestamp. In any case, the viewId value can not exceed 19 digits.
2. Fetch the content for the second asset only after a response is received for the first asset. Please use the GlobalNotificationReceiver to listen to render is done events

//Sets view ID value for the first item and fetch content
taboolaWidgetMiddleScreen.setViewId("12345");
taboolaWidgetMiddleScreen.fetchContent();

//Sets view ID value for the second item
taboolaFooterScreen.setViewId("12345");


//Fetch content for the 2nd Taboola asset only after the completion of the 1st item
@Override
public void taboolaDidReceiveAd(TaboolaWidget taboolaWidget) {
 Log.d(TAG, "taboolaDidReceiveAd() called with: taboolaWidget = [" + taboolaWidget + "]");
 taboolaFooterScreen.fetchContent();
}

Step 7: Test the integration

To test the integration, you can use our Android SDK Integration Verifier special mode

In addition to that, 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.

Step 8: Code Examples

You can find the entire code examples on our Github repository

For your convenience we listed some quick links for noticable examples:

Step 9: Submit APK for QA

When you have finished the integration, contact your account manager and send a debuggable version of your Android project. Set the project to allow SSL proxying.

You're done!

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