Using Marketing API with Facebook Pixel

The Facebook Pixel is the main tool you can use to track events on a website. You can then use data from the pixel with Marketing API to:

  • Build custom audiences based on activity on your website, and
  • Measure conversion activity and determine which ads lead to results such as purchases

This is a guide on Facebook Pixel with Marketing API. If you are a web developer or web master, 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 with an HTTP GET to https://graph.facebook.com/{API_VERSION}/act_{AD_ACCOUNT_ID}/adspixels. For 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.10/<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.

name description type

code

Pixel code

string


Image Only Pixel Code

You should use the JavaScript code for Facebook Pixel. In some cases, you may 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>&amp;ev=PageView&amp;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 via API if you develop ads management software and enable people to create their own Facebook pixels in your. To create a pixel, HTTP POST to https://graph.facebook.com/{API_VERSION}/act_{AD_ACCOUNT_ID}/adspixels.

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.10/act_<AD_ACCOUNT_ID>/adspixels

The response has the pixel ID:

{
  "id": "11111"
}

Use these fields:

name description type

name

Name of your pixel

string

To install your pixel, see Facebook Pixel, Using the Pixel. 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 people on Facebook. See Advanced Matching.

Reporting Events

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>&amp;ev=ViewContent&amp;cd[content_name]=ABC%20Leather%20Sandal&amp;cd[content_category]=Shoes&amp;cd[content_type]=product&amp;cd[content_ids]=1234&amp;cd[value]=0.50&amp;cd[currency]=USD&amp;noscript=1" height="1" width="1" style="display:none"/>

Reporting Purchase with additional product information

fbq('track', 'Purchase', { 
    content_type: 'product',
    contents: [
      {
        'id': '1234',
        'quantity': 2,
        'item_price': 10.00
      },
      {
        'id': '4642',
        'quantity': 1,
        'item_price': 5.00
      }
    ],
    value: 25.00,
    currency: 'USD'
});

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 from a specific pixel. The trackSingleCustom method does not validate custom data.

<script>
function onClick() {
    fbq('trackSingleCustom', '<PIXEL_ID>', 'PageView');
};
</script>

Report a custom event via img pixel

<img src="https://www.facebook.com/tr?id=<FB_PIXEL_ID>&amp;ev=CustomEventName&amp;cd[custom_param1]=ABC&amp;cd[custom_param2]=123&amp;cd[value]=10.00&amp;cd[currency]=USD&amp;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.10/<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.10/<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.10/<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.10/<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('<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.10/<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.10/<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.10/<PIXEL_ID>/shared_agencies

Related Resources