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

Introduction

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

Building a Unit

Each time you build a TBLWebUnit instance, you pass an anonymous subclass of TBLWebListener.

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

TBLWebUnit tblWebUnit = 
tblWebPage.build(<Context>, <placementName>, <mode>, <placementType>, new TBLWebListener(){
  
    // Override any methods of interest.
    // An example for overriding 'onItemClick':
    @Override
    onItemClick(String placementName, String itemId, String clickUrl, boolean isOrganic, @Nullable String customData) {
        Log.d(TAG,"onItemClick"+itemId);
        return super.onItemClick(placementName, itemId, clickUrl, isOrganic, customData);

    }
});

TBLWebUnit tblWebUnit = 
tblWebPage.build(<Context>, <placementName>, <mode>, <placementType>, new TBLWebListener() {});

📘

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

TBLWebListener

TBLWebListener supports the following events (methods). Each of these is explained below.

public abstract class TBLWebListener {
    public TBLWebListener() {
    }

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

    public void onRenderSuccessful(String placementName, int height) {
    }

    public void onRenderFailed(String placementName, String errorMessage) {
    }

    public void onResize(String placementName, int height) {
    }

    public void onUpdateContentCompleted() {
    }

    public void onOrientationChange(int height) {
    }

    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 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. (You can override the default behavior for organic content only.)
• customData - (Optional) Extra data passed from Taboola servers.

📘

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.

onRenderSuccessful

The Taboola placement rendered successfully in your web content.

public void onRenderSuccessful(String placementName, int height) {
}

📘

Params

• placementName - The name of the placement that rendered - e.g. "Feed without video".
• height - The height, in pixels, of the Taboola content rendered.

onRenderFailed

The Taboola placement failed to render in your web content.

public void onRenderFailed(String placementName, String errorMessage) {
}

📘

Params

• placementName - The name of the placement that failed to render - e.g. "Feed without video".
• errorMessage - The error message.

onResize

This event is triggered each time a Taboola placement 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(String placementName, int height) {
}

📘

Params

• placementName - The name of the placement that resized - e.g. "Feed without video".
• 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 TBLWebUnit 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.

onOrientationChange

Orientation of the Android device has changed.

public void onOrientationChange(int height) {
}

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.

Listening for errors within the JS tag

Overview

Typically, event handling is performed within your application code, as described above.

Should you choose to perform event handling within your web content, see the instructions that follow.

Code

As described under Basic Integration, each placement is implemented via a JS tag in the of your web content.

You can optionally add a noContent event listener to each of your JS tags.

<script type="text/javascript">

  ...

// To handle a 'nocontent' error via JS, add this code snippet:
_taboola.push({
    listenTo: "nocontent",
    handler: function(data) {
        // handle the error here  
    }
});

  ...

</script>

💁🏻

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.