Marketing API Version

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 -->  

The default pixel code fires the PageView event, which can be used to create audience rules that match referral URLs.

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:

Event NameEvent DescriptionParametersRequired Parameters

ViewContent

When a key page is viewed such as a product page, e.g. landing on a product detail page

value, currency, content_name, content_type, content_ids, contents

None. For Dynamic Product Ads; content_ids or contents, and content_type are required.

Search

When a search is made, e.g. when a product search query is made

value, currency, content_category, content_ids, contents, search_string

None

AddToCart

When a product is added to the shopping cart, e.g. click on add to cart button

value, currency, content_name, content_type, content_ids, contents

None. For Dynamic Product Ads; content_ids or contents, and content_type are required.

AddToWishlist

When a product is added to a wishlist, e.g. click on add to wishlist button

value, currency, content_name, content_category, content_ids, contents

None

InitiateCheckout

When a person enters the checkout flow prior to completing the checkout flow, e.g. click on checkout button

value, currency, content_name, content_category, content_ids, contents, num_items

None

AddPaymentInfo

When a payment information is added in the checkout flow, e.g. click / LP on save billing info button

value, currency, content_category, content_ids, contents

None

Purchase

When a purchase is made or checkout flow is completed, e.g. landing on thank you/confirmation page

value, currency, content_name, content_type, content_ids, contents, num_items

value, currency. For Dynamic Product Ads; content_ids or contents, and content_type are required.

Lead

When a sign up is completed, e.g. click on pricing, signup for trial

value, currency, content_name, content_category

None

CompleteRegistration

When a registration form is completed, e.g. complete subscription/signup for a service

value, currency, content_name, status

None

Parameters

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

Parameter NameParameter Description

value

value of a user performing this event to the business

currency

currency for the value specified.

content_name

Name of the page/product

content_category

Category of the page/product

content_ids

Product ids associated with the event. e.g. SKUs of products for AddToCart event: ['ABC123', 'XYZ789']

contents

A list of JSON object that contains the product ids associated with the event as well as additional information about the products. id, quantity, and item_price are the available fields. e.g. [{'id': 'ABC123', 'quantity': 2, 'item_price': 5.99}, {'id': 'XYZ789', 'quantity': 2, 'item_price': 9.99}]

content_type

Either 'product' or 'product_group' based on the content_ids or contents being passed. If the ids being passed in content_ids or contents parameter are ids of products then the value should be 'product'. If product group ids are being passed, then the value should be 'product_group'.

num_items

Used with InitiateCheckout event. The number of items that checkout was initiated for.

search_string

Used with the Search event. The string entered by the user for the search

status

Used with the CompleteRegistration event, to show the status of the registration.

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.

See additional Pixel 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.