Troubleshooting and Debugging Taboola | Blue Frog Docs

Troubleshooting and Debugging Taboola

Comprehensive guide to diagnosing and resolving common Taboola Pixel issues, conversion tracking problems, and integration challenges.

This guide provides solutions to common Taboola implementation issues, debugging techniques, and best practices for maintaining a healthy Taboola Pixel integration.

Taboola Pixel Troubleshooting

Verify Pixel Installation

Check if the Taboola Pixel is properly loaded on your pages:

// Open browser console and run:
console.log(window._tfa);

// Should return an array of event objects
// Example output:
// [
//   {notify: 'event', name: 'page_view', id: 1234567},
//   {notify: 'event', name: 'make_purchase', id: 1234567, revenue: 99.99}
// ]

Common Pixel Issues

1. Pixel Not Loading

Symptoms:

  • window._tfa is undefined
  • No Taboola requests in Network tab

Diagnosis:

// Check if pixel is blocked
if (typeof window._tfa === 'undefined') {
  console.error('Taboola Pixel not loaded');
}

// Check Network tab for:
// - cdn.taboola.com/libtrc/unip/YOUR_ACCOUNT/tfa.js
// - trc.taboola.com/YOUR_ACCOUNT/log/

Solutions:

  1. Verify script tag is present in HTML
  2. Check for ad blocker interference
  3. Ensure script is not blocked by Content Security Policy
<!-- Add to CSP header if needed -->
<meta http-equiv="Content-Security-Policy"
      content="script-src 'self' 'unsafe-inline' cdn.taboola.com trc.taboola.com">
  1. Verify account ID is correct
  2. Check for JavaScript errors preventing execution

2. Incorrect Account ID

Symptoms:

  • Events fire but no data appears in Taboola Backstage
  • Network requests return 404 errors

Diagnosis:

// Verify account ID in pixel code
const scriptTag = document.getElementById('tb_tfa_script');
if (scriptTag) {
  console.log('Script source:', scriptTag.src);
  // Should be: //cdn.taboola.com/libtrc/unip/YOUR_ACCOUNT_ID/tfa.js
}

// Check events
window._tfa.forEach(event => {
  console.log('Event:', event);
  if (event.id) {
    console.log('Account ID:', event.id);
  }
});

Solutions:

  1. Verify account ID in Taboola Backstage under Account Settings
  2. Ensure account ID is numeric (not publisher ID or site ID)
  3. Update pixel code with correct account ID:
// ✗ Wrong - using publisher ID or site ID
window._tfa.push({notify: 'event', name: 'page_view', id: 'network-id'});

// ✓ Correct - using advertiser account ID
window._tfa.push({notify: 'event', name: 'page_view', id: 1234567});

3. Events Not Firing

Symptoms:

  • Pixel loads but specific events don't trigger
  • Conversions not recorded

Diagnosis:

// Monitor event firing
const originalPush = window._tfa.push;
window._tfa.push = function(...args) {
  console.log('Taboola event fired:', args);
  return originalPush.apply(this, args);
};

// Check event queue
setInterval(() => {
  console.log('Current event queue:', window._tfa);
}, 5000);

Solutions:

  1. Verify event syntax matches Taboola specifications
  2. Ensure events fire on correct page types
  3. Check timing - events should fire after pixel loads
// ✗ Wrong - event fires before pixel loads
window._tfa.push({notify: 'event', name: 'make_purchase', id: 1234567, revenue: 99.99});
// ... pixel script loads here ...

// ✓ Correct - event fires after pixel is ready
<script type="text/javascript">
  window._tfa = window._tfa || [];
  !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/1234567/tfa.js',
  'tb_tfa_script');
</script>
<script type="text/javascript">
  window._tfa.push({notify: 'event', name: 'make_purchase', id: 1234567, revenue: 99.99});
</script>

4. Duplicate Pixel Loading

Symptoms:

  • Multiple pixel scripts on same page
  • Duplicate conversion events
  • Inflated metrics in reporting

Diagnosis:

// Check for multiple pixel instances
const taboolaScripts = document.querySelectorAll('script[src*="taboola.com"]');
console.log(`Found ${taboolaScripts.length} Taboola script(s)`);
taboolaScripts.forEach((script, index) => {
  console.log(`Script ${index + 1}:`, script.src);
});

// Check for duplicate events
const events = {};
window._tfa.forEach(event => {
  const key = JSON.stringify(event);
  events[key] = (events[key] || 0) + 1;
});
Object.entries(events).forEach(([event, count]) => {
  if (count > 1) {
    console.warn(`Duplicate event (${count}x):`, event);
  }
});

