📘

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:

## Step 2: Initialize Taboola

Create a `PublisherInfo` object and init Taboola

• `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 `Activity`or `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.

• `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.

📘

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.

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

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

🚧

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.

🚧

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

1. Create a new `GlobalNotificationReceiver` object in your `Activity`/`Fragment`

2. In `onCreate()` register `GloablNotificationReceiver` using the following code:

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

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

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

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

**Event: taboolaViewItemClickHandler** <code>boolean taboolaViewItemClickHandler(String url, boolean isOrganic)</code>. 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). <code>URL</code> - the original click URL <code>isOrganic</code> - 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. <code>Return value</code>:

• Returning <code>false</code> - 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 <code>true</code> - the click is a standard one and is sent to the Android OS for default behavior. Example:

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

## 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 <code>SC:</code> prefix in the title; organic items are flagged with an <code>OC:</code> 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](🔗)