Pixel for Building Audiences

The Facebook Pixel is the main tool you can use to track events on a website and build audiences based on this data.

This is an advanced guide about Facebook Pixel with Marketing API. For instructions for non-technical audiences, see Getting Started with Facebook Pixel.

We deprecated the Conversion Tracking Pixel to provide the best solutions. In February 2017 the conversion tracking pixel will no longer be available for use. Start using the new Facebook pixel today - a single pixel for more powerful advertising and measurement. Learn how to transition from the conversion tracking pixel to the Facebook pixel, see Advertiser Help Center, Facebook Pixel.

Get Pixel Code

If a pixel exists for an ad account, get the code with Marketing API, by making an HTTP GET call to:

https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/adspixels

Use these fields:

namedescriptiontype

code

The pixel code

string


Example:

use FacebookAds\Object\AdsPixel;
use FacebookAds\Object\Fields\AdsPixelFields;

$pixel = new AdsPixel(<PIXEL_ID>, 'act_<AD_ACCOUNT_ID>');
$pixel->read(array(AdsPixelFields::CODE));

echo $pixel->{AdsPixelFields::CODE}.PHP_EOL;
from facebookads.adobjects.adspixel import AdsPixel
from facebookads.adobjects.adaccount import AdAccount

account = AdAccount('act_<AD_ACCOUNT_ID>')
account.get_ads_pixels(fields=[AdsPixel.Field.code])
AdsPixel adsPixel2 = new AdsPixel(<PIXEL_ID>, context).get()
  .requestCodeField()
  .execute();
curl -G \
  -d 'fields=code' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.9/<PIXEL_ID>

The response contains the code parameter containing the actual code. <FB_PIXEL_ID> is your pixel id. When you copy the code above, replace <FB_PIXEL_ID> with your own Facebook pixel id. Now you can add the pixel code to your website.

Image Only Pixel Code

You should use a the full JavaScript code for Facebook Pixel for the best experience. In some cases, you could use an HTML or an image pixel then add another 3rd-party tag from your website. The image pixel looks like this:

<img src="https://www.facebook.com/tr?id=<FB_PIXEL_ID>&ev=PageView&noscript=1" height="1" width="1" style="display:none"/>

Replace <FB_PIXEL_ID> with your Facebook pixel ID.

Create Pixels

You can share pixels between businesses and ad accounts, so you ususally need only one. You can also use an existing pixel rather than creating a new one.

You only need to create new pixels for your own ads management software and want people to create their own Facebook pixels in your tool. To create a pixel, HTTP POST to:

https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/adspixels

Use these fields:

namedescriptiontype

name

The name of your pixel

string

Example:

use FacebookAds\Object\AdsPixel;
use FacebookAds\Object\Fields\AdsPixelFields;

$pixel = new AdsPixel(null, 'act_<AD_ACCOUNT_ID>');
$pixel->{AdsPixelFields::NAME} = 'My WCA Pixel';
$pixel->create();
from facebookads.adobjects.adspixel import AdsPixel

pixel = AdsPixel(parent_id='act_<AD_ACCOUNT_ID>')
pixel[AdsPixel.Field.name] = 'My new Pixel'

pixel.remote_create()
curl \
  -F 'name=My WCA Pixel' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.9/act_<AD_ACCOUNT_ID>/adspixels

The response has the pixel ID:

{
  "id": "11111"
}

Installing Pixels

  1. Paste pixel code on each web page immediately before the closing </head> tag in your HTML. If your site has a global include file, such as header.php, place the code there. Placing it in the <head> tag isn't necessary, but it helps capture more conversions and create bigger website custom audiences.
  2. Place one of the 9 standard events on select pages of your website with standard parameters. For example, when someone buys something, call the Purchase event on the purchase confirmation page only with information about the order passed back in the standard parameters such as value and currency.
  3. After you confirm the pixel and standard events work, remove existing Conversion Tracking pixels and Custom Audience pixels from your website.

