Facebook Conversions API

Why use this integration?

The Facebook Conversions API integration offers the possibility to send important events, such as purchases and leads to Facebook, which allows better optimization of Facebook Ads campaigns.

Our Facebook Conversions API integration directly responds to the decreased reliability of Facebook Pixel due to browser tracking preventions, ad blockers, and more. It offers more control over what data is being sent over to Facebook. The API allows you to send events to Facebook’s Ads platform directly without having to rely on browser pixel events and enables you to effectively capture offline and deep-funnel events.

Contrasting to the often unnecessarily excessive collection of data by Facebook Pixel, our Consent management framework paired with the FB CAPI allows you to directly control the scope of the data sent, using customer consents.

📘

Integrate Facebook Conversions API in 1 hour!

Read the Facebook Conversions API explainer article and jump to see how our client integrated Facebook Conversions API in 1 hour.

📘

Tips & Tricks

Refer to our documentation to learn more about:

• Why you should run ads with Bloomreach Engagement
• How you can combine Ad Audiences with AI Predictions
• Relevant Use Cases for your business
• Best Practices for Ad Audience Management

Using the Facebook Conversions API integration

Facebook Conversion events are sent using Scenarios. To do so, connect an on-event trigger (e.g., on event purchase) with the Send Event to Facebook Conversions API action node, which you can find in the ‘Actions > Other‘ toolbar. You should get a result that is similar to the picture shown below.

The webhook template Send Event to Facebook Conversions API can be used for all standard events that can be accepted by Facebook, for example, purchase event (also includes total price and currency) or any other event such as adding to a cart (cart_update), completing of registration, or searching for a product and provide valuable data which can then be used inside the Facebook Platform.

Configuration

When configuring the action node, you need to specify the following in the parameters:

Pixel ID

• Unique identification of the Facebook pixel, which needs to be copied from pixel settings available in the Facebook Events Manager.
  *, E.g. 1234567890123456

Authorization Token

• Security key that prevents non-authorized entities from tracking events into your pixels on Facebook. It needs to be generated in Facebook Events Manager for each pixel.
• E.g. GiZCiKJSOAwjU2z6ALlpqb7Xj9Mbz2tNVOOZSSH436YJfReMh5eB

Facebook Event Name

• Standard Facebook events are predefined visitor actions corresponding to common, conversion-related activities, such as searching for a product, viewing a product, or purchasing a product.
• See a list of all standard events that Facebook can accept.
• E.g. Purchase or AddToCart

Action Source

• This field allows you to specify where your events occurred. Knowing where your events took place helps ensure your ads go to the right people.
• This is a required parameter. Please note that if the Action Source is set to website, parameters Event Source URL and Client User Agent are also required.
• You may send events where the action_source has potential values of “app” or “physical_store.” However, Conversions API does not currently support the optimization of non-website data like app or offline events.
  *, E.g. website or app

Event Source URL

• The browser URL where the event happened. Enter a static value or use Jinja personalization to retrieve the full URL from events.
• This is a required parameter if Action Source is set to website.
• See the tracking section below for more examples on how to track this information
• E.g. https://demo.exponea.com/cart

Client User Agent

• The user agent string for the browser corresponding to the event.
• Use Jinja personalization to include user agent string from a customer attribute (you need to implement the tracking of user agent string separately).
• See the tracking section below for more examples on how to track this information
• This is a required parameter if Action Source is set to website.
• E.g. Chrome/86.0.4240.111, or Windows NT 10.0; Win64; x64

Client IP Address

• The IP address of the browser corresponding to the event.
• Use Jinja personalization to create the aggregate separately.
• See the tracking section below for more examples on how to track this information
• This is a required parameter in case the only other identification parameter used is Client User Agent
• E.g. 10.20.30.40

Test Event Code

• Code used to verify that your server events are received correctly by Facebook. Use this code to test your server events in the Test Events feature in Events Manager.
• This is an optional parameter that is usually used only during testing. It should be removed for production usage so that Facebook will not consider it a testing event.
• E.g. TEST1234567

The process of identifying a Facebook user as your customer is based on the identification parameters provided as part of the webhook’s payload that you can view and configure in the Editor tab. For the best results, it is essential that Facebook can do so.

By default, the action nodes are set up to include the following customer information parameters:

Facebook Click ID (FBC)

• Provided as a query parameter within the URL, if the customer clicked on an ad on Facebook; tracked using a JavaScript tag.
• See the tracking section below for more examples on how to track this information
• E.g., fb.1.1602686895.IwAR3xruhRZhD77zSpA669v9xdo3I0VHHoz2gXwvpE8uWPb8qN5Eq2TfgGr6s

Facebook Browser ID (FBP)

• Read from FBP first cookie, which is set by the FB Pixel, if it is placed on the website
• See the tracking section below for more examples on how to track this information
• E.g., fb.1.1603122906825.1012802381

Customer's First Name

• Read from customer attribute first_name
• E.g., John

