Event Handling

Overview

When fetching and displaying Taboola content, you may need to handle certain events. Taboola Classic Integration provides a TBLClassicPageDelegate for event handling.

The following events are supported.

didClickPlacementName

An item in the placement was clicked.

👍

Use Case

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

- (BOOL)classicUnit:(UIView*)classicUnit didClickPlacementName:(NSString *)placementName itemId:(NSString *)itemId clickUrl:(NSString *)clickUrl isOrganic:(BOOL)organic customData:(NSDictionary *)customData{
    // Insert your code here...
    // Return 'NO' to handle the click event yourself - or 'YES' for Taboola to handle it.
    // Note: you can override the default behavior for *organic* content only.
    return YES;
}

func classicUnit(_ classicUnit: UIView!, didClickPlacementName placementName: String!, itemId: String!, clickUrl: String!, isOrganic organic: Bool, customData: [AnyHashable : Any]!) -> Bool {
    // 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.
    return true;
}

📘

Callback params

• classicUnit - A reference to the placement, returned as type UIView.
• placementName - The name of the clicked placement - e.g. "<<placementName>>".
• itemId - The ID of the clicked item.
• clickUrl - The Click URL of the clicked item.
• organic - A boolean value, indicating if the clicked item is organic. (If not, then you cannot override the click behavior.)

📘

Return value

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

🚧

You can override the default behavior for organic content only.

didLoadOrResizePlacementName

Returns the loaded placement with its updated height.

🚧

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

🚧

Best practice

Let Taboola SDK manage the cell, so that no event handling is required here

Otherwise - insert your resizing code (for both the Widget and Feed) here.

- (void)classicUnit:(UIView *)classicUnit didLoadOrResizePlacementName:(NSString *)placementName height:(CGFloat)height placementType:(PlacementType)placementType {
    NSLog(@"%@", placementName);
    // If Taboola manages the UI (*recommended*), then NO special handling is required here.
    // Else - insert your code here.
}

func classicUnit(_ classicUnit: UIView!, didLoadOrResizePlacementName placementName: String!, height: CGFloat, placementType: PlacementType) {
    print("Placement name: \(String(describing: placementName)) has been loaded with height: \(height)")
    // If Taboola manages the UI (*recommended*), then NO special handling is required here.
    // Else - insert your code here.
}

📘

Params

• placementName - The name of the placement loaded/resized.
• height - The height, in pixels, of the placement loaded/resized.
• placementType - Widget or Feed.

🚧

For a more detailed example, see: Advanced Options > Publisher manages the cell.

adDidReceiveSuccess

Triggered when an ad loads successfully.

- (void)adDidReceiveSuccess:(UIView *)classicUnit {
    // Insert your code here...
}

func adDidReceiveSuccess(_ classicUnit: UIView!) {
    // Insert your code here...
}

didFailToLoadPlacementName

The Taboola Unit failed to receive an ad.

- (void)classicUnit:(UIView *)classicUnit didFailToLoadPlacementName:(NSString *)placementName errorMessage:(NSString *)error {
    NSLog(@"%@", error);
    // Insert your code here...
}

func classicUnit(_ classicUnit: UIView!, didFailToLoadPlacementName placementName: String!, errorMessage error: String!) {
    print(error as Any)
    // Insert your code here...
}

📘

Params

• placementName - The name of the placement that failed.
• error - The error message. (See below for possible values.)

Possible values for error:

updateContentDidComplete

Triggered when a Taboola Feed has finished updating its content.

👍

Use case

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

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

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

---

Note: The updateContentDidComplete event is not called when the content is first loaded.

- (void)updateContentDidComplete:(UIView *)classicUnit {
    // Insert your code here...  
}

func updateContentDidComplete(_ classicUnit: UIView!) {
    // Insert your code here...
}

🚧

Applies to Feed only.

onEvent

When refreshing content for a given Taboola Unit (see the Use Case above), use onEvent to detect if a failure occurred:

- (void)classicUnit:(UIView *)classicUnit onEvent:(ReportActionType)actionType data:(NSDictionary *)data {
    // Insert your code here...
}

func classicUnit(_ classicUnit: UIView, onEvent actionType: ReportActionType, data: [AnyHashable: Any]) {
    // Insert your code here...
}

📘

Params

• actionType - a numeric enum with the following possible values:
  1. ErrorUnknown (= 1) - An unknown error occurred.
  2. UpdateFailed (= 2) - The Taboola Unit failed to receive an ad, while re-fetching content.

scrollViewDidScrollToTopClassicUnit

When the user scrolls down in your app and encounters a Taboola Feed, the SDK automatically switches the scroll from your app to the Feed (i.e. to the Feed's web view). By default, this scroll switch is handled automatically by Taboola SDK, without any action on your part.

You can override this default behavior and implement the scroll switch yourself. For more detail, see: Advanced Options > Manual Scroll Switch.

💁🏻

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.