Marketing API Version

Pixel Events in Buttons and Advanced Scenarios

GDPR Update

The General Data Protection Regulation (GDPR) takes effect on May 25, 2018, and creates consistent data protection rules across Europe. It applies to companies (regardless of where they are based) who process personal data about individuals in the EU.

While many of the principles build on current EU data protection rules, the GDPR has a wider scope, more prescriptive standards and substantial fines. For example, it requires a higher standard of consent for using some types of data and broadens individuals' rights with respect to accessing and porting their data.

Businesses who advertise with the Facebook companies can continue to use Facebook platforms and solutions in the same way they do today. Each company is responsible for ensuring their own compliance with the GDPR, just as they are responsible for compliance with the laws that apply to them today.

Set Up Cookie Consent

As of May 25, 2018, businesses may want to implement code that creates a banner and requires affirmative consent (for example, an “I agree” checkbox at the top of the page) to use the pixel. If you already have a system in place that addresses this need, such as a tag manager, you can make this code optional.

Use the following API to pause sending pixel fires to Facebook, and once cookie consent is granted, send pixel fires to Facebook. You need to call revoke on every page.

fbq('consent', 'revoke');
fbq('consent', 'grant');

For example:

// Revoke consent before 'init' is called
fbq('consent', 'revoke');
fbq('init', '<your pixel ID>');
fbq('track', 'PageView');
// Once affirmative consent has been granted
fbq('consent', 'grant');

For more information, see our Cookie Consent Guide.

What data does the Facebook pixel collect?

See our Cookie Policy for details about the cookies used and the data received. The Facebook pixel receives these types of data:

  • Http Headers – Anything present in HTTP headers. HTTP Headers are a standard web protocol sent between any browser request and any server on the internet. HTTP Headers include IP addresses, information about the web browser, page location, document, referrer and person using the website.
  • Pixel-specific Data – Includes Pixel ID and the Facebook Cookie.
  • Button Click Data – Includes any buttons clicked by site visitors, the labels of those buttons and any pages visited as a result of the button clicks.
  • Optional Values – Developers and marketers can optionally choose to send additional information about the visit through Custom Data events. Example custom data events are conversion value, page type and more.
  • Form Field Names – Includes website field names like ‘email’, ‘address’, ‘quantity’ for when you purchase a product or service. We don't capture field values unless you include them as part of Advanced Matching or optional values.

Need more information?

Learn more about specific ad products and FAQs about the GDPR:

For information about how to use data from the pixel, see Standard and Custom Events.

How the Facebook Pixel Works

Typically you track conversions and events using Facebook Pixel by loading it with a page and firing Standard Events such as ViewContent or Purchase. However, you may need additional work in some cases. For example:

  • Single Page Applications where it's impractical to load the Pixel multiple times
  • Tracking clicks on buttons
  • Tracking that the user read an entire article

Facebook Pixel can work on those cases with some additional code. This page describes a few of those cases.

Facebook Pixel has three basic parts:

  1. Loading code, which downloads the actual pixel code from Facebook's servers
  2. Initialization code - Defines pixel ID and fires a PageView event using the fbq function
  3. noscript pixel - a fallback for cases when javascript is disabled

The fbq function can be used to track additional actions without the need to repeat the steps above. All examples in this page assume the default pixel code has already been loaded.

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

<!-- End Facebook Pixel Code -->

You can improve Pixel effectiveness if you track all PageView events. We do not recommend removing the initial PageView event from your website when tracking additional events.

Tracking clicks on Buttons

Suppose you have an e-commerce website and your "Add to Cart" button does not navigate to a new page. You may want to activate an event when the button is clicked.

In this example, we will activate a ViewContent standard event on page load. When someone clicks "Add to Cart" button, we will activate an AddToCart standard event.

To do this, first load Facebook Pixel code that you want to fire on page load:

<!-- Facebook Pixel Code -->
<script>
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'
 });
</script>
<!-- End Facebook Pixel Code -->

Then fire AddToCart either on a new page load or on the click of an Add To Cart button. There are multiple ways to handle clicks on buttons. Here's an example adding an eventListener to a button.

