Meta Conversions API Integration

Overview

Ensighten has developed a Conversions API (CAPI) solution in line with Meta’s recommendation to deploy the Conversions API tags server-side to achieve greater accuracy with conversion tracking and targeting. This guide will serve as a step-by-step implementation guide on how to deploy both the Meta Pixel and CAPI tags using Ensighten. Meta recommends deploying both the Meta Pixel (on the client side) and the CAPI (on the server side) for maximum accuracy and tracking due to possible browser and device tracking restrictions.

Requirements

• User role with Manage and Server Tag Console permissions.
• Be familiar with Ensighten Tag Manager and SST.

Generate and Store Conversions API Access Token

Within this guide, we will assume a Meta pixel has already been created within your Business Manager and deployed via Google Tag Manager. If you have not created the Meta Pixel yet, use this to help How to set up and install a Meta Pixel.

Creating an access token for the Meta Pixel

1. Log in to Business Settings and select your business.
2. Under Data Sources on the left, click on Pixels.
   
3. Select your pixel and click Open in Events Manager at the top right.
   
4. Ensure you have the correct Pixel ID highlighted in the menu on the left, then click on Settings in the right panel.
   
5. Under the Conversions API section and set up manually subsection, click on the Generate access token link.
   
6. Copy the generated access token and save it for the next step in the implementation.
   

Storing the Access Token as an SST Secret

1. Log in to Ensighten and navigate to the Secrets section within the SST UI.
2. Click Create Secret in the top right corner of the page.
3. In the NAME field enter meta_access_token. In the VALUE field paste in the value of your access token you copied in the previous step.  Finally, click SAVE.
   

Configure Meta Pixel

Now that your Pixel has enabled the Conversions API feature and you have set up your access token, the Meta Pixel needs to be modified to enable the Conversions API tag.

Store the Facebook Click ID

1. You need to create a new Data Definition to extract the Facebook Click ID to pass to the Conversion. Visit the Data page and click ADD DATA DEFINITION.
2. Enter the name Facebook - Formatted Click ID as the Data Definition name, choose Custom from the data element type list, and create a new collection called Tag-Specific.

3. In the GET THE DATA FROM selection, select Custom and use this function:

   function() {
       const storage_key = '_fbc';
       const fbclid = new URLSearchParams(window.location.search).get('fbclid');
       if (fbclid) {
           const timestamp = new Date().getTime();
           const subdomain_index = (() => {
               const domain_split_reverse = window.location.hostname.split('.').reverse();
               const cookie_name = `__cheq_tld_${timestamp}`;
               const is_secure = window.location.protocol === 'https:';
               const secure_flag = is_secure ? ';Secure' : '';
               const test_cookie = (domain) => {
                   document.cookie = `${cookie_name}=1;path=/;domain=${domain};SameSite=Lax${secure_flag}`;
                   const exists = document.cookie.split(/;\s*/).some(c => c.startsWith(cookie_name + '='));
                   document.cookie = `${cookie_name}=;expires=${new Date(0).toUTCString()};Max-Age=0;path=/;domain=${domain};SameSite=Lax${secure_flag}`;
                   return exists;
               };
   
               for (let i = 1; i <= domain_split_reverse.length; i++) {
                   const current_cookie_domain = domain_split_reverse.slice(0, i).reverse().join('.');
                   if (test_cookie(current_cookie_domain)) return i - 1;
               }
           })();
           const response = ['fb', subdomain_index, String(timestamp), fbclid].join('.');
           Bootstrapper.Cookies.set(storage_key, response);
           window.localStorage.setItem(storage_key, response);
           return response;
       }
       return Bootstrapper.Cookies.get(storage_key) || window.localStorage.getItem(storage_key);
   }

   1. You will need the Cookies Frameworks if you don’t already have these enabled. If you don’t have them enabled, be sure to create a tag using the Ensighten Frameworks app, ensure Cookies is toggled on, and use the All Pages - Blocking (Synchronous) Condition.
4. Click Continue and select your Spaces or simply check the Global checkbox if you want this Data Definition available across all your Spaces.
5. Click Continue, ensure All Pages - Non-blocking (Asynchronous) is your selected Condition, and click Save.

