Taboola Pixel Setup, Conversion Events, and Backstage API | OpsBlu Docs

Taboola Pixel Setup, Conversion Events, and Backstage API

Technical guide to Taboola Pixel (TBL) installation, conversion tracking, audience targeting, and Backstage API integration for native ad campaigns.

How Taboola Tracking Works

Taboola uses a JavaScript pixel (commonly referred to as the TBL pixel) to track user behavior on advertiser websites and attribute conversions back to content recommendation clicks. The tracking flow follows this sequence:

  1. A user clicks a Taboola content recommendation on a publisher site
  2. The click routes through Taboola's redirect server (trc.taboola.com), which logs the click and appends a click identifier (tblci) to the destination URL
  3. The Taboola Pixel JavaScript loads on the advertiser's landing page, reads the tblci parameter, and stores it in a first-party cookie
  4. As the user navigates the site, the pixel fires PAGE_VIEW events on each page
  5. When the user completes a conversion action, the pixel fires an event to trc.taboola.com with the stored click ID
  6. Taboola's attribution engine matches the conversion to the original click

The pixel sends data via image beacon or XHR POST to trc.taboola.com. Data collected includes page URL, referrer, tblci value, user agent, viewport dimensions, and event parameters. The tblci parameter is the primary attribution key for click-through conversions. View-through attribution relies on cookie-based matching from Taboola's ad serving.

Installing the Taboola Pixel

Place the base pixel code in the <head> section of every page. Replace YOUR_ACCOUNT_ID with your Taboola Backstage account ID.

<!-- Taboola Pixel - Base Code -->
<script type="text/javascript">
  window._tfa = window._tfa || [];
  window._tfa.push({notify: 'event', name: 'page_view', id: YOUR_ACCOUNT_ID});

  !function (t, f, a, x) {
    if (!document.getElementById(x)) {
      t.async = 1; t.src = a; t.id = x;
      f.parentNode.insertBefore(t, f);
    }
  }(document.createElement('script'),
    document.getElementsByTagName('script')[0],
    '//cdn.taboola.com/libtrc/unip/YOUR_ACCOUNT_ID/tfa.js',
    'tb_tfa_script');
</script>
<noscript>
  <img src="https://trc.taboola.com/YOUR_ACCOUNT_ID/log/3/unip?en=page_view"
    width="0" height="0" style="display:none"/>
</noscript>

Verification

  1. Open browser DevTools > Network tab
  2. Filter requests for trc.taboola.com
  3. You should see a request with en=page_view firing on page load
  4. In Taboola Backstage, navigate to Tracking > Pixel Status to confirm the pixel is active

Conversion Tracking

Fire conversion events by pushing event objects to the _tfa array after the base pixel has loaded.

Standard Conversion Events

<script>
  // Purchase / Transaction
  window._tfa.push({
    notify: 'event',
    name: 'purchase',
    id: YOUR_ACCOUNT_ID,
    revenue: 59.99,
    currency: 'USD',
    orderid: 'TBL-ORD-54321'
  });

  // Lead form submission
  window._tfa.push({
    notify: 'event',
    name: 'lead',
    id: YOUR_ACCOUNT_ID
  });

  // Add to cart
  window._tfa.push({
    notify: 'event',
    name: 'add_to_cart',
    id: YOUR_ACCOUNT_ID,
    revenue: 29.99,
    currency: 'USD'
  });

  // Start checkout
  window._tfa.push({
    notify: 'event',
    name: 'checkout',
    id: YOUR_ACCOUNT_ID
  });

  // Content view / Key page view
  window._tfa.push({
    notify: 'event',
    name: 'view_content',
    id: YOUR_ACCOUNT_ID
  });

  // App install
  window._tfa.push({
    notify: 'event',
    name: 'app_install',
    id: YOUR_ACCOUNT_ID
  });
</script>

Custom Events

<script>
  window._tfa.push({
    notify: 'event',
    name: 'custom_event_name',
    id: YOUR_ACCOUNT_ID,
    revenue: 0,
    currency: 'USD'
  });
</script>

Configuring Conversions in Backstage

  1. Go to Tracking > Conversions in the Backstage dashboard
  2. Click "New Conversion"
  3. Select the event name to track
  4. Set the conversion window (default: 30-day click, 1-day view)
  5. Choose the counting method: "Every" for revenue events, "Once" for leads
  6. Set a conversion value (static or dynamic from the revenue parameter)
  7. Assign the conversion to relevant campaigns

Audience and Retargeting

Pixel-Based Custom Audiences

Build retargeting audiences from pixel data:

  1. In Backstage, go to Audiences > New Audience
  2. Select "Pixel-Based" as the source
  3. Define rules based on URL conditions (contains, equals, starts with) or events fired
  4. Set the membership duration (1-180 days)
  5. Apply audiences to campaigns as targeting or exclusion segments