<!-- Somewhere there is a button that performs Add to Cart -->
<button id="addToCartButton">Add To Cart</button>

<!-- Add Pixel Events to the button's click handler -->
<script type="text/javascript">
  var button = document.getElementById('addToCartButton');
  button.addEventListener(
    'click', 
    function() { 
      fbq('track', 'AddToCart', {
        content_name: 'Really Fast Running Shoes', 
        content_category: 'Apparel & Accessories > Shoes',
        content_ids: ['1234'],
        content_type: 'product',
        value: 4.99,
        currency: 'USD' 
      });          
    },
    false
  );
</script>

There are many ways you can handle click events; Make sure you do always call fbq function after the click.

Triggering events based on visibility

For this example, suppose you have a blog and want to track users who read the entire content of an article. There's no action from the user other than scrolling to the end of the page.

Here's the sample HTML for a page where the pixel loads:

<!DOCTYPE html>
<html>
<head>
  <!-- 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 -->
</head>

<body>
  <h1>Scroll Page until the Lead event is fired</h1>
  <div style="height: 120vh; width: 100vw; background-color: #00f;"></div>
  <h1 id="fb-fire-pixel">Lead event will fire when this phrase enters the screen</h1>
  <div style="height: 120vh; width: 100vw; background-color: #000;"></div>
</body>
</html>

When the h1 element with id=fb-fire-pixel appears, we should fire the Lead standard event. To verify an element is visible on screen, we add the following code to the page:

// This code should be loaded together with Facebook Pixel

var executeWhenElementIsVisible = function(dom_element, callback) {

  if (!(dom_element instanceof HTMLElement)) {
    console.error('dom_element must be a valid HTMLElement');
  }

  if (typeof callback !== 'function') {
    console.error(
      'Second parameter must be a function, got',
      typeof callback,
      'instead',
    );
  }

  function isOnViewport(elem) {
    var rect = elem.getBoundingClientRect();
    var docElem = document.documentElement;
    return (
      rect.top >= 0 &&
      rect.left >= 0 &&
      rect.bottom <= (window.innerHeight || docElem.clientHeight) &&
      rect.right <= (window.innerWidth || docElem.clientWidth)
    );
  }

  var executeCallback = (function() {
    var wasExecuted = false;
    return function() {
      if (!wasExecuted && isOnViewport(dom_element)) {
        wasExecuted = true;
        callback();
      }
    };
  })();

  window.addEventListener('scroll', executeCallback, false);
};

After that, we need to define how to fire the pixel when the element is visible on screen:

// Get the element that should be visible to trigger the pixel fire
var element = document.getElementById('fb-fire-pixel');

// Then, set the event to be tracked when element is visible
// Note that second parameter is a function, not a function call
executeWhenElementIsVisible(element, function() {
  fbq('track', 'Lead');
});

Triggering events based on page length or percentage

For this example, suppose you want to track users who read up to a length or percentage of the page. There's no action from the user other than scrolling to the desired page length or percentage.

This first example is to track the length of the page which the user has read. In the example, we are firing off the lead pixel when user has read up to 500px length of the page.

var executeWhenReachedPageLength = function(length, callback) {
  if (typeof length !== 'number') {
    console.error(
      'First parameter must be a number, got',
      typeof length,
      'instead',
    );
  }

  if (typeof callback !== 'function') {
    console.error(
      'Second parameter must be a function, got',
      typeof callback,
      'instead',
    );
  }

  function getWindowLength() {
    return window.innerHeight || 
      (document.documentElement || document.body).clientHeight;
  }

  function getCurrentScrolledLengthPosition() {
   return window.pageYOffset || 
     (document.documentElement || document.body.parentNode || document.body).scrollTop;
  }

  var executeCallback = (function() {
    var wasExecuted = false;
    return function() {
      if (!wasExecuted && getCurrentScrolledLengthPosition() > length) {
        wasExecuted = true;
        callback();
      }
    };
  })();

  if (getWindowLength() >= length) {
    callback();
  } else {
    window.addEventListener('scroll', executeCallback, false);
  }
};