Add Advanced Matching

You can send additional customer data through the pixel and match more website actions with Facebook users. See Advanced Matching.

Standard Events

These are optional events you can add to your Facebook pixel base code. With them you can better understand the audience visiting your website and reach specific sets of your users who have visited your website as well as track and optimize for conversions.

You should implement standard events only be implemented on specific pages of your website. For example, add Purchase only on pages where a purchases are made, such as confirmation pages for shopping carts.

Standard events require Facebook pixel code is loaded on a page before they are called.

Below are standard events and their required parameters. These are recommended for advertisers creating Custom Audiences from their website and required for advertisers for track conversions:

Event NameEvent DescriptionParametersRequired Parameters

ViewContent

When a page viewed such as landing on a product detail page

value, currency, content_name, content_type, content_ids

None. For Dynamic Product Ads content_ids and content_type required.

Search

When a search is made, such as a product query

value, currency, content_category, content_ids, search_string

None

AddToCart

When some adds a product to a shopping cart

value, currency, content_name, content_type, content_ids

None. For Dynamic Product Ads content_ids and content_type required.

AddToWishlist

When a product is added to a wishlist

value, currency, content_name, content_category, content_ids

None

InitiateCheckout

When someone starts a checkout flow but does not complete it yet

value, currency, content_name, content_category, content_ids, num_items

None

AddPaymentInfo

Payment information is added during checkout

value, currency, content_category, content_ids

None

Purchase

When a purchase is made or checkout flow is completed

value, currency, content_name, content_type, content_ids, num_items

value, currency. For Dynamic Product Ads content_ids and content_type required.

Lead

When a sign up is completed, such as signup for trial

value, currency, content_name, content_category

None

CompleteRegistration

When a registration form is completed, such as signup for a service

value, currency, content_name, status

None

Parameters

You should send value and currency parameters for each event to calculate cost per action, and Return On Ad Spend (ROAS). value is the value of a user performing this event not the value of the product. This helps you optimize for people reaching this event. If you know a conversion is worth $10 on average and that 10% of people who reach page “ABC” convert, you could place a value of $1 on people reaching the “ABC” page.

All recommended parameters to pass with Standard events:

Parameter NameParameter Description

value

value of someone performing this event to the business

currency

currency for the value specified.

content_name

Name of page or product

content_category

Category for page or product

content_ids

Product ids associated with the event, such as SKUs of products in AddToCart event: ['ABC123', 'XYZ789']

content_type

Either product or product_group based on the content_ids passed. If the ids in content_ids are product ids then the value should be product. If product group ids then the value should be product_group.

num_items

Use with InitiateCheckout event. The number of items in checkout.

search_string

Use with Search event. The string entered for the search

status

Use with CompleteRegistration event, to show registration status.

Custom Events

Facebook pixel supports custom events to create your website Custom Audiences or custom conversions.

Event NameEvent DescriptionRequired Parameters

CustomEvent

Any custom event you want to report. Length of the custom event name must be less than 50 characters

None

Reporting Events, Examples

Reporting ViewContent standard event with parameters

fbq('track', 'ViewContent', { 
    content_type: 'product',
    content_ids: ['1234'],
    content_name: 'ABC Leather Sandal',
    content_category: 'Shoes'
    value: 0.50,
    currency: 'USD'
});

Reporting ViewContent with the img pixel

<img src="https://www.facebook.com/tr?id=<FB_PIXEL_ID>&ev=ViewContent&cd[content_name]=ABC%20Leather%20Sandal&cd[content_category]=Shoes&cd[content_type]=product&cd[content_ids]=1234&cd[value]=0.50&cd[currency]=USD&noscript=1" height="1" width="1" style="display:none"/>

Report a Search event

fbq('track', 'Search', { 
    search_string: 'leather sandals',
    content_category: 'Product Search',
    content_ids: ['1234', '2424', '1318', '6832'],
    value: 0.50,
    currency: 'USD'
});