Customer's Last Name

• Read from customer attribute last_name
• E.g., Smith

Customer's City

• Read from customer attribute city
• E.g., Austin

Customer's Country

• Read from customer attribute country
• E.g., US

Customer's Phone Number

• Read from customer attribute phone
• A phone number. Include only digits with country code, area code, and number.
• E.g., 16505551212

Customer's Email

• Read from customer attribute email
• An email address, in lowercase.
• E.g., [email protected]

After sending the event to Facebook, you will be able to see the matching quality along with personalized recommendations on how to increase it in Facebook’s Event Manager. When the matching quality is lower, Facebook might recommend that you also provide additional customer information parameters. You can find the list of all possible customer information parameters in Facebook’s documentation.

📘

Data scope

You will need to balance the scope of the data provided carefully. The rule of thumb is that the more data about the customer is provided, the higher the chance that Facebook will be able to match the customer to the user. However, the scope of the data provided to Facebook should be minimized, and it needs to follow the customer’s consent preferences.

Although our standard action node templates already include the hashing by default, keep in mind that customer information parameters that include Personal Identifiable Information (PII), need to be hashed using the sha256 algorithm before sending to Facebook Conversions API. Furthermore, remember you can only send PII to Facebook if the customer has given the appropriate consent.

Consent management and data privacy

To stay compliant in regard to data protection, it is required to use Facebook Conversions API together with our Consent Management framework. Our framework helps you by providing an effective solution for the collection, storage, and opt-out requirements under data protection regulations:

The created consent categories can then be easily used within the Scenario to target only the customers with the relevant consent.

Use case ideas

Increasing the data quality for conversion tracking
Track conversions happening in your app or website directly using backend API without relying on browser event tracking.

Predictive data
If you want to add an AI edge to your retargeting, we recommend pairing the use of Facebook Conversions API with our Predictions module. This allows you to use forward-looking data generated by an advanced machine learning model to discover segments with higher conversion potential or those you are about to lose. Feed this data into Facebook for more accurate and targeted ads.

Increasing email open rates
By sending a conversion event to Facebook every time the customer opens the email, you can optimize the Facebook campaign to drive more conversions, and with that, more email opens.

Tracking Customer Information Parameters

In order to increase the event match quality, you might implement additional tracking on the website using Bloomreach Engagement Tag Manager. Keep in mind that some of the tracked data can be considered as PII (Personal identifiable information), and we require that the following tags are only fired when you have collected explicit consent from the customer.

Tag for tracking the Facebook Browser ID (FBP)

var fbp = getCookieByName('_fbp'); 
exponea.update({'fbp': fbp});

function getCookieByName(cname) {
	    var name = cname + "=";
	    var decodedCookie = decodeURIComponent(document.cookie);
	    var ca = decodedCookie.split(';');
	    for(var i = 0; i <ca.length; i++) {
	        var c = ca[i];
	        while (c.charAt(0) == ' ') {
	            c = c.substring(1);
	        }
	        if (c.indexOf(name) == 0) {
	            return c.substring(name.length, c.length);
	        }
	    }
	    return "";
}

Tag for tracking the Facebook Click ID (FBC)

var fbclid = getParameterByName('fbclid', window.location.href); 
exponea.update({'fbclid': 'fb.1.' + {{ time | int }} + '.' + fbclid});

function getParameterByName(name, url) {
    if (!url) url = window.location.href;
    name = name.replace(/[\[\]]/g, '\\$&');
    var regex = new RegExp('[?&]' + name + '(=([^&#]*)|&|#|$)'),
        results = regex.exec(url);
    if (!results) return null;
    if (!results[2]) return '';
    return decodeURIComponent(results[2].replace(/\+/g, ' '));
}

Tag for tracking the Client User Agent

var user_agent = navigator.userAgent;
exponea.update({ 'user_agent': user_agent });

Aggregate for tracking the Event Source URL

For website events, it is required to provide Event Source URL parameter. If the URL is not available directly in the triggering event's attributes, you might want to use the following customer aggregate.

last page_visit location

Aggregate for tracking the Client IP Address

last session_start ip

For website events, it is required to provide the Event Source URL parameter. If the URL is not available directly in the triggering event's attributes, you might want to use the following customer aggregate.

Deduplication

The solution currently supports two ways of deduplication:

• event_id - the same ID must be sent from the pixel using API. This is especially useful for Purchase events, where an order ID or transaction ID might be used as an event_id that enables the deduplication.
• deduplication using FBP parameter - set up automatic tracking of FBP (see above), webhook presets will automatically send FBP parameter with each API request - most of the events get deduplicated using this way.

See also this Facebook article related to event deduplication.

Limitations

Currently, there are these limitations present in our solution:

• The access token is exposed in the webhook endpoint URL field
• Although Conversion API supports sending the external_id parameter to identify customers using external IDs (such as cookie or CRM IDs), our Facebook Ads retargeting does not support creating audiences based on External ID.