- Android version 2.1 (
android:minSdkVersion="9"
)
- Add the library dependency to your project
compile 'com.taboola:android-sdk:1.3.+@aar'
// include to have clicks open in chrome tabs rather than in a default browser (mandatory)
compile 'com.android.support:customtabs:26.+'
// include if you are using DFP mediation
compile 'com.google.firebase:firebase-ads:11.+'
// include if you are using MoPub mediation
compile('com.mopub:mopub-sdk-banner:4.16.+@aar') {
transitive = true
}
We encourgae developers to use the latest SDK version. In order to stay up-to-date we suggest subscribing to get github notifications whenever there is a new release. For more information check: https://help.github.com/articles/managing-notifications-for-pushes-to-a-repository/
- Include this line in your app’s AndroidManifest.xml to allow Internet access
<uses-permission android:name="android.permission.INTERNET" />
- Any
Activity
which is intended to show TaboolaWidget should include the following attribute, to avoid reloading the Taboola recommendations multiple time unnecessarily:
<activity
android:configChanges="orientation|screenSize|keyboardHidden">
</activity>
To include Taboola recommendations in your app just add a com.taboola.android.TaboolaWidget
to your UI.
TaboolaWidget
subclasses ViewGroup
and behaves just like any other standard Android view.
- Include the XML block in your
Activity
orFragment
layout
<!-- Specify target_type only if it's specified by your Taboola account manager. -->
<com.taboola.android.TaboolaWidget
android:id="@+id/taboola_view"
android:layout_width="match_parent"
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>"
/>
-
Replace the attribute values in the XML according to the values provided by your Taboola account manager (
publisher
,mode
,placement
,url
,page_type
,target_type
) -
In your
Activity
orFragment
code, declare an instance onTaboolaWidget
import com.taboola.android.TaboolaWidget;
//...
private TaboolaWidget taboola;
- In your
Activity
OnCreate
orFragment
OnCreateView
, assign the inflatedTaboolaWidget
defined in the XML to theTaboolaWidget
declared in the previous step, and have it fetch the display the recommendations
taboola = (TaboolaWidget) rootView.findViewById(R.id.taboolaView);
taboola.fetchContent();
- Run your app, your
Activity
/Fragment
should now show Taboola recommendations.
Optionally, you can set the TaboolaWidget attributes directly in code, rather than have them set in XML
TaboolaWidget taboola = (TaboolaWidget) findViewById(R.id.taboola_view);
// Optional - set your content data parameters via code (instead of XML)
taboola.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>")
.setPageId("<my-page-URI>"); //default value is the relative path of the pageUrl provided.
// Optional. Set this parameter only if instructed by your Taboola account manager.
taboola.setTargetType("<my-target-type>");
// fetch and display recommendations
taboola.fetchContent();
The default click behavior of TaboolaWidget is as follows:
- On devices where Chrome custom tab is supported - open the recommendation in a chrome custom tab (in-app)
- Otherwise - open the recommendation in the system default web browser (outside of the app)
TaboolaWidget
allows app developers to intercept recommendation clicks in order to create a click-through or to override the default way of opening the recommended article.
In order to intercept clicks, you should implement the interface com.taboola.android.listeners.TaboolaEventListener
and connect TaboolaWidget
to your event listener. The Activity
or Fragment
in which TaboolaWidget
is displayed might be a good candidate to implement TaboolaEventListener
.
TaboolaEventListener
include the methods:
public boolean taboolaViewItemClickHandler(String url, boolean isOrganic);
public void taboolaViewResizeHandler(TaboolaWidget widget, int height);
This method will be called every time a user clicks a recommendation, right before triggering the default behavior with Intent.ACTION_VIEW
. The app can intercept the click there, and should return a boolean
value.
- Return
false
- abort the default behavior, the app should display the recommendation content on its own (for example, using an in-app browser). (Since 1.2.1 aborts only for organic items!) - Return
true
- this will allow the app to implement a click-through and continue to the default behaviour.
isOrganic
indicates whether the item clicked was an organic content recommendation or not.
Best practice would be to suppress the default behavior for organic items, and instead open the relevant screen in your app which shows that piece of content.
@Override
public boolean taboolaViewItemClickHandler(String url, boolean isOrganic) {
if (isOragnic){
showInAppContent(url);
return false;
}
return true;
}
TaboolaWidget
may resize its height after loading recommendations, to make sure that the full content is displayed (based on the actual widget mode
loaded).
After resize, TaboolaWidget
will call taboolaViewResizeHandler
method of the TaboolaEventListener
, to allow the host app to adjust its layout to the changes. (This behavior may be disabled by setting the property autoResizeHeight
to false
.)
TaboolaWidget
fires app level broadcasts to notify registered objects within the app about certain event. Catching those events might be useful for implementing custom event mediation adapters for ad platforms not natively supported by Taboola Android SDK.
These are the types of broadcasts sent by TaboolaWidget:
GlobalNotificationReceiver.TABOOLA_DID_RECEIVEAD
GlobalNotificationReceiver.TABOOLA_VIEW_RESIZED
GlobalNotificationReceiver.TABOOLA_ITEM_DID_CLICK
GlobalNotificationReceiver.TABOOLA_DID_FAILAD
In order to catch those notifications, you can use the class com.taboola.android.globalNotifications.GlobalNotificationReceiver
-
Create a new
GlobalNotificationReceiver
object in yourActivity
/Fragment
-
In
OnResume()
oronCreate()
, register theGloablNotificationReceiver
to receive broadcasts fromTaboolaWidget
s
LocalBroadcastManager.getInstance(getActivity()).registerReceiver(
mGlobalNotificationReceiver,
new IntentFilter(GlobalNotificationReceiver.GLOBAL_NOTIFICATIONS_KEY)
);
-
Implement
OnGlobalNotificationsListener
interface - this implementing object will be called whenever a broadcast is received -
Register the object which implements
OnGlobalNotificationsListener
with yourGlobalNotificationReceiver
using the methodregisterNotificationsListener
-
Make sure you unregister
GlobalNotificationReceiver
inonPause()
/onDestroy()
LocalBroadcastManager.getInstance(getActivity()).unregisterReceiver(mGlobalNotificationReceiver);
This repository includes an example Android app which uses the Taboola SDK. To use it, just clone this repository and open the project wih Android Studio.
In case you encounter some issues when integrating the SDK into your app, try recreating the scenario within the example app. This might help isolate the problem, and in case you weren't able to solve it, you'll be able to send the example app with your recreated issue to Taboola's support for more help.
Taboola Android SDK supports mediation via these platforms:
In order to configure mediation of Taboola SDK via a 3rd party platform, follow the steps listed below.
-
Include the Taboola SDK in your app as explained under 1.2. Incorporating the SDK
-
In the required platform web management interface, create a new "custom event" network named "Taboola", and fill the parameters as described below.
-
Target impressions from the newly created Taboola network into the required ad-units within your app.
In this way, the platform would automatically use the Taboola SDK when an impression from Taboola should be displayed.
These steps are similar between all platforms, more detailed information can be found in these links for the specific platforms:
-
Class name: com.taboola.android.mediation.DfpCustomEventBanner
-
Parameters: Parameters for the Taboola SDK can be configured either from the DFP web interface or within the code (settings from web interface take precedence over settings configured in code).
- Configuring from DFP web interface: The "parameter" field in the DFP custom event configuration screen, should contain a JSON string with the required properties. Notice that strings should be enclosed within escaped double quotes.
{ \"publisher\":\"<publisher id>\", \"mode\":\"<mode>\", \"url\":\"<url>\", \"placement\":\"<placement>\", \"<page-type>\":\"auto\", \"referrer\":\"<ref url>" }
Notice:
<values>
in the JSON should be replaced with the values provided by your Taboola account manager.- Configuring within the app code: Use the following DFP method to send a NetworkExtrasBundle to the TaboolaSDK. The Bundle should contain key/value pairs with the required parameters.
public AdRequest.Builder addNetworkExtrasBundle (Class<? extends MediationAdapter> adapterClass, Bundle networkExtras)
-
Class name: com.taboola.android.mediation.MoPubCustomEventBanner
-
Parameters: Parameters for the Taboola SDK can be configured either from the MoPub web interface or within the code (settings from web interface take precedence over settings configured in code).
- Configuring from MoPub web interface: The "Custom Class Data" field in the MoPub custom native network configuration screen, should contain a JSON string with the required properties. Notice that strings should be enclosed within double quotes.
{ "publisher": "publisher", "mode": "mode", "url": "http://www.example.com", "article": "auto", "page_type" : "page_type", "referrer": "http://www.example.com/ref" }
- Configuring within the app code: Use the following MoPub method to send a map of LocalExtras to the TaboolaSDK. The Map should contain key/value pairs with the required parameters.
public void setLocalExtras(Map<String, Object> localExtras)
Mandatory. Sets the publisher
(can also be set via XML as publisher
)
Mandatory. Sets the widget display mode
(can also be set via XML as mode
)
Mandatory. Sets the widget placement
(can also be set via XML as placement
)
Mandatory. (Can also be set via XML as page_type
)
Mandatory. (Can also be set via XML as url
)
Optional. Default: "mix"
. (can also be set via XML as target_type
).
Change only if it's specified by your Taboola account manager.
Optional. Default: true
. (can also be set via XML as item_click_enabled
)
Default: true. Determines whether TaboolaWidget
may resize when the loaded content requires (can also be set via XML as auto_resize_height
)
Optional. Attaches a TaboolaEventListener
to the TaboolaWidget
. Allows intercepting clicks and handle height resize events
Allows pushing commands to the TaboolaWidget
, as used in the Taboola JavaScript API
Allows pushing commands to the TaboolaWidget
, as used in the Taboola JavaScript API
After initializing the TaboolaWidget
, this method should be called to actually fetch the recommendations
Resets the TaboolaWidget
- All conents and pushed commands are cleared. New commands must be pushed before fetching data again.
Refreshes the recommendations displayed on the TaboolaWidget
.
Set level of log output of the widget. (default level is ERROR
)
Sets the TaboolaWidget
attributes. You can use keys from class com.taboola.android.utils.Const
(Same as setting every attribute individually via setMode(String mode)
, setPublisher(String publisher)
, etc.)
You can find proguard rules for Taboola Widget in proguard-taboola-widget.pro file. The file contains instructions on which rules to comment/uncomment depending on which parts of the SDK you are using.
This program is licensed under the Taboola, Inc. SDK License Agreement (the “License Agreement”). By copying, using or redistributing this program, you agree to the terms of the License Agreement. The full text of the license agreement can be found at https://github.com/taboola/taboola-android/blob/master/LICENSE. Copyright 2017 Taboola, Inc. All rights reserved.