AndroidiOSAnnouncementsSupport Forum
SDK DocumentationRecipesAnnouncementsSupport Forum
AndroidiOSAnnouncementsSupport Forum

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

ο»Ώ
  • `publisherId` - Your publisher ID as provided to you by Taboola account manager
## Step 2: Init TaboolaJS
In your Application class, enter the following:
ο»Ώ
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:
ο»Ώ
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. 
ο»Ώ
  • `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. 
ο»Ώ
  • `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:
ο»Ώ
**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 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.
<code>Return value</code>:
  • Returning <code>false</code> aborts the click's default behavior. The app displays the Taboola Recommendation content on its own (for example, using an in-app browser).
  • Returning <code>true</code> 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 <code>TaboolaJs</code> object.
Create an <code>OnRenderListener</code>:
ο»Ώ
Register the above listener with the <code>TaboolaJs</code> object
ο»Ώ
If you want to receive an event about the widget resize status, register the following listener in the `TaboolaJs` object.
Create an `OnResizeListener`:
ο»Ώ
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)
ο»Ώ
### 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.   
  1. Add `lazyFetch:true` to the mobile JS tag inside the `<body>` tag (see Step 2 above)
ο»Ώ
  1. Fetch content when view becomes visible (`onPageSelected`)
ο»Ώ
## Step 6: Unregister the webview
To unregister a Webview, in your `Activity` or `Fragment` code:
ο»Ώ
## 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 <code>SC:</code> prefix in the title; organic items are flagged with an <code>OC:</code> prefix in the title.
Column Titleο»Ώ
Mid article widgetBelow article widget
<code>publisher</code>"sdk-tester-demo""sdk-tester-demo"
<code>placement</code>"Mid Article""Below Article"
<code>PageUrl</code>"https://blog.taboola.com""https://blog.taboola.com"
<code>PageType</code>"article""article"
<code>TargetType</code>"mix""mix"
<code>mode</code>"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](πŸ”—ο»Ώ)ο»Ώ