Event Handling

📍

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.

Introduction

When fetching and displaying Taboola content, you may need to handle certain events. The events for Taboola SDK Classic Integration are described below.

Building a Unit

Each time you build a TBLClassicUnit instance, you pass an anonymous subclass of TBLClassicListener.

You can use this listener object to override any events (methods) of interest:

TBLClassicUnit tblClassicUnit = 
tblClassicPage.build(<Context>, <placementName>, <mode>, <placementType>, new TBLClassicListener() {
    
    // Override any methods of interest.
    // An example for overriding 'onItemClick':    
    @Override
    public boolean onItemClick(String placementName, String itemId, String clickUrl, boolean isOrganic, String customData) {
        Log.d(TAG,"onItemClick"+itemId);
        return super.onItemClick(placementName, itemId, clickUrl, isOrganic, customData);
    }
    
});

TBLClassicUnit tblClassicUnit = 
tblClassicPage.build(<Context>, <placementName>, <mode>, <placementType>, new TBLClassicListener() {
});

📘

TBLClassicListener is an abstract class. You can override events (methods) of interest and ignore the rest.

👍

Android Studio 4.x Tip

1. Right-click within the curly braces of your anonymous, inner class (see above code snippet).
2. From the context menu, select: Generate... > Override Methods....
3. Android Studio displays a list of abstract methods that you have not overridden. Double-click on a method to generate stub code.

TBLClassicListener

TBLClassicListener supports the following events/methods. Each of these is explained below.

public abstract class TBLClassicListener {
    public TBLClassicListener() {
    }

    public boolean onItemClick(String placementName, String itemId, String clickUrl, boolean isOrganic, String customData) {
        return true;
    }

    public void onTaboolaWidgetOnTop() {
    }

    public void onAdReceiveSuccess() {
    }

    public void onAdReceiveFail(String error) {
    }

    public void onResize(int height) {
    }

    public void onUpdateContentCompleted() {
    }

    public void onEvent(int actionType, String data) {
    }
}

Events

onItemClick

Item was clicked.

👍

Use Case

Use this method to intercept the item click event, and open organic content directly within your app.

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.
}

📘

Callback params

• placementName - The placement name of the Taboola content that contains the clicked item - e.g. "Feed without video".
• itemId - The ID of the clicked item.
• clickUrl - The Click URL of the clicked item.
• isOrganic - Indicates if the clicked item is organic. (If not, then you cannot override the click behavior.)
• customData - Extra data passed from Taboola servers. (Can be null.)

📘

Return value

• Return true to indicate that Taboola SDK should open the Click URL.
• Return false to prevent Taboola SDK from opening the Click URL (allowing you to handle it).

🚧

You can override the default behavior for organic content only.

onTaboolaWidgetOnTop()

Scrolling of content within the Taboola Feed has reached the top.

public void onTaboolaWidgetOnTop() {
}

onAdReceiveSuccess

Taboola Unit successfully received an ad.

public void onAdReceiveSuccess() {
}

onAdReceiveFail

The Taboola Unit failed to receive an ad.

public void onAdReceiveFail(String error) {
}

📘

Params

• error - The error message. (See below for possible values.)

Possible values for error:

onResize

This event is triggered each time the Taboola Widget resizes its height to match content.

👍

Use Case

Reorganize your layout, after the re-sizing of Taboola content.

🚧

This event is typically triggered several times while Taboola content loads.

public void onResize(int height) {
}

📘

Params

height - The height, in pixels, of the Taboola content rendered.

onUpdateContentCompleted

Content for the Taboola Feed was updated 'upon request'.

👍

Use Case

When your app detects a Pull-To-Refresh gesture, invoke updateContent() on your TBLClassicUnit instance to refresh content.

(For example, in a Taboola News integration, where Taboola Feed covers the entire screen.)

The onUpdateContentCompleted event will trigger once the requested content has updated.

public void onUpdateContentCompleted() {
}

🚧

Applies to:

• Feed only.
• Scenario where updateContent() was invoked.

onEvent

Used for specialized flows only.

public void onEvent(int actionType, String data) {
}

📘

For more information about supported use cases, speak to your Taboola Account Manager.

💁🏻

Need a hand?

Go ahead! Ask a question in our Support Forum.

Tip: Provide as much detail as possible, including your platform and SDK version.