Solutions:

  1. Remove duplicate pixel implementations
  2. Ensure pixel loads only once per page
  3. Implement event deduplication:
const firedEvents = new Set();

function trackTaboolaEvent(eventData) {
  const eventKey = JSON.stringify(eventData);

  if (firedEvents.has(eventKey)) {
    console.log('Event already tracked:', eventData);
    return;
  }

  window._tfa.push(eventData);
  firedEvents.add(eventKey);
}

// Usage
trackTaboolaEvent({
  notify: 'event',
  name: 'make_purchase',
  id: 1234567,
  revenue: 99.99,
  order_id: 'ORDER_123'
});

Conversion Tracking Issues

Transactions Not Recorded

Symptoms:

  • Purchases not showing in Taboola reports
  • Conversion tracking incomplete

Diagnosis:

// Check purchase event on confirmation page
console.log('Taboola events:', window._tfa);

// Look for make_purchase event:
// {
//   notify: 'event',
//   name: 'make_purchase',
//   id: 1234567,
//   revenue: 99.99,
//   currency: 'USD',
//   order_id: 'ORDER_123'
// }

Solutions:

  1. Verify purchase event fires only on order confirmation page
  2. Check required parameters are present:
// ✗ Wrong - missing required parameters
window._tfa.push({
  notify: 'event',
  name: 'make_purchase',
  id: 1234567
});

// ✓ Correct - all required parameters
window._tfa.push({
  notify: 'event',
  name: 'make_purchase',
  id: 1234567,
  revenue: 99.99,
  currency: 'USD',
  order_id: 'ORDER_12345'
});
  1. Ensure transaction fires only once:
// Prevent duplicate firing
if (!sessionStorage.getItem('taboola_purchase_tracked')) {
  window._tfa.push({
    notify: 'event',
    name: 'make_purchase',
    id: 1234567,
    revenue: orderData.total,
    currency: 'USD',
    order_id: orderData.id
  });
  sessionStorage.setItem('taboola_purchase_tracked', 'true');
}
  1. Verify currency code is valid (ISO 4217):
const validCurrencies = ['USD', 'EUR', 'GBP', 'CAD', 'AUD', 'JPY'];

function trackPurchase(revenue, currency, orderId) {
  if (!validCurrencies.includes(currency)) {
    console.error(`Invalid currency: ${currency}`);
    return;
  }

  window._tfa.push({
    notify: 'event',
    name: 'make_purchase',
    id: TABOOLA_ACCOUNT_ID,
    revenue: parseFloat(revenue),
    currency: currency,
    order_id: orderId
  });
}

Incorrect Revenue Values

Symptoms:

  • Revenue in Taboola doesn't match actual transaction values
  • Conversions tracked but with $0 value

Diagnosis:

// Verify revenue value format
const revenue = 99.99;
console.log('Revenue type:', typeof revenue); // Should be 'number'
console.log('Revenue value:', revenue);

// Check for common issues
if (typeof revenue === 'string') {
  console.error('Revenue should be number, not string');
}
if (isNaN(revenue)) {
  console.error('Revenue is not a valid number');
}

Solutions:

  1. Ensure revenue is a number, not string:
// ✗ Wrong - revenue as string
window._tfa.push({
  notify: 'event',
  name: 'make_purchase',
  id: 1234567,
  revenue: "99.99", // String
  currency: 'USD'
});

// ✓ Correct - revenue as number
window._tfa.push({
  notify: 'event',
  name: 'make_purchase',
  id: 1234567,
  revenue: 99.99, // Number
  currency: 'USD'
});
  1. Convert string to number if needed:
const revenueString = "99.99";
const revenue = parseFloat(revenueString);

window._tfa.push({
  notify: 'event',
  name: 'make_purchase',
  id: 1234567,
  revenue: revenue,
  currency: 'USD'
});
  1. Remove currency symbols and thousands separators:
function cleanRevenue(revenueString) {
  // Remove currency symbols and commas
  const cleaned = revenueString.replace(/[$,€£¥]/g, '');
  return parseFloat(cleaned);
}

// Usage
const revenue = cleanRevenue("$1,299.99"); // Returns 1299.99

User Identification Not Working

Symptoms:

  • Custom audiences not building
  • Remarketing campaigns not effective

Diagnosis:

// Check user_id event
window._tfa.forEach(event => {
  if (event.name === 'user_id') {
    console.log('User ID event:', event);
  }
});

Solutions:

  1. Set user_id when available:
// For logged-in users
if (typeof userId !== 'undefined' && userId) {
  window._tfa.push({
    notify: 'action',
    name: 'user_id',
    id: TABOOLA_ACCOUNT_ID,
    user_id: userId
  });
}
  1. Hash user identifiers for privacy:
