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

Pixel Standard Events

Event NameEvent DescriptionParameters

AddPaymentInfo

When payment information is added in the checkout flow.

A person clicks on a save billing information button.

content_category, content_ids, contents, currency, value

None required.

AddToCart

When a product is added to the shopping cart.

A person clicks on an add to cart button.

content_ids, content_name, content_type, contents, currency, value

None required.

Required for Dynamic Ads: content_ids, content_type, and contents

AddToWishlist

When a product is added to a wishlist.

A person clicks on an add to wishlist button.

content_name, content_category, content_ids, contents, currency, value

None required.

CompleteRegistration

When a registration form is completed.

A person submits a completed subscription or signup form.

content_name, currency, status, value

None required.

Contact

When a person initiates contact with your business via telephone, SMS, email, chat, etc.

A person submits a question about a product.
None required.

CustomizeProduct

When a person customizes a product.

A person selects the color of a t-shirt.
None required.

Donate

When a person donates funds to your organization or cause.

A person adds a donation to the Humane Society to their cart.
None required.

FindLocation

When a person searches for a location of your store via a website or app, with an intention to visit the physical location.

A person wants to find a specific product in a local store.
None required.

InitiateCheckout

When a person enters the checkout flow prior to completing the checkout flow.

A person clicks on a checkout button.

content_category, content_ids, contents, currency, num_items, value

None required.

Lead

When a sign up is completed.

A person clicks on pricing.

content_category, content_name, currency, value

None required.

PageView

This is the default pixel tracking page visits.

A person lands on your website pages.
None required.

Purchase

When a purchase is made or checkout flow is completed.

A person has finished the purchase or checkout flow and lands on thank you or confirmation page.

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

Required: currency and value

Required for Dynamic Ads: content_ids, content_type, and contents

Schedule

When a person books an appointment to visit one of your locations.

A person selects a date and time for a dentist appointment.
None required.

Search

When a search is made.

A person searches for a product on your website.

content_category, content_ids, contents, currency, search_string, value

None required.

StartTrial

When a person starts a free trial of a product or service you offer.

A person selects a free week of your game.

currency, predicted_ltv, value

None required.

SubmitApplication

When a person applies for a product, service, or program you offer.

A person applies for a credit card, educational program, or job.
None required.

Subscribe

When a person applies to a start a paid subscription for a product or service you offer.

A person subscribes to your streaming service.

currency, predicted_ltv, value

None required.

ViewContent

When a key page is viewed such as a product page.

A person lands on a product details page.

content_ids, content_name, content_type, contents, currency, value

None required.

Required for Dynamic Ads: content_ids, content_type, and contents

Parameters

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

Parameter NameParameter Description

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'].

content_name

Name of the page/product.

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

contents

A list of JSON object that contains the International Article Number (EAN) when applicable, or other product or content identifier(s) associated with the event as well as quantities and prices of the products. id, quantity, and item_price are the required fields. e.g. [{'id': 'ABC123', 'quantity': 2, 'item_price': 5.99}, {'id': 'XYZ789', 'quantity': 2, 'item_price': 9.99}]. Note that item_price is the price of a single item, not cumulative price.

currency

The currency for the value specified.

num_items

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

predicted_ltv

Predicted lifetime value of a subscriber as defined by the advertiser and expressed as an exact value.

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.

value

The value of a user performing this event to the business.

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.