Overview

You can optionally subscribe to events using _taboola.push with a listenTo parameter. When the specified event occurs, TRECS triggers a customEvent that calls your handler function.

📘

Common use cases

• Monitoring placement health - Track when placements successfully render or fail, helping you troubleshoot integration issues and monitor performance.
• Custom analytics tracking - Send events to your analytics platform when standard tracking methods are challenging or insufficient.
• User engagement measurement - Measure how users interact with Taboola content (clicks, visibility) to optimize placement positioning.
• Third-party integrations - Trigger actions in other systems when users engage with recommended content.
• A/B testing - Track placement visibility and engagement for different page layouts or user segments.
• HP4U tracking - See: HP4U Events

Basic implementation

function callBack(data) {   
    console.log(data.detail);
}

window._taboola = window._taboola || []; 
_taboola.push({
    listenTo: 'visible', 
    handler: callBack
});

The event data is passed to the callback function under the detail property, as shown in the example above.

Available events

Key terms

Before diving in, take a moment to review some key terms:

📘

Software components

• TRECS - Taboola Recommendation Engine Client Side. The JavaScript library that powers Taboola's content recommendations on publisher websites.
• TRC - Taboola Recommendation Core. The backend service that processes recommendation requests and returns content.
• TRCImpl - The core implementation object within TRECS that handles the recommendation logic and rendering.
• Engine - The core TRECS engine that coordinates content loading, rendering, and user interactions.

📘

Placements

• Placement - A Taboola unit that displays content in a specified location (e.g. "below article").
• Widget - A Taboola unit with a fixed number of items.
• Feed - A Taboola unit with a scrolling list of items.
• Next-up - A Taboola unit that displays once the user has finished reading an article.
• Vignette - A Taboola unit that displays as a full-screen overlay.

Events

The following events are available for all publishers:

📘

Event availability

Most events are available by default, but some require specific publisher configuration settings to be enabled.

Event data structures

Render and visible event data

Events: render, visible

{
    variant: "test variant if exists",
    container: "DOM element",
    placement: "placement data",
    baseMode: "mode name",
    mode: "mode name",
    itemCount: "number of items in placement",
    items: "items data"
}

Click event data

Event: click

{
    slot: "index number",
    id: "Taboola id",
    type: "item type",
    title: "item title",
    url: "click url from response",
    linkTarget: "target url",
    mode: "mode name",
    placement: "placement id",
    baseMode: "mode name",
    variant: "test variant if exists",
    itemCount: "number of items",
    loggerUrl: "click url generated in TRECS"
}

👍

Best practice

Always check for the existence of event data properties before using them, as the data structure may vary depending on the specific event and configuration.

Expected flow

The typical sequence of external events follows this pattern:

🚧

HP4U

Additional events are available for HP4U. See: HP4U Events