async function hashUserId(userId) {
  const msgBuffer = new TextEncoder().encode(userId.toString());
  const hashBuffer = await crypto.subtle.digest('SHA-256', msgBuffer);
  const hashArray = Array.from(new Uint8Array(hashBuffer));
  return hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
}

// Usage
const userId = 'USER_12345';
const hashedId = await hashUserId(userId);

window._tfa.push({
  notify: 'action',
  name: 'user_id',
  id: TABOOLA_ACCOUNT_ID,
  user_id: hashedId
});

Browser Console Debugging

Enable Debug Mode

// Add debug logging
window._tfa = window._tfa || [];
const originalPush = window._tfa.push;

window._tfa.push = function(...args) {
  console.group('Taboola Event');
  console.log('Event data:', args);
  console.log('Timestamp:', new Date().toISOString());
  console.groupEnd();
  return originalPush.apply(this, args);
};

Network Tab Analysis

What to Check:

  1. Pixel Script Load

    • URL: https://cdn.taboola.com/libtrc/unip/YOUR_ACCOUNT/tfa.js
    • Status: 200 OK
    • Type: script

  2. Event Tracking Requests

    • URL: https://trc.taboola.com/YOUR_ACCOUNT/log/3/unip
    • Status: 200 OK
    • Type: xhr or img

  3. Cookie Sync Requests

    • URL: https://trc.taboola.com/sg/YOUR_ACCOUNT/
    • Status: 200 OK

Common Network Issues:

// Issue: CORS errors
// Solution: Taboola handles CORS automatically, verify no proxy interference

// Issue: 404 Not Found
// Cause: Invalid account ID
// Check account ID in Backstage: Account Settings

// Issue: Request blocked
// Cause: Ad blocker or browser extension
// Test in incognito mode with extensions disabled

Console Error Messages

"Taboola account ID not set"

// ✗ Wrong - missing account ID
window._tfa.push({notify: 'event', name: 'page_view'});

// ✓ Correct - account ID included
window._tfa.push({notify: 'event', name: 'page_view', id: 1234567});

"Invalid event format"

// ✗ Wrong - incorrect parameter names
window._tfa.push({
  event: 'purchase', // Should be 'notify' and 'name'
  value: 99.99 // Should be 'revenue'
});

// ✓ Correct - proper format
window._tfa.push({
  notify: 'event',
  name: 'make_purchase',
  id: 1234567,
  revenue: 99.99,
  currency: 'USD'
});

"Missing required parameter"

// ✗ Wrong - missing currency for purchase
window._tfa.push({
  notify: 'event',
  name: 'make_purchase',
  id: 1234567,
  revenue: 99.99
});

// ✓ Correct - all required parameters
window._tfa.push({
  notify: 'event',
  name: 'make_purchase',
  id: 1234567,
  revenue: 99.99,
  currency: 'USD',
  order_id: 'ORDER_123'
});

Tag Manager Debugging

Google Tag Manager Issues

Preview Mode Testing:

  1. Enable GTM Preview mode
  2. Navigate through site
  3. Check Taboola tags fire on correct triggers
  4. Verify data layer variables populate correctly

Common GTM Issues:

// Issue: Race condition - data layer not ready
// Solution: Use Custom Event trigger

// ✗ Wrong - fires before data available
dataLayer.push({
  event: 'pageview',
  revenue: getRevenue() // async function
});

// ✓ Correct - wait for data
async function pushTaboolaEvent() {
  const revenue = await getRevenue();
  dataLayer.push({
    event: 'taboola_purchase',
    revenue: revenue,
    currency: 'USD'
  });
}

Debugging GTM Variables:

// Check GTM data layer
console.log('GTM Data Layer:', dataLayer);

// Check specific variables
dataLayer.forEach(item => {
  if (item.event === 'taboola_purchase') {
    console.log('Taboola purchase event:', item);
  }
});

Adobe Launch Debugging

Enable debug mode:

// In console
_satellite.setDebug(true);

// Check rule firing
_satellite.track('taboola_conversion');

// View data elements
_satellite.getVar('taboola_account_id');
_satellite.getVar('order_total');

Performance Issues

Slow Page Load Times

Diagnosis:

// Measure pixel impact
performance.mark('taboola-start');

// Pixel loads here

performance.mark('taboola-end');
performance.measure('taboola-load', 'taboola-start', 'taboola-end');

const measure = performance.getEntriesByName('taboola-load')[0];
console.log(`Taboola load time: ${measure.duration}ms`);

