📘

Have you gone through the instructions of Getting started?

• Make sure to complete the [SDK installation](🔗) before performing the procedures in the following article.

• Feed 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: Import and declare 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

## Step 3: Initialize Taboola

Create a `PublisherInfo` object and init Taboola

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

## Step 4: Displaying the TaboolaWidget

You can choose between adding the view using the layout XML or dynamically via the code

### Using Layout XML

1. Add `TaboolaWidget` to your layout XML file

• `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 id 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 into the code" section

2. Add a reference to the view inside your code

3. Set the Feed height to be twice the size of the device screen

4. To show Taboola Feed, request the `fetchContent()` function

🚧

Important!

• 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

Code example:

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

1. Create new Taboola instance

2. Set the Feed height to be twice the size of the device screen

3. Define your Taboola parameters

• `setPublisher` - Your publisher 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 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.

4. Add `taboolaWidget` to your layout

5. To show Taboola Feed, request the `fetchContent()` function

🚧

Important

• 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 screen/fragment is visible to the user. Fetch the content using the `ViewPager.OnPageChangeListener` listener

Code example:

🚧

Important Note

Fetch the widget content only when the screen/fragment is visible to the user. In case you are using <code>ViewPager</code>, fetch the content using the <code>ViewPager.OnPageChangeListener</code> listener.

## Step 5: Set the scrolling behavior

Taboola Feed has a fixed size, usually in the bottom of the screen. When the user is scrolling down the screen, and the Feed is taking up the entire screen, the scrolling is switched from the app into Taboola Feed.

There are two ways of doing so:

• Handled by Taboola's SDK - The SDK will detect when the Feed is taking over the screen and will handover the scroll from the app into the Feed.

• Manually by the app - in case the app is implementing it own custom scrolling by listening to the native OS scroll listener.

### Automatically handled by Taboola's SDK

Set the `setInterceptScroll` function to `true` in order to let Taboola's SDK to identify when it's the right moment to conduct the scroll switch from your app to Taboola's Feed

### Manually by the publisher app

To manually hand over the scroll from the app into the Feed, you need to listen to the `registerScrollToTopListener` that notifies when the Feed is on the top of the screen and is scrolled up.

## Step 6: Show the progress bar

A loading progress bar will show up when switching the scroll to the Taboola Feed. The progress bar will preserve a good UX for your users and smooth the experience when moving the scroll from your app into Taboola Feed.

You can control the progress bar visibility and color by using the following functions:

• `setProgressBarDuration(2)` - sets the progress bar duration in seconds, the default value is 0.7 seconds

• `setProgressBarColor(Color.BLUE)` - sets the color of the UI indicator, by default the value is dark blue (#4472c4). You can also pass the color HEX value by using the `Color.parseColor("#1876D2")` function

• `setProgressBarEnabled(true)` - Activate/deactivate the progress bar when the automatic scroll switch is enabled. The default value is `true`

• `showProgressBar()` - shows the progress bar on the bottom of the screen, when you manually controlling the scroll switch

## Step 7: Additional Integration Information (Optional)

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

3. Implement the interface `OnGlobalNotificationsListener`. Make sure to include the 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:

### 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.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 sent to the Android OS for relevant action resolve. 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:

### Horitzontal scrolling

Taboola Feed can work seamlessly with apps that uses horizontal navigation between screens. When Taboola Feed handles the scrolling (See Step 3 above) it is required to activate the following flag in order to intercept horizontal scrolling gestures and allow the screens navigation. By default this flag is turned off.

### 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 mid-article Widget together with below article Feed. 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 8: Use the Testing publisher

**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 9: Try the Examples

You can find the entire code examples on our [Github repository](🔗)

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

## Step 10: 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](🔗).