Contao Meta Pixel Event Tracking | OpsBlu Docs

Contao Meta Pixel Event Tracking

How to implement Meta Pixel standard and custom events on Contao. Covers lead events (Lead, ViewContent, CompleteRegistration), custom conversions, and...

Pixel base code must be installed first. See Contao Meta Pixel Setup.

Contao Implementation

Contao uses PHP templates and a modular layout system. Add pixel events via the page layout's custom JavaScript section, or create a custom Contao module. Use $GLOBALS['TL_BODY'] to inject scripts from PHP, or add directly to your theme's fe_page.html5 template.

Standard Events

Meta Pixel standard events are predefined actions that Meta's ad system recognizes for optimization. When you fire standard events with proper parameters, Meta can optimize ad delivery for those specific actions (e.g., optimizing for purchases, not just page views).

Event Priority Guide

Event When to Fire Required Parameters
PageView Every page load (automatic with base pixel) None (automatic)
ViewContent Key content page viewed content_name, content_category
Lead Form submitted content_name
CompleteRegistration Account/newsletter signup content_name, status
Search Site search performed search_string
Contact Contact form or click-to-call content_name

Lead and Engagement Events

// Form submission
fbq('track', 'Lead', {
  content_name: 'Contact Form',
  content_category: 'Inquiry'
});

// Newsletter signup
fbq('track', 'CompleteRegistration', {
  content_name: 'Newsletter',
  status: true
});

// Key page viewed
fbq('track', 'ViewContent', {
  content_name: document.title,
  content_category: 'Page View'
});

// Search performed
fbq('track', 'Search', {
  search_string: 'user query',
  content_category: 'Site Search'
});

Custom Events

For actions not covered by standard events:

// Custom event — not used for standard ad optimization
// but available in Custom Conversions and custom audiences
fbq('trackCustom', 'ShareContent', {
  content_name: 'Article Title',
  method: 'email'
});

fbq('trackCustom', 'VideoWatch', {
  video_title: 'Demo Video',
  percent_watched: 75
});

Standard vs custom events: Always prefer standard events when they match your action — Lead instead of a custom FormSubmit, Purchase instead of a custom OrderComplete. Standard events unlock Meta's ad optimization algorithms. Custom events work for audiences and custom conversions but don't support value-based optimization.

Debugging Events

Meta Pixel Helper

Install the Meta Pixel Helper Chrome extension. Visit your site and click the extension icon — it shows every pixel fire with event name, parameters, and any errors. Green checkmark = working. Yellow/red = issues.

Events Manager Test Events

In Meta Events Manager → Test Events → enter your site URL → interact with your site. Events appear in real-time with full parameter details. This verifies events reach Meta's servers (Pixel Helper only verifies client-side firing).

Console Debugging

// Check if pixel is loaded
console.log('fbq loaded:', typeof fbq === 'function');

// Monitor all pixel fires
if (typeof fbq === 'function') {
  const origFbq = fbq;
  fbq = function() {
    console.log('Pixel event:', Array.from(arguments));
    return origFbq.apply(this, arguments);
  };
}

Custom Conversions

If you can't modify site code to fire standard events, create Custom Conversions in Events Manager that trigger on URL rules:

  1. Events Manager → Custom Conversions → Create
  2. Set rules: URL contains /thank-you or /order-confirmation
  3. Assign a conversion category (Purchase, Lead, etc.)
  4. Meta will count PageView events on matching URLs as conversions

This is a workaround — standard events with parameters are always more accurate for optimization.

Next Steps

Nach oben