Taboola Pixel

Description

Taboola Pixel is used to gather data about user actions to optimize the campaigns. It also allows to track conversions, and target custom audiences.

App Coverage

App	Integrated
UK	✅
DE	✅

Integration

Taboola Pixel is integrated via browser script. An overview of the integration methods can be found via the links below:

Debug Tools

An overview of the debugging tools can be found via the links below:

Testing Tool
Taboola Pixel Helper (Chrome extension)

Notes

Before integrating Taboola Pixel, note the following:

Event name and properties should match the defined conversion
Validate conversion values and currency when sending revenue events
The base pixel script is loaded once per page, keyed by a fixed script element id, so re-initializing the provider does not inject it twice
Revenue events require revenue, currency, and orderid — an event missing any of them is sent as a plain event instead

Plugin Usage Guide

The @releafuk/analytics package provides a custom Taboola plugin through the taboolaProvider() factory function. Taboola is integrated by loading the _tfa pixel script directly, without a tag manager.

Configuration

The taboolaProvider() factory accepts the config parameter that should satisfy the TaboolaConfig type:

type TaboolaConfig = {
  accountId: string;
  enabled?: boolean;
  revenueEventId?: string | number;
};

Option	Required	Default	Description
`accountId`	Yes	-	Taboola account id. `init()` logs an error and leaves the provider in an `error` state if it is missing.
`enabled`	No	`true`	Controls whether the provider loads the pixel and sends events. Use `false` to keep the provider registered but disabled for an environment.
`revenueEventId`	No	`accountId`	Event id used for revenue events, when Taboola issued a separate id for revenue tracking. Falls back to `accountId` when not set.

The provider requires advertising consent — it only runs once that consent key is granted.

Script loading

init() pushes a page_view notify event onto window._tfa and injects //cdn.taboola.com/libtrc/unip/<accountId>/tfa.js, tagged with a fixed script element id so a second init() call does not load the pixel twice.

Usage

Define Taboola event parameters under the taboola provider key, then register taboolaProvider() when creating the analytics service:

import {
  createAnalyticsService,
  createEvent,
  createEventDefinition,
  createEventRegistry,
  taboolaProvider,
} from "@releafuk/analytics";

const leadSubmitted = createEvent<undefined, "LeadSubmitted">({
  name: "LeadSubmitted",
});

const events = createEventRegistry().register(
  createEventDefinition(leadSubmitted, {
    providers: {
      taboola: () => ({
        event: "lead",
      }),
    },
  }),
);

export const analytics = createAnalyticsService({
  app: "releaf",
  events,
  providers: [
    taboolaProvider({
      accountId: import.meta.env.PUBLIC_TABOOLA_ACCOUNT_ID,
    }),
  ],
  consent: {
    default: {
      analytics: "denied",
      advertising: "denied",
      functionality: "denied",
      adUserData: "denied",
      adPersonalization: "denied",
    },
  },
});

await analytics.init();

Plain events are pushed as { notify: "event", name: event, id: accountId }.

Revenue events

To report revenue, set meta.eventType to "revenue" and include revenue, currency, and orderid in params. The provider pushes those as the pixel’s revenue payload, keyed by revenueEventId when configured, otherwise by accountId:

const purchaseCompleted = createEvent<
  {
    orderId: string;
    total: number;
    currency: string;
  },
  "PurchaseCompleted"
>({
  name: "PurchaseCompleted",
});

const events = createEventRegistry().register(
  createEventDefinition(purchaseCompleted, {
    providers: {
      taboola: (data) => ({
        event: "purchase",
        params: {
          revenue: data.total,
          currency: data.currency,
          orderid: data.orderId,
        },
        meta: { eventType: "revenue" },
      }),
    },
  }),
);

An event with meta.eventType: "revenue" but missing revenue, currency, or orderid is sent as a plain event instead.