Solutions:

  1. Ensure async loading:
<!-- ✓ Correct - async loading -->
<script type="text/javascript">
  window._tfa = window._tfa || [];
  !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/1234567/tfa.js',
  'tb_tfa_script');
</script>
  1. Load pixel after critical content:
// Load Taboola after page is interactive
if (document.readyState === 'complete') {
  loadTaboolaPixel();
} else {
  window.addEventListener('load', loadTaboolaPixel);
}

function loadTaboolaPixel() {
  window._tfa = window._tfa || [];
  const script = document.createElement('script');
  script.src = '//cdn.taboola.com/libtrc/unip/1234567/tfa.js';
  script.async = true;
  script.id = 'tb_tfa_script';
  document.head.appendChild(script);
}
  1. Use requestIdleCallback for non-critical tracking:
if ('requestIdleCallback' in window) {
  requestIdleCallback(() => loadTaboolaPixel());
} else {
  setTimeout(() => loadTaboolaPixel(), 1);
}

Data Discrepancies

Conversion Count Mismatches

Common Causes:

  1. Duplicate Transactions - Event fires multiple times
  2. Missing Deduplication - No order ID tracking
  3. Time Zone Differences - Taboola vs. analytics platform time zones
  4. Attribution Windows - Different attribution models

Solutions:

  1. Implement transaction deduplication:
const trackedOrders = new Set();

function trackPurchase(orderId, revenue, currency) {
  if (trackedOrders.has(orderId)) {
    console.log('Order already tracked:', orderId);
    return;
  }

  window._tfa.push({
    notify: 'event',
    name: 'make_purchase',
    id: TABOOLA_ACCOUNT_ID,
    revenue: revenue,
    currency: currency,
    order_id: orderId
  });

  trackedOrders.add(orderId);
  localStorage.setItem('taboola_orders', JSON.stringify([...trackedOrders]));
}
  1. Use consistent order IDs across platforms
  2. Compare attribution windows in both systems

Event Tracking Discrepancies

Investigation Steps:

  1. Verify events fire on correct pages
  2. Check event parameters match expected values
  3. Ensure consistent event naming
// Verify event consistency
const expectedEvents = ['page_view', 'make_purchase', 'view_content'];

window._tfa.forEach(event => {
  if (event.name && !expectedEvents.includes(event.name)) {
    console.warn('Unexpected event name:', event.name);
  }
});

Testing Tools

Taboola Pixel Helper

Use browser extensions for real-time debugging:

  • Taboola Pixel Helper (Chrome extension)
  • Shows active pixel events
  • Validates event format
  • Displays account configuration

Manual Testing

// Test pixel in console
window._tfa = window._tfa || [];

// Test page view
window._tfa.push({
  notify: 'event',
  name: 'page_view',
  id: 1234567
});

// Test purchase
window._tfa.push({
  notify: 'event',
  name: 'make_purchase',
  id: 1234567,
  revenue: 99.99,
  currency: 'USD',
  order_id: 'TEST_ORDER_' + Date.now()
});

// Verify in Network tab

cURL Testing

# Test pixel endpoint
curl -I https://cdn.taboola.com/libtrc/unip/1234567/tfa.js

# Should return 200 OK

# Test tracking endpoint
curl -X POST "https://trc.taboola.com/1234567/log/3/unip" \
  -H "Content-Type: application/json" \
  -d '{"name":"page_view","id":1234567}'

Best Practices for Prevention

  1. Implement Comprehensive Testing

    • Test pixel in staging before production
    • Validate events in test environment
    • Use automated monitoring

  2. Monitor Pixel Health

    • Set up alerts for pixel failures
    • Check pixel status daily in Backstage
    • Review error reports regularly

  3. Version Control

    • Track pixel changes in version control
    • Document customizations
    • Maintain rollback capability

  4. Regular Audits

    • Monthly pixel verification
    • Quarterly event tracking reviews
    • Annual implementation audits

  5. Documentation

    • Maintain implementation documentation
    • Document custom events and parameters
    • Keep troubleshooting runbook updated

Getting Help

Taboola Support Resources

  1. Taboola Help Center: https://help.taboola.com
  2. Technical Documentation: https://help.taboola.com/hc/en-us/articles/115005660689
  3. Support Ticket: Submit via Taboola Backstage
  4. Account Manager: Contact for account-specific issues

Information to Provide

When contacting support, include:

  • Account ID
  • Affected page URLs
  • Browser console errors
  • Network tab screenshots
  • Steps to reproduce issue
  • Expected vs. actual behavior

Next Steps

↑ Back to top
// SYS.FOOTER