Pixel Events - Facebook Tag API

In this document

• Overview
• Setup
• Standard and Custom events
• Conversion and Custom Audience Events Together
• Pixel Events in buttons and Advanced Scenarios
• Using Facebook Ads Extensions

Overview

You can use the JavaScript Tag API to track custom audience and conversion events, providing the capability to send multiple and customized events on one page, and include data beyond just the referral URL. You can then use these events and associated custom data in Custom Audiences from Your Website Rules.

Setup

To use the JavaScript Tag API, you must first load the Custom Audience Pixel on your page. Afterwards, the Tag API can then be used to fire the desired Conversion and Custom Audience events. The JavaScript code is:

<!-- Facebook Pixel Code -->
<script>
!function(f,b,e,v,n,t,s){if(f.fbq)return;n=f.fbq=function(){n.callMethod?
n.callMethod.apply(n,arguments):n.queue.push(arguments)};if(!f._fbq)f._fbq=n;
n.push=n;n.loaded=!0;n.version='2.0';n.queue=[];t=b.createElement(e);t.async=!0;
t.src=v;s=b.getElementsByTagName(e)[0];s.parentNode.insertBefore(t,s)}(window,
document,'script','https://connect.facebook.net/en_US/fbevents.js');

fbq('init', '<FB_PIXEL_ID>');
fbq('track', "PageView");
</script>
<noscript><img height="1" width="1" style="display:none"
src="https://www.facebook.com/tr?id=<FB_PIXEL_ID>&ev=PageView&noscript=1"
/></noscript>
<!-- End Facebook Pixel Code -->  

Automatic Configuration

The Facebook pixel will send button click and page metadata (such as data structured according to Opengraph or Schema.org formats) from your website to improve your ads delivery and measurement and automate your pixel setup. To configure the Facebook Pixel to not send this additional information, in the Facebook Pixel Base code, add fbq('set', 'autoConfig', 'false', '<FB_PIXEL_ID>') above the init call.

Standard and Custom events

The Custom Audience pixel has 9 standard events that are useful for both building audiences and tracking your website conversions back to your advertising efforts for reporting purposes. Please note, if you use oCPM, optimizing for a standard event is required in order to optimize your campaign delivery.

Events can be reported using fbq('track', 'eventName', {customData}); where customData is optional. The first value, 'track', should not be altered.

To report a standard conversion event, use one of the 9 standard events in the fbq track call. To report a legacy conversion event, use a Conversion Pixel ID as the eventName in the fbq track call. For both, you should include value and currency in the customData object. Additionally, if you are not interested in tracking or optimizing for conversions, you can pass custom event names into the trackCustom call.

Below are the 9 standard events:

Parameters

Here is a description for all the recommended parameters to be passed with the Standard events as described in the table above.

Examples

// Standard event (can be used for conversion tracking
// and optimizing in addition to audience building)
fbq('track', 'Purchase', {currency: 'EUR', value: 15.23});

// Legacy conversion event (can only be used for conversion 
// tracking and optimizing)
fbq('track', '125653456', {currency: 'USD', value: 30.00});

// Custom event (can only be used for audience building)
fbq('trackCustom', 'MyCustomEvent', {custom_param: 'custom_value'});

Utilizing Parameters in Events

Audience building can be enhanced by the passing of customData into the track and trackCustom calls. This allows you to define more granular data around events. Building audiences has the added benefit of being able to use trackCustom in order to build more specific audiences that are not covered by 1 of the 9 standard events. You can continue to pass customData into these events for more granular audience building. However, you can not track or optimize for conversions based on custom events at the current time.

Examples

// Reach customers that viewed a product in the 'Shoes' category
// with a price greater than $100
fbq('track', 'ViewContent', {
  content_name: 'Really Fast Running Shoes',
  content_category: 'Apparel & Accessories > Shoes',
  content_ids: ['1234'],
  content_type: 'product',
  value: 0.50,
  currency: 'USD'
 });
  
// Multiple events can also be added to each page.  Ex: Reach visitors
// based on information about them and how they got to the page
// that Registered in the last n days
fbq('track', 'ViewContent', {
  content_name: 'The Avengers Trailer',
  content_category: 'Entertainment',
  value: 1.50,
  currency: 'USD',
  referrer: document.referrer,
  userAgent: navigator.userAgent,
  language: navigator.language
});

fbq('track', 'CompleteRegistration', {currency: 'USD', value: 0.75});

// You can use non-standard event names for audience building when you
// do not need to track or optimize for conversions.
fbq('trackCustom', 'FrequentShopper', {
  num_purchases: 8,
  average_order: 245.24,
  favorite_category: 'Sporting Goods'
});

Putting it all together

There are many occasions where you may want to both build an audience and measure a conversion event at the same time. You can do so using the same event as long as you use one of the 9 standard events.

To do this, include both the base code and the fbq call underneath the base code on page load. The fbq call can either be inside the base code tag underneath the PageView track call or it can be inside its own script tag below the base code.

<!-- Facebook Pixel Code -->
<script>
!function(f,b,e,v,n,t,s){if(f.fbq)return;n=f.fbq=function(){n.callMethod?
n.callMethod.apply(n,arguments):n.queue.push(arguments)};if(!f._fbq)f._fbq=n;
n.push=n;n.loaded=!0;n.version='2.0';n.queue=[];t=b.createElement(e);t.async=!0;
t.src=v;s=b.getElementsByTagName(e)[0];s.parentNode.insertBefore(t,s)}(window,
document,'script','https://connect.facebook.net/en_US/fbevents.js');
// Insert Your Custom Audience Pixel ID below. 
fbq('init', '<FB_PIXEL_ID>');
fbq('track', 'PageView');
</script>
<!-- Insert Your Custom Audience Pixel ID below. --> 
<noscript><img height="1" width="1" style="display:none"
src="https://www.facebook.com/tr?id=<FB_PIXEL_ID>&ev=PageView&noscript=1"
/></noscript>
<!-- End Facebook Pixel Code -->

<script>
// Assuming a single item is purchased
fbq('track', 'Purchase', {
  content_name: 'Really Fast Running Shoes',
  content_category: 'Apparel & Accessories > Shoes',
  content_ids: ['1234'],
  content_type: 'product',
  value: 199.50,
  currency: 'USD'
});

// Assuming multiple items are purchased
fbq('track', 'Purchase', {
  content_ids: ['1234', '4642', '35838'],
  content_type: 'product',
  value: 247.35,
  currency: 'USD'
});

// Assuming multiple items are purchased using `contents` to provide more information
fbq('track', 'Purchase', {
  contents: [
    {
      'id': '1234',
      'quantity': 2,
      'item_price': 10
    },
    {
      'id': '4642',
      'quantity': 1,
      'item_price': 5
    }
  ],
  content_type: 'product',
  value: 25.00,
  currency: 'USD'
});
</script>

When a page with the above code loads, an event named 'Purchase' will fire and measure a conversion and also allow you to build an audience off of the event name and parameters.

Pixel Events in buttons and Advanced Scenarios

Typically you track conversions and events using Facebook Pixel by loading it with a page and firing Standard Events such as ViewContent or Purchase.

Whenever you want to track things in a different moment such as after a button click, you might need some additional work. Check our documentation on this and other more advanced use cases.

Facebook Ads Extensions

Facebook has built extensions to make it easier to install the pixel on your website. If you use one of those extensions, all standard pixel events will be installed. Those platforms might ask if you want to send additional customer data through the pixel (a feature called Advanced Matching) in order to improve pixel tracking capabilities. Learn more about Advanced Matching.

If part of your customers are in the European Union, you may need to take further action to comply with European data protection laws.