executeWhenReachedPageLength(10, function() {
  fbq('track', 'Lead');
});

This second example is to track the percentage of the page which the user has read. In the example, we are firing off the lead pixel when user has read 75% of the page.

var executeWhenReachedPagePercentage = function(percentage, callback) {
  if (typeof percentage !== 'number') {
    console.error(
      'First parameter must be a number, got',
      typeof percentage,
      'instead',
    );
  }

  if (typeof callback !== 'function') {
    console.error(
      'Second parameter must be a function, got',
      typeof callback,
      'instead',
    );
  }

  function getDocumentLength() {
    var D = document;
    return Math.max(
        D.body.scrollHeight, D.documentElement.scrollHeight,
        D.body.offsetHeight, D.documentElement.offsetHeight,
        D.body.clientHeight, D.documentElement.clientHeight
    )
  }

  function getWindowLength() {
    return window.innerHeight || 
      (document.documentElement || document.body).clientHeight;
  }

  function getScrollableLength() {
    if (getDocumentLength() > getWindowLength()) {
      return getDocumentLength() - getWindowLength();
    } else {
      return 0;
    }
  }

  var scrollableLength = getScrollableLength();

  window.addEventListener("resize", function(){
    scrollableLength = getScrollableLength();
  }, false)

  function getCurrentScrolledLengthPosition() {
   return window.pageYOffset || 
     (document.documentElement || document.body.parentNode || document.body).scrollTop;
  }

  function getPercentageScrolled() {
    if (scrollableLength == 0) {
      return 100;
    } else {
      return getCurrentScrolledLengthPosition() / scrollableLength * 100;
    }
  }

  var executeCallback = (function() {
    var wasExecuted = false;
    return function() {
      if (!wasExecuted && getPercentageScrolled() > percentage) {
        wasExecuted = true;
        callback();
      }
    };
  })();

  if (getDocumentLength() == 0 ||
    (getWindowLength()/getDocumentLength() * 100 >= percentage)) {
    callback();
  } else {
    window.addEventListener('scroll', executeCallback, false);
  }
};

executeWhenReachedPagePercentage(75, function() {
  fbq('track', 'Lead');
});

Delayed Pixel Fires

Suppose you want to track users who interact with your website a few seconds before firing a pixel event. You can do this with the setTimeout function.

// Delay pixel fire by 3 seconds
var seconds = 3;
setTimeout(function() {
  fbq('track', 'Lead');
}, seconds * 1000);

It could be used to track “engaged” visits to a page, where people are not bouncing too fast and are actually reading the content.

Triggering events based on articles viewed per session

If you want to know who viewed a certain number of articles from your site, you can have a session counter and load Facebook pixel code when this occurs.

We know that a session is a group of user interactions with your website that can take place within a given time frame per site request. You can increase the number of page views as long as you detect user activities give a time frame.

Assume you have the variable sessionCountViews per site_request, you can add the Facebook pixel code based on the number of page views you counted.

Example counting only for the 6th article viewed

if (site_request.sessionCountViews == 6) {
  fbq('track', "ViewContent", {
    sessionCountViews: site_request.sessionCountViews,
  });
}

Selective event tracking with multiple pixels

If you have multiple pixels on the same page and would like to selectively fire events on each unique pixel, the trackSingle and trackSingleCustom capabilities should be used.

Using the track function on pages that have multiple pixels initialized (either using multiple base codes or even combining it within one base code) could produce over-firing or unexpected behaviour and should be applied only in specific situations.

Example where we fire a PageView event on both initialized pixels and selectively fire a Standard event (Purchase) on one pixel and a Custom Event on a second pixel.

fbq('init', '<PIXEL_A>');
fbq('init', '<PIXEL_B>');
fbq('track', 'PageView'); //fire PageView for both initialized pixels

// only fire the Purchase event for Pixel A
fbq('trackSingle', '<PIXEL_A>', 'Purchase', {
      value: 4,
      currency: 'GBP',
});

// only fire the custom event Step4 for Pixel B
fbq('trackSingleCustom', '<PIXEL_B>', 'Step4',{
  //optional parameters
});