Basic Integration
Android Classic - Basic Integration
You are viewing the V4 docs. This is the preferred version for Android.
To select an earlier version, use the nav bar (above):
While reading the documentation, take a look at our Sample App.
Initialize Taboola
The initialization steps in this section are the same for Classic and Web integrations.
- Create a
TBLPublisherInfo
object and initialize Taboola:
TBLPublisherInfo publisherInfo = new TBLPublisherInfo("publisher-id");
// (Optional) Set the desired log level:
Taboola.setLogLevel(logLevel);
Taboola.init(publisherInfo);
IMPORTANT
- Initialization is required once per application. It should be done as early as possible - preferably in a subclass of
Application
.- Failure to initialize successfully will result in Taboola recommendations not being displayed. Make sure that all paths within your application logic result in a successful initialization.
Your Publisher ID (aka Publisher Name) is a unique, alphabetic String. It might contain dashes - e.g.
"<<publisherID>>"
- but not spaces.
During onboarding, Taboola will provide you with your Publisher ID, as well as any other param values needed for your integration.
Build Taboola content instances
Flow 1: Build Taboola content instances via code (recommended)
Overview
- For each screen, obtain a
TBLClassicPage
instance.- For each placement on that screen:
- Use the Page instance to build a Unit. Make sure to use a unique placement name for each Unit.
- Add the Unit instance to the layout via code.
Do not invoke the
addUnitToPage()
method - the Unit instance returned already belongs to that Page instance.
In your Activity/Fragment Java file:
- Obtain a
TBLClassicPage
instance for that screen, passing the relevantpageUrl
andpageType
(e.g."<<pageType>>"
):
TBLClassicPage classicPage =
Taboola.getClassicPage(<pageUrl>, <pageType>);
pageUrl
- A fully-qualified, public URL, with the same content as the current screen. E.g."https://www.example.com/articles?id=123"
.pageType
- The page type, as provided by Taboola - e.g."<<pageType>>"
.
- Build a Taboola Unit instance, for that Page:
TBLClassicUnit classicUnit =
classicPage.build(<Context>, <placementName>, <mode>, <placementType>, new TBLClassicListener() {});
placementName
- The placement name, as provided by Taboola - e.g."<<placementName>>"
,"stories-prod"
, etc.mode
- The UI Mode ID of the widget, as provided by Taboola - e.g."<<mode>>"
,"thumbnails-feed"
, etc.placementType
- The Unit type that the Taboola SDK should return - see below.TBLClassicListener
- An abstract class used for event handing - see: Event Handing.
Possible values for placementType
placementType
Value | Type | Description |
---|---|---|
TBL_PLACEMENT_TYPE.PAGE_MIDDLE | Int | Returns a mid-page Widget. |
TBL_PLACEMENT_TYPE.PAGE_BOTTOM | Int | Returns a page bottom Widget. |
TBL_PLACEMENT_TYPE.FEED | Int | Returns a Taboola Feed. |
For information about the
TBLClassicListener
abstract class and event handing, see: Event Handing.
- Add the Taboola Unit to your layout:
FrameLayout frameLayout = <Activity/Fragment>.findViewById(R.id.parent_layout);
frameLayout.addView(classicUnit);
- Fetch content for the Taboola Unit:
classicUnit.fetchContent();
Flow 2: Add Taboola content instances via XML
Overview
- For each screen, obtain a
TBLClassicPage
instance in your Activity/Fragment Java file- For each placement on that screen:
- In the corresponding layout file, add a
TBLClassicUnit
XML element. Make sure to assign a unique placement name to each element.- In your Activity/Fragment Java file, use the
addUnitToPage()
method to attach theTBLClassicUnit
instance to theTBLClassicPage
instance.Invoke the
addUnitToPage()
method for eachTBLClassicUnit
XML element that you defined.
In your Activity/Fragment Java file:
- Obtain a
TBLClassicPage
instance for that screen, passing the relevantpageUrl
andpageType
(e.g."<<pageType>>"
):
TBLClassicPage classicPage =
Taboola.getClassicPage(<pageUrl>, <pageType>);
pageUrl
- A fully-qualified, public URL, with the same content as this screen e.g."https://www.example.com/articles?id=123"
.pageType
- The page type, as provided by Taboola - e.g."<<pageType>>"
.
In the corresponding layout file:
- Add the Taboola namespace to the top-level View:
<LinearLayout
xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:taboola="http://schemas.android.com/apk/res-auto"
...
>
...
</LinearLayout>
- Add a
com.taboola.android.TBLClassicUnit
element, and edit the attribute values:
<com.taboola.android.TBLClassicUnit
android:id="@+id/taboola_view"
android:layout_width="match_parent"
android:layout_height="wrap_content"
taboola:tb_mode="<mode>"
taboola:tb_placement="<placement-name>"
taboola:tb_target_type="<target-type>"
/>
taboola:tb_mode
- The UI Mode ID of the widget, as provided by Taboola - e.g."<<mode>>"
,"thumbnails-feed"
, etc.taboola:tb_placement
- The placement name, as provided by Taboola - e.g."<<placementName>>"
,"stories-prod"
, etc.taboola:tb_target_type
- The target type, as provided by Taboola - e.g."mix"
.
The Unit will resize itself when it loads. Make sure to set the height to
"wrap_content"
.
In your Activity/Fragment Java file:
- Add the Unit to the relevant Page instance, by invoking the
addUnitToPage()
method.
TBLClassicUnit classicUnit = view.findViewById(R.id.taboola_view);
// Invoke the 'addUnitToPage()' method for Units that were built via XML:
classicPage.addUnitToPage(widgetUnit, <placementName>, <mode>, <placementType>, new TBLClassicListener() {});
placementName
- The placement name, as provided by Taboola - e.g."<<placementName>>"
,"stories-prod"
, etc.mode
- The UI Mode ID of the widget, as provided by Taboola - e.g."<<mode>>"
,"thumbnails-feed"
, etc.placementType
- The Unit type that the Taboola SDK should return - see below.TBLClassicListener
- An abstract class used for event handing - see: Event Handing.
Possible values for placementType
Value | Type | Description |
---|---|---|
TBL_PLACEMENT_TYPE.PAGE_MIDDLE | Int | Returns a mid-page Widget or Limited Feed. |
TBL_PLACEMENT_TYPE.PAGE_BOTTOM | Int | Returns a page bottom Widget. |
TBL_PLACEMENT_TYPE.FEED | Int | Returns a Taboola Feed. |
For information about the
TBLClassicListener
abstract class and event handing, see: Event Handing.
- Fetch content for the Taboola Unit:
classicUnit.fetchContent();
Make sure to add the Taboola Unit to your layout and fetch content as soon as the screen loads.
Ideally, this should be done in
onCreate()
for an Activity - or inonCreateView()
for a Fragment.
Multiple Units on 1 screen
The following code snippet illustrates how you might implement multiple Units on 1 screen.
// Create a Page
TBLClassicPage classicPage = Taboola.getClassicPage(<pageUrl>, <pageType>);
// Use the Page to create the 1st Unit - e.g. mid-article Widget:
TBLClassicUnit widgetUnit = classicPage.build(<Context>, <placementName1>, <mode1>, <placementType1>, new TBLClassicListener() {});
// Add the 1st Unit to the layout:
FrameLayout frameLayout = <Activity/Fragment>.findViewById(R.id.parent_layout);
frameLayout.addView(widgetUnit);
// Fetch content for the 1st Unit:
widgetUnit.fetchContent();
// Use the same Page to create the 2nd Unit - e.g. below-article Feed:
TBLClassicUnit feedUnit = classicPage.build(<Context>, <placementName2>, <mode2>, <placementType2>, new TBLClassicListener() {});
// Add the 2nd unit to the layout:
FrameLayout frameLayout = <Activity/Fragment>.findViewById(R.id.parent_layout);
frameLayout.addView(feedUnit);
// Fetch content for the 2nd Unit:
feedUnit.fetchContent();
For this example, the Units are created via code.
To step through the code, line-by-line, click on the recipe below:
Sequential vs Parallel
By default, if a given screen/page contains multiple Taboola Units, each Unit loads sequentially, after a fixed interval of time. This enables Taboola to prevent duplications across Units.
To customize this behavior, refer to Advanced Options.
The Click Event
Each time you build a TBLClassicUnit
, you pass a subclass of TBLClassicListener
that listens for events.
If desired, you can use this listener object to intercept the item click event, and open organic content directly within your app:
TBLClassicUnit tblClassicUnit =
tblClassicPage.build(<Context>, <placementName>, <mode>, <placementType>, new TBLClassicListener(){
@Override
public boolean onItemClick(String placementName, String itemId, String clickUrl, boolean isOrganic, String customData) {
// Insert your code here...
// Return 'false' if you are handling the click event yourself, or 'true' if you want Taboola SDK to handle the click event.
// Note: you can override the default behavior for *organic* content only.
}
});
You can override the default behavior for organic content only
For more information, see Event Handling and onItemClick.
Well Done!
You have completed the basic integration steps!
If everything is working smoothly, take a look at the What's Next section below.
Taboola content not rendering?
- Test with the same params as the sample app, and see if those work.
- Still stuck? Submit a question on our forum.
What's next?
- For handling clicks and other important events, see Event Handling.
- To use advanced options while working with the Taboola SDK, see Advanced Options.
- In order to provide personalized recommendations for impressions in the EU and California, make sure to implement GDPR & CCPA respectively.
- If you have not already done so, make sure to look at our sample app.
- Once you are complete, submit your app for review - see the App Verification section.
IMPORTANT
Prior to launch, you must provide Taboola with a test app for verification. Skipping this step may result in a significant loss of revenue.
See: App Verification
Updated about 2 months ago