Configure Meta Pixel

1. Now that you have a Data Definition to retrieve the Facebook Click ID, edit your existing Meta Pixel tag(s), if they exist, or create a new one by visiting the Manage Apps page, search for Meta Pixel, and click Configure or navigate directly to the app.
2. Edit your existing Meta pixel tags (if they exist) or create a new one by visiting the Manage Apps page, search for Meta Pixel.
3. Click Configure.
4. Within the configuration page, expand the Conversions API panel toggle on Enable SST Conversions API Integration.
5. In the Facebook Click ID (Formatted) field, select Data Definition from the right drop-down menu and select Facebook - Formatted Click ID as the value.
6. If this is a new pixel tag, choose your necessary Conditions or Events that should execute this pixel.
7. Click the Save & Commit button at the bottom of the page and then publish the tag change.

Meta highly recommends sending user data (where possible) such as the user’s email address and/or phone number to improve the event match quality. These options are available in the “User Data” panel shown in the screenshot below.

Configure Server-Side Tagging library

Next, we need to configure the Server-Side Tagging (SST) Library. You will only need one instance of the SST library for all your SST tags, so if you’ve already configured the tag, you can skip this step.

1. Visit the Manage Apps page, search for Server-Side Tagging (SST), and click Configure (or simply, click here).
2. Select Core Library as the tag type.
3. Enter a tag name, like SST - Library.
4. Enter your SST first-party domain and any additional fields if necessary, such as your data layer.
5. Click Continue and select the Space(s) for your website (client-side, not server-side) and ensure the Condition is set to All Pages - Non-blocking (Asynchronous).
6. Click Save & Commit.
7. Publish the space.

Configure Meta Conversions API

Visit the Manage Apps page, Apps Library, search for Conversions API, and click Configure when hovering over the Meta Conversions API, or you can navigate directly to the App Meta (Facebook) Conversions API.

1. Enter a tag name, like Meta Conversions API.
2. Select your Access Token SST Secret in the Access Token field.
3. Make sure the Enable Conversions API Integration toggled is enabled.
   
4. Click Continue and select a Server-Side Tagging Space, typically having SST in the name.
5. Choose the Condition All Pages - Non-blocking (Asynchronous).
6. Click Save & Commit.
7. Publish the space.

The more information you send to the Conversation API, the better the match rate will be.

For more information on fields, visit Conversions API.

Testing and Validation

Validate Meta Pixel and SST beacon

1. First, visit the Server Tag Console and make sure Event Collection is toggle_on on.
2. Next, install the Meta Pixel Helper extension for your Edge or Chrome browser.
3. Visit the webpage(s) where your Meta Pixel(s) execute, open your Developer Tools’ Network panel, filter requests by sst, and refresh the page.
4. Click on the Meta Pixel Helper icon which should have a green badge with the number of Meta events that executed successfully.
5. Validate the expected values are passed correctly.
   
6. Now that the Meta Pixel is validated, look at the entry beginning with sst and look at the Payload tab. Expand the events array and ensure there is an entry with the name "facebook_conversions_api_integration" like what is shown below.
   
7. After validating both the Meta Pixel and SST beacon are executing properly click on the Headers tab for the SST request, expand Response Headers, and copy the value for the xens- event-id header to use in the next steps.
   

Validate Facebook Conversions API request

1. Visit your Server Tag Console, select the filter icon, choose Event ID, and then paste your x-ens-event-id value copied from the Meta Pixel and SST beacon steps and click enter.
   
2. Click on the visibility icon to inspect your event.
   
3. Find the POST request to graph.facebook.com, validate the request was sent successfully, usually shown with a 200 status code. Check that the data sent is correct in the Request Payload section.
   

Validate Facebook Events Manager

1. Visit and log in to Meta Business. 
2. Upon login, visit the Events Manager.
3. Choose your Meta Pixel in the right-hand panel.
4. Your Meta Pixel events should populate in the bottom panel and the Integration column should say Browser • Conversions API notifying you that Facebook is receiving data both from the Browser, Pixel implementation on the website, and the Conversion API. You can also see your Event Match Quality based on the user data, like an email, phone, IP address, etc., that is being passed.