Audience Types Available

  • Website Visitors - Users who visited specific pages or any page on your site
  • Event-Based - Users who fired specific conversion events (e.g., add to cart but not purchase)
  • Campaign Engagers - Users who clicked your Taboola campaigns
  • CRM/Email Lists - Upload hashed email addresses (SHA-256) for matching
  • Lookalike Audiences - Modeled from any seed audience, with similarity controls from 1% to 10%

Dynamic Audience Example

To create an abandoned cart audience:

  1. Create Audience A: Users who fired add_to_cart in the last 14 days
  2. Create Audience B: Users who fired purchase in the last 14 days
  3. Target Audience A and exclude Audience B in your campaign settings

Server-Side / Backstage API Integration

The Taboola Backstage API provides programmatic access to campaign management, reporting, and audience operations.

Authentication

# Get an OAuth access token
curl -X POST 'https://backstage.taboola.com/backstage/oauth/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=client_credentials'

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 43200
}

Campaign Management

# List all campaigns
curl -X GET 'https://backstage.taboola.com/backstage/api/1.0/YOUR_ACCOUNT_ID/campaigns/' \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...'

# Create a new campaign
curl -X POST 'https://backstage.taboola.com/backstage/api/1.0/YOUR_ACCOUNT_ID/campaigns/' \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Q1 Retargeting - Cart Abandoners",
    "branding_text": "Your Brand",
    "cpc": 0.45,
    "spending_limit": 5000,
    "spending_limit_model": "ENTIRE",
    "start_date": "2026-04-01",
    "marketing_objective": "DRIVE_WEBSITE_TRAFFIC"
  }'

Performance Reporting

# Get campaign-level performance data
curl -X GET 'https://backstage.taboola.com/backstage/api/1.0/YOUR_ACCOUNT_ID/reports/campaign-summary/dimensions/campaign_day_breakdown?start_date=2026-03-01&end_date=2026-03-31' \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...'

Server-Side Conversion API

Send conversions from your server when client-side pixel firing is not possible:

# Report a server-side conversion
curl -X POST 'https://trc.taboola.com/YOUR_ACCOUNT_ID/log/3/s2s-action' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "purchase",
    "revenue": 99.99,
    "currency": "USD",
    "orderid": "ORD-99887",
    "click-id": "GiA1b2c3d4e5...",
    "timestamp": "2026-03-01T10:00:00Z"
  }'

The click-id is the tblci value from the landing page URL. Capture it server-side on the initial page load.

Common Issues

Pixel Not Detected in Backstage

  • Verify the account ID in the pixel code matches your Backstage account
  • Confirm tfa.js loads from cdn.taboola.com (check for CSP or ad blocker interference)
  • Ensure the pixel script is in the <head>, not deferred or loaded conditionally
  • Wait 15-30 minutes after first fire for Backstage to reflect the pixel status

Missing tblci Parameter

  • Some CMS platforms or redirect chains strip URL parameters. Check that tblci persists through your redirect logic
  • If using client-side routing (React Router, Next.js), capture tblci from the initial URL before the router takes over
  • SPAs should read window.location.search on initial load and store tblci in session storage

Conversion Count Discrepancies

  • Compare the attribution window settings in Backstage with your analytics platform
  • Check for duplicate event fires on confirmation pages (page refreshes, back-button navigation)
  • Use the orderid parameter on purchase events to enable server-side deduplication
  • View-through conversions may appear in Taboola but not in your last-click analytics tool

SmartBid Not Optimizing

  • SmartBid requires a minimum of 30 conversions in the past 30 days to optimize effectively
  • Ensure the conversion action assigned to the campaign is the one SmartBid should optimize toward
  • Start with Target CPA at 20-30% above your actual CPA, then reduce gradually

Content Security Policy

Required CSP directives for Taboola:

script-src: cdn.taboola.com
img-src: trc.taboola.com
connect-src: trc.taboola.com

Platform-Specific Considerations

tblci vs Click ID Storage: The tblci parameter can be very long (200+ characters). Ensure your server-side storage (database columns, cookies) can handle the full value. Truncation will break attribution.

Dynamic Creative: Taboola's dynamic creative system rotates headline and thumbnail combinations automatically. The pixel tracks performance per creative variant. When using the API to create campaign items, you can upload multiple titles and thumbnails per item and let Taboola's optimization select winners.

Publisher Blocking: In Backstage under Campaign > Site Blocking, you can exclude specific publisher sites. Monitor the Sites report to identify low-performing publishers and add them to the block list. This is critical for maintaining traffic quality.

SmartBid vs Manual CPC: SmartBid (automated bidding) adjusts CPC per impression based on predicted conversion probability. It requires sufficient conversion volume (30+ per 30 days). For new campaigns with low conversion volume, start with manual CPC and switch to SmartBid once the learning threshold is met.

Taboola Newsroom: Taboola offers a free analytics tool (Taboola Newsroom) for publishers that is separate from the Backstage advertiser platform. Do not confuse the two. Newsroom uses its own tracking script and dashboard.

शीर्ष पर वापस जाएँ