Report a Lead event

fbq('track', 'Lead', {
    content_name: 'Auto Insurance',
    content_category: 'Quote',
    value: 40.00,
    currency: 'USD'
});

Report a custom event

fbq('trackCustom', '<CustomEventName>', {
    custom_param1: 'ABC',
    custom_param2: 123,
    value: 10.00,
    currency: 'USD'
});

Report a custom event via img pixel

<img src="https://www.facebook.com/tr?id=<FB_PIXEL_ID>&ev=CustomEventName&cd[custom_param1]=ABC&cd[custom_param2]=123&cd[value]=10.00&cd[currency]=USD&noscript=1" height="1" width="1" style="display:none"/>

To suppress pixel being fired via pushState or replaceState:

fbq.disablePushState = true;

Track In-Page Events

After you install the pixel track in-page actions, such as product purchases, by tying events to HTML elements such as buttons. For example:

<button onClick="fbq('track', 'Purchase');">Button Text</button>

Or you could create a function that pushes the event. The advantage is if you have multiple HTML elements, you can call a single function when someone clicks any of them; you don't have to define individual onClick element.

For example, to push the event:

<script>
function onClick() {
  fbq('track', 'Purchase');
};
</script>

You can call this function to fire Purchase events from multiple HTML elements. For example:

<button onClick="onClick()">Buy Now</button>

<button onClick="onClick()">Buy as a Gift</button>

Note: Pixel Helper may show multiple pixel events firing from the same page. The Pixel Helper expects pages to fire only on load but by tying events to elements, such as a button, you are using an alternative solution that overturns the expected behavior.

Sharing Pixel

You can share your Facebook pixel with your own ad accounts and with other businesses via Business Manager. You must be an admin of the business. To share a pixel:

use FacebookAds\Object\AdsPixel;

$pixel = new AdsPixel(<PIXEL_ID>);
//  destination ad account id without 'act_'
$pixel->sharePixelWithAdAccount(<BUSINESS_ID>, '<DESTINATION_ACCOUNT_ID>');
from facebookads.adobjects.adspixel import AdsPixel

pixel = AdsPixel(<PIXEL_ID>)

response = pixel.share_pixel_with_ad_account(
    '<BUSINESS_ID>',
    '<DESTINATION_ACCOUNT_ID>',
)
print(response.body())
curl \
  -F 'business=<BUSINESS_ID>' \
  -F 'account_id=<DESTINATION_ACCOUNT_ID>' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.9/<PIXEL_ID>/shared_accounts

To list your own ad accounts your pixel is shared with:

use FacebookAds\Object\AdsPixel;

$pixel = new AdsPixel(<PIXEL_ID>, $ad_account_id);

$shared_accounts = $pixel->getSharedAccounts(
  array(),
  array(
    'business' => '<BUSINESS_ID>',
  ));
foreach ($shared_accounts as $shared_account) {
  echo $shared_account->{AdAccountFields::ID}.PHP_EOL;
}
from facebookads.adobjects.adspixel import AdsPixel
from facebookads.adobjects.adaccount import AdAccount

pixel = AdsPixel(<PIXEL_ID>)
shared_accounts = pixel.get_ad_accounts('<BUSINESS_ID>')
for shared_account in shared_accounts:
    print(shared_account[AdAccount.Field.id])
APINodeList<AdAccount> adAccounts = new AdsPixel(<PIXEL_ID>, context).getSharedAccounts()
  .setBusiness(<BUSINESS_ID>)
  .execute();
curl -G \
  -d 'business=<BUSINESS_ID>' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.9/<PIXEL_ID>/shared_accounts

To unshare a pixel:

use FacebookAds\Object\AdsPixel;

$pixel = new AdsPixel(<PIXEL_ID>);
// ad account id without 'act_'
$pixel->unsharePixelWithAdAccount(<BUSINESS_ID>, <ACCOUNT_ID>);
from facebookads.adobjects.adspixel import AdsPixel

pixel = AdsPixel(<PIXEL_ID>)
pixel.unshare_pixel_from_ad_account(<BUSINESS_ID>, <ACCOUNT_ID>)
curl -X DELETE \
  -d 'business=<BUSINESS_ID>' \
  -d 'account_id=<ACCOUNT_ID>' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.9/<PIXEL_ID>/shared_accounts

You can share your pixel with other businesses too. You can only share pixels created by your business. Once you share your pixel with another business, they cannot share it further. They can only assign their ad accounts to your pixel. To share a pixel with another business or agency:

use FacebookAds\Object\AdsPixel;

$pixel = new AdsPixel(<PIXEL_ID>);
$pixel->sharePixelWithAgency(<BUSINESS_ID>, <AGENCY_ID>);
from facebookads.adobjects.adspixel import AdsPixel

pixel = AdsPixel(<PIXEL_ID>)

response = pixel.share_pixel_with_agency(<BUSINESS_ID>, <AGENCY_ID>)
print(response.body())
curl \
  -F 'business=<BUSINESS_ID>' \
  -F 'agency_id=<AGENCY_ID>' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.9/<PIXEL_ID>/shared_agencies

To list ad accounts that a business assigned to your pixel:

use FacebookAds\Object\AdsPixel;

$pixel = new AdsPixel(<PIXEL_ID>, $ad_account_id);

$shared_accounts = $pixel->getSharedAccounts(
  array(),
  array(
    'business' => '<BUSINESS_ID>',
  ));
foreach ($shared_accounts as $shared_account) {
  echo $shared_account->{AdAccountFields::ID}.PHP_EOL;
}
from facebookads.adobjects.adspixel import AdsPixel
from facebookads.adobjects.adaccount import AdAccount

pixel = AdsPixel(<PIXEL_ID>)
shared_accounts = pixel.get_ad_accounts('<DESTINATION_BUSINESS_ID>')
for shared_account in shared_accounts:
    print(shared_account[AdAccount.Field.id])
APINodeList<AdAccount> adAccounts = new AdsPixel(<PIXEL_ID>, context).getSharedAccounts()
  .setBusiness(<BUSINESS_ID>)
  .execute();
curl -G \
  -d 'business=<BUSINESS_ID>' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.9/<PIXEL_ID>/shared_accounts

To list businesses that your pixel is shared with:

use FacebookAds\Object\AdsPixel;
use FacebookAds\Object\Fields\BusinessFields;

$pixel = new AdsPixel(<PIXEL_ID>, $ad_account_id);

$shared_business = $pixel->getSharedAgencies();
foreach ($shared_business as $business) {
  echo $business->{BusinessFields::ID}.PHP_EOL;
}
from facebookads.adobjects.adspixel import AdsPixel
from facebookads.adobjects.business import Business

pixel = AdsPixel(<PIXEL_ID>)
shared_business = pixel.get_agencies()
for business in shared_business:
    print(business[Business.Field.id])
APINodeList<Business> businesss = new AdsPixel(<PIXEL_ID>, context).getSharedAgencies()
  .execute();
curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.9/<PIXEL_ID>/shared_agencies

To unshare a pixel from a business, use a DELETE:

use FacebookAds\Object\AdsPixel;

$pixel = new AdsPixel(<PIXEL_ID>);
$pixel->unsharePixelWithAgency(<BUSINESS_ID>, <AGENCY_ID>);
from facebookads.adobjects.adspixel import AdsPixel

pixel = AdsPixel(<PIXEL_ID>)
fixtures.unshare_pixel_from_agency(<PIXEL_ID>, <BUSINESS_ID>, <AGENCY_ID>)
curl -X DELETE \
  -d 'business=<BUSINESS_ID>' \
  -d 'agency_id=<AGENCY_ID>' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.9/<PIXEL_ID>/shared_agencies

Related Resources