Facebook Pixel - Custom Tag Template

The Facebook Pixel custom tag template is an unofficial tag template for Google Tag Manager’s community template gallery.

Description

This template implements the Facebook Pixel on the website. You can use it to load the SDK, initiate the pixel(s), and to send custom and standard events to Facebook with any custom properties and user attributes you wish. The template should be equipped to handle all the functionality of the pixel. Please let me know in the comments if there are features that you think are missing!

Instructions

Here are the features of the pixel, together with some detail on how they work.

In general, when the tag fires, it goes through all the Pixel IDs added to the tag. For each one, it first checks if the pixel has been initialized for the ID. If it hasn’t, it proceeds to initialize it (along with any parameters that can be set with the initialization call). Then, the tag proceeds to do whatever you’ve configured it to do. It will send an event with any properties you have configured, and you can also use the tag to disable things like automatic history event tracking.

NOTE! The pixel DOES NOT automatically send the PageView tracking hit similar to how the Facebook Pixel snippet does. You will need to create a PageView tag to send the page view to Facebook.

Facebook Pixel ID(s)

The first field requires you to add your Facebook Pixel ID. You can add more than one ID by separating each with a comma, e.g. 123456789,234567890.

If you add more than one ID, then the tag will initialize (if necessary) and send the hit to all the pixel IDs listed in the field.

Enhanced Ecommerce dataLayer integration

If you check this button, then the tag will look in dataLayer for the most recent object with the ecommerce key. If this object has one of the following properties: detail, add, checkout, or purchase, the tag will automatically derive the following information from the object to be sent with the tag.

If the dataLayer does not have an ecommerce object, or if the ecommerce object doesn’t have one of detail, add, checkout, purchase, or if the ecommerce object doesn’t have a products array, the tag will end with a failure.

Event Name is mapped like this:

• An ecommerce.detail object sets event name as ViewContent.

• An ecommerce.add object sets event name as AddToCart.

• An ecommerce.checkout object sets event name as InitiateCheckout.

• An ecommerce.purchase object sets event name as Purchase.

Object Properties are mapped like this:

• A contents parameter is created from the products array, and it is populated with the id and quantity of each product in the latter.

• content_type is set to product.

• currency is derived from ecommerce.currencyCode, or set to USD by default.

• num_items is used in InitiateCheckout and Purchase and is aggregated from the total quantity of all products in the products array.

• value is calculated by multiplying the price and quantity of each product in the products array, and summing everything up.

Here’s an example of how an Enhanced Ecommerce object gets mapped into Facebook object properties:

{
  ecommerce: {
    currencyCode: 'EUR',
    checkout: {
      actionField: {
        step: 1
      },
      products: [{
        id: 'firstProduct',
        name: 'firstProductName',
        price: '3.15',
        quantity: 2,
        category: 'prods'
      },{
        id: 'secondProduct',
        name: 'secondProductName',
        price: '7.35',
        quantity: 3,
        category: 'prods'
      }]
    }
  }
}

// BECOMES

{
  content_type: 'product',
  currency: 'EUR',
  num_items: 5,
  contents: [{"id":"firstProduct","quantity":2},{"id":"secondProduct","quantity":3}],
  value: 28.35
}

NOTE! You can use the Object Properties settings (see below) to override these individual properties, if you are unhappy with how some parts of the automatic integration work.

Event Name

If you haven’t selected the Enhanced Ecommerce integration, you can choose an event name from the list of standard events. You can also specify a custom event name, or you can use a Google Tag Manager variable to provide the event name dynamically.

Consent Granted (GDPR)

If this field gets the value false (most commonly through a Google Tag Manager variable), the pixel will download the SDK, but it will not initialize nor send any hits to Facebook.

Enable Advanced Matching

If you check this box, then a new group called Customer Information Data Parameters appears.

Data Processing Options

You can add supported data processing options to this field. They are evaluated on a tag-by-tag basis, and are set for all pixel IDs of any given tag.

Customer Information Data Parameters

You can use this to set pre-defined parameters for Facebook’s Advanced Matching feature.

Object Properties

You have three options for adding object properties to the hit.

If you checked the Enhanced Ecommerce integration, some properties will be automatically populated.

You can also load a properties object using a Google Tag Manager variable that returns an object with key-value pairs that will then be added to the hit.

Finally, you can add properties manually using the table in the tag. Each row represents one property.

You can add pre-defined properties and custom properties. Read this for more information.

NOTE! If you define properties using multiple sources (e.g. Enhanced Ecommerce integration AND variable AND the table), then conflicts are resolved in the order of table > variable > Enhanced Ecommerce. In other words, if you set content_type in the table, it will override content_type set in a variable or the Enhanced Ecommerce integration.

More Settings

You can check the Disable Automatic Configuration to prevent the pixel from automatically listening to clicks or collecting page metadata.

You can check the Disable History Event Tracking to prevent the pixel from automatically tracking pushState and replaceState history events.

You can add an Event ID to deduplicate hits sent from the website and via server-side tracking.

Release notes