Using the Marketing API with the 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
- Measure conversion activity and determine which ads lead to results such as purchases
The conversion tracking pixel is no longer available for ad creation. Learn how to use the new Facebook pixel.
Get the Pixel Code
If a pixel exists for an ad account, get the code with Marketing API with an HTTP GET to //graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/adspixels. For example:
curl -X GET \
-d ‘fields=”code”‘ \
-d ‘access_token=<ACCESS_TOKEN>’ \ //graph.facebook.com/v4.0/<PIXEL_ID>/
The response contains the code parameter containing the actual code. <PIXEL_ID> is your pixel id. When you copy the code above, replace <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="//www.facebook.com/tr?id=<PIXEL_ID>&ev=PageView&noscript=1" height="1" width="1" style="display:none"/>
Replace <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 //graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/adspixels.
curl -X POST \
-F ‘name=”My WCA Pixel”‘ \
-F ‘access_token=<ACCESS_TOKEN>’ \
//graph.facebook.com/v4.0/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="//www.facebook.com/tr?id=<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"/>
Reporting Purchase with additional product information
fbq('track', 'Purchase', { content_type: 'product', contents: [ { 'id': '1234', 'quantity': 2, }, { 'id': '4642', 'quantity': 1, } ], 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="//www.facebook.com/tr?id=<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:
curl -X POST \
-F ‘account_id=null’ \
-F ‘business=null’ \
-F ‘access_token=<ACCESS_TOKEN>’ \
//graph.facebook.com/v4.0/{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;
}To unshare a pixel:
use FacebookAds\Object\AdsPixel;
$pixel = new AdsPixel(<PIXEL_ID>);
// ad account id without 'act_'
$pixel->unsharePixelWithAdAccount(<BUSINESS_ID>, <ACCOUNT_ID>);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>);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;
}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>);Terms of Service
You can use Marketing API to accept and check Facebook’s Terms of Service for Custom Audiences, Moble Custom Audiences, Website Custom Audiences, and legacy Conversion Pixels. This API is currently under limited availability. Contact your Facebook Representative for access.
To check if your ad account can accept the Terms of Service via API, make a GET to: ad_account_ID/customaudiencestos
In the reponse, check the type: custom_audience and type: web_custom_audience fields. To accept the Terms of Service for an ad account make a POST request. To do this you need to be an ad account admininistrator or advertiser with ['MANAGE', 'ADVERTISE'] roles, not just an analyst. See Business Manager API, Permitted Roles. For example:
ad_account_ID/customaudiencestos?tos_id=custom_audience_tos
or:
ad_account_ID/customaudiencestos?tos_id=web_custom_audience_tos
To see if an ad account accepted the terms, make a GET to:
ad_account_id? fields=tos_accepted
In the response check to see if it contains custom_audience_tos, web_custom_audience_tos, or similar:
{ "tos_accepted": { "web_custom_audience_tos": 1, "custom_audience_tos": 1 }, "id": “act_xxxxxxxxxxxx" }
Related Resources
- Conversion Tracking and Pixel Stats – Track and optimize for conversions.
- Custom Audiences – Create Website Custom Audiences with people who visited or took specific actions on your website.
- Facebook Pixel, Standard and Custom Events – Default events tracked by the pixel, and custom events you can add.