Taboola Event Tracking | Blue Frog Docs

Taboola Event Tracking

Complete guide to implementing standard and custom event tracking with Taboola Pixel for conversion optimization and audience building.

This guide covers all aspects of event tracking with Taboola, including standard events, custom events, and best practices for conversion tracking.

Event Tracking Overview

Taboola event tracking allows you to:

  • Track specific user actions (purchases, signups, downloads)
  • Optimize campaigns for conversions
  • Build custom audiences based on behavior
  • Measure campaign ROI
  • Create lookalike audiences

Standard Events

Taboola provides predefined standard events for common user actions.

Page View Event

Tracks when a user views a page. This should fire on all pages.

window._tfa = window._tfa || [];
window._tfa.push({
  notify: 'event',
  name: 'page_view',
  id: YOUR_ACCOUNT_ID
});

Use Cases:

  • Track overall site traffic
  • Build general retargeting audiences
  • Measure campaign reach

View Content Event

Tracks when a user views content (article, video, product).

window._tfa.push({
  notify: 'event',
  name: 'view_content',
  id: YOUR_ACCOUNT_ID,
  content_id: 'CONTENT_123',
  content_type: 'product', // or 'article', 'video'
  value: 99.99 // Optional: content value
});

Parameters:

  • content_id (required) - Unique identifier for the content
  • content_type (optional) - Type of content viewed
  • value (optional) - Monetary value associated with the content

Example - Product Page:

window._tfa.push({
  notify: 'event',
  name: 'view_content',
  id: 1234567,
  content_id: 'PROD_789',
  content_type: 'product',
  value: 129.99
});

Example - Article Page:

window._tfa.push({
  notify: 'event',
  name: 'view_content',
  id: 1234567,
  content_id: 'ARTICLE_456',
  content_type: 'article'
});

Add to Cart Event

Tracks when a user adds an item to their shopping cart.

window._tfa.push({
  notify: 'event',
  name: 'add_to_cart',
  id: YOUR_ACCOUNT_ID,
  content_id: 'PRODUCT_ID',
  value: 99.99,
  currency: 'USD'
});

Parameters:

  • content_id (required) - Product ID
  • value (required) - Product price
  • currency (required) - Currency code (ISO 4217)

Complete Example:

// E-commerce add to cart
window._tfa.push({
  notify: 'event',
  name: 'add_to_cart',
  id: 1234567,
  content_id: 'SHOE_BLACK_SIZE_10',
  value: 79.99,
  currency: 'USD'
});

Make Purchase Event (Conversion)

Tracks completed purchases. This is the primary conversion event for e-commerce.

window._tfa.push({
  notify: 'event',
  name: 'make_purchase',
  id: YOUR_ACCOUNT_ID,
  revenue: 199.99,
  currency: 'USD',
  order_id: 'ORDER_12345'
});

Parameters:

  • revenue (required) - Total transaction amount (number)
  • currency (required) - Currency code (ISO 4217)
  • order_id (required) - Unique order identifier

Complete Example:

window._tfa.push({
  notify: 'event',
  name: 'make_purchase',
  id: 1234567,
  revenue: 249.98,
  currency: 'USD',
  order_id: 'ORD_2024_001234'
});

Important Notes:

  • Fire only once per transaction
  • Use actual revenue (after discounts, excluding shipping/tax if desired)
  • Revenue must be a number, not string
  • Implement deduplication to prevent double-counting

Lead Event

Tracks lead generation events (form submissions, signups, downloads).

window._tfa.push({
  notify: 'event',
  name: 'lead',
  id: YOUR_ACCOUNT_ID,
  value: 25.00 // Optional: lead value
});

Parameters:

  • value (optional) - Estimated value of the lead

Example - Contact Form:

window._tfa.push({
  notify: 'event',
  name: 'lead',
  id: 1234567,
  value: 50.00
});

Example - Newsletter Signup:

window._tfa.push({
  notify: 'event',
  name: 'lead',
  id: 1234567
});

Custom Events

Create custom events for tracking specific actions unique to your business.

Custom Event Structure

window._tfa.push({
  notify: 'event',
  name: 'custom',
  id: YOUR_ACCOUNT_ID,
  custom_event_name: 'your_event_name',
  param1: 'value1',
  param2: 'value2'
});

Custom Event Examples

Video Play:

window._tfa.push({
  notify: 'event',
  name: 'custom',
  id: 1234567,
  custom_event_name: 'video_play',
  video_id: 'VID_789',
  video_title: 'Product Demo'
});

File Download:

window._tfa.push({
  notify: 'event',
  name: 'custom',
  id: 1234567,
  custom_event_name: 'file_download',
  file_name: 'whitepaper.pdf',
  file_type: 'pdf'
});

Trial Signup:

window._tfa.push({
  notify: 'event',
  name: 'custom',
  id: 1234567,
  custom_event_name: 'trial_started',
  plan_type: 'professional',
  trial_length: 30
});

Account Creation:

window._tfa.push({
  notify: 'event',
  name: 'custom',
  id: 1234567,
  custom_event_name: 'account_created',
  account_type: 'business'
});

User Identification

Track individual users for personalization and custom audiences.

User ID Tracking

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

Best Practices:

  • Set user_id when user logs in
  • Use consistent user identifier across sessions
  • Hash user IDs for privacy

Hashed User ID Example:

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: 1234567,
  user_id: hashedId
});

Implementation Examples

E-commerce Implementation

Product Page:

<script>
  // Product view event
  window._tfa = window._tfa || [];
  window._tfa.push({
    notify: 'event',
    name: 'view_content',
    id: 1234567,
    content_id: '<?php echo $product_id; ?>',
    content_type: 'product',
    value: <?php echo $product_price; ?>
  });
</script>

Add to Cart Button:

<button onclick="addToCart()">Add to Cart</button>

<script>
function addToCart() {
  // Add to cart logic
  // ...

  // Track add to cart event
  window._tfa.push({
    notify: 'event',
    name: 'add_to_cart',
    id: 1234567,
    content_id: productId,
    value: productPrice,
    currency: 'USD'
  });
}
</script>

Order Confirmation Page:

<script>
  // Fire only on successful purchase
  window._tfa = window._tfa || [];

  // Prevent duplicate firing
  if (!sessionStorage.getItem('taboola_purchase_' + orderData.id)) {
    window._tfa.push({
      notify: 'event',
      name: 'make_purchase',
      id: 1234567,
      revenue: <?php echo $order_total; ?>,
      currency: '<?php echo $currency; ?>',
      order_id: '<?php echo $order_id; ?>'
    });

    sessionStorage.setItem('taboola_purchase_' + orderData.id, 'true');
  }
</script>

Lead Generation Implementation

Contact Form:

<form id="contactForm" onsubmit="handleSubmit(event)">
  <input type="text" name="name" required>
  <input type="email" name="email" required>
  <button type="submit">Submit</button>
</form>

<script>
function handleSubmit(event) {
  event.preventDefault();

  // Submit form logic
  // ...

  // Track lead event
  window._tfa.push({
    notify: 'event',
    name: 'lead',
    id: 1234567,
    value: 50.00
  });

  // Continue with form submission
  return true;
}
</script>

Newsletter Signup:

document.getElementById('newsletterForm').addEventListener('submit', function(e) {
  e.preventDefault();

  // Track signup
  window._tfa.push({
    notify: 'event',
    name: 'custom',
    id: 1234567,
    custom_event_name: 'newsletter_signup'
  });

  // Submit form
  this.submit();
});

Content Publisher Implementation

Article View:

<script>
  window._tfa = window._tfa || [];
  window._tfa.push({
    notify: 'event',
    name: 'view_content',
    id: 1234567,
    content_id: '<?php echo $article_id; ?>',
    content_type: 'article'
  });
</script>

Video Play Tracking:

// Using video player API
videoPlayer.on('play', function() {
  window._tfa.push({
    notify: 'event',
    name: 'custom',
    id: 1234567,
    custom_event_name: 'video_play',
    video_id: videoPlayer.getCurrentVideoId(),
    video_title: videoPlayer.getCurrentVideoTitle()
  });
});

Dynamic Event Tracking

Track Events from Data Layer

// Data layer structure
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
  event: 'purchase',
  transactionId: 'ORDER_123',
  transactionTotal: 199.99,
  transactionCurrency: 'USD'
});

// Listen for data layer events
window.dataLayer.push = function(...args) {
  Array.prototype.push.apply(this, args);

  // Process Taboola events
  args.forEach(item => {
    if (item.event === 'purchase') {
      window._tfa.push({
        notify: 'event',
        name: 'make_purchase',
        id: 1234567,
        revenue: item.transactionTotal,
        currency: item.transactionCurrency,
        order_id: item.transactionId
      });
    }
  });
};

Event Wrapper Function

// Create reusable tracking function
const TaboolaTracker = {
  accountId: 1234567,

  trackPageView: function() {
    window._tfa.push({
      notify: 'event',
      name: 'page_view',
      id: this.accountId
    });
  },

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

  trackLead: function(value = null) {
    const event = {
      notify: 'event',
      name: 'lead',
      id: this.accountId
    };

    if (value) {
      event.value = parseFloat(value);
    }

    window._tfa.push(event);
  },

  trackCustomEvent: function(eventName, params = {}) {
    window._tfa.push({
      notify: 'event',
      name: 'custom',
      id: this.accountId,
      custom_event_name: eventName,
      ...params
    });
  }
};

// Usage
TaboolaTracker.trackPurchase(99.99, 'USD', 'ORDER_123');
TaboolaTracker.trackLead(25.00);
TaboolaTracker.trackCustomEvent('video_play', {
  video_id: 'VID_789',
  video_duration: 120
});

Event Deduplication

Prevent duplicate event tracking:

Session-Based Deduplication

function trackUniqueEvent(eventData) {
  const eventKey = JSON.stringify(eventData);
  const sessionKey = 'taboola_event_' + btoa(eventKey);

  if (sessionStorage.getItem(sessionKey)) {
    console.log('Event already tracked in this session');
    return false;
  }

  window._tfa.push(eventData);
  sessionStorage.setItem(sessionKey, 'true');
  return true;
}

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

Order ID-Based Deduplication

const trackedOrders = new Set(
  JSON.parse(localStorage.getItem('taboola_orders') || '[]')
);

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

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

  trackedOrders.add(orderId);
  localStorage.setItem('taboola_orders', JSON.stringify([...trackedOrders]));
}

Testing Events

Console Testing

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

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

// Check event fired
console.log(window._tfa);

// Monitor network requests
// Open Network tab and filter by "taboola"

Test Mode

// Create test mode flag
const isTestMode = window.location.search.includes('taboola_test=true');

function trackEvent(eventData) {
  if (isTestMode) {
    console.log('TEST MODE - Event would fire:', eventData);
    return;
  }

  window._tfa.push(eventData);
}

// Usage
// Visit: yoursite.com?taboola_test=true
trackEvent({
  notify: 'event',
  name: 'make_purchase',
  id: 1234567,
  revenue: 99.99,
  currency: 'USD',
  order_id: 'ORDER_123'
});

Verification

Check Events in Backstage

  1. Log in to Taboola Backstage
  2. Navigate to Tracking > Pixel
  3. View Recent Events
  4. Verify events appear (may take up to 24 hours)

Network Tab Verification

  1. Open browser DevTools (F12)
  2. Go to Network tab
  3. Trigger event
  4. Look for requests to trc.taboola.com
  5. Check request payload contains event data

Event Debugging

// Add event listener to monitor all events
const originalPush = window._tfa.push;
window._tfa.push = function(...args) {
  console.group('Taboola Event Tracked');
  console.log('Event:', args[0]);
  console.log('Timestamp:', new Date().toISOString());
  console.groupEnd();
  return originalPush.apply(this, args);
};

Best Practices

  1. Event Naming - Use descriptive, consistent event names
  2. Required Parameters - Always include required parameters
  3. Data Types - Use correct data types (numbers for revenue, strings for IDs)
  4. Deduplication - Prevent duplicate conversion tracking
  5. Testing - Test all events before production deployment
  6. Documentation - Document all custom events and parameters
  7. Privacy - Hash personal identifiers before sending
  8. Performance - Avoid tracking excessive events that impact page load

Common Issues

Events Not Firing

Check:

  • Pixel is loaded before event fires
  • Account ID is correct
  • Event syntax is correct
  • No JavaScript errors

Revenue Not Tracking

Check:

  • Revenue is a number, not string
  • Currency code is valid (ISO 4217)
  • Revenue value is positive

Duplicate Conversions

Solutions:

  • Implement order ID deduplication
  • Use sessionStorage to prevent re-fires
  • Ensure event fires only once per conversion

Next Steps

↑ Back to top
// SYS.FOOTER