Facebook Conversions API

What, why, and how

The Facebook Conversions API integration offers the possibility to send important events, such as purchases, and leads to Facebook, which allows better optimisation 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, and 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.

📘

Want to know more?

Read Facebook Conversions API explainer article on our blog.

Using the Facebook Conversions API integration

Creation

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

When placing the action node, we recommend using the action node with the name Send Event to Facebook Conversions API, because it offers the greatest flexibility in terms of configuration options.

Send Other Event to Facebook Conversions API
Any other event that you need to track.

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

Access Token

  • Security key that prevents non-authorised entities to track events into your pixels on Facebook. Needs to be generated in Facebook Events Manager for each pixel.
  • E.g. GiZCiKJSOAwjU2z6ALlpqb7Xj9Mbz2tNVOOZSSH436YJfReMh5eB

Facebook Event Name

  • Standard Facebook events are predefined visitor actions that correspond 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 can be accepted by Facebook.
  • 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 in case the Action Source is set to website, parameters Event Source URL and Client User Agent are required too.
  • 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 to 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 personalisation to retrieve 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 personalisation 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 personalisation 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
  • E.g. TEST1234567

The process of identifying a Facebook user as your customer is done 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 important that Facebook is able to 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 carefully balance the scope of the data provided. The rule of thumb is the more data about the customer is provided, the higher the chance that Facebook will be able to match the customer to the Facebook 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 in the collection, storage, and opt-out requirements under data protection regulations:

Requirement

Consent Management solution

Collect explicit consent before users are tracked by non-essential cookies or tracker (e.g cross tracking between Facebook and other sites)

Allow users to opt in to sharing their personal data with a third party (like Facebook) on our Consents page.

Store a record of consent

The date, message a user saw and their consent status (accept/reject) is stored in Exponea.

Give users the ability to opt out of sharing their data (e.g with third parties). This should be as easy as it was to give their consent to track initially.

Allow users to opt out of sharing their personal data with a third party (like Facebook) on our Consents page.

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

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 that 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 Exponea Tag Manager. Keep in mind, that some of the data that is tracked can be considered as PII (Personal identifiable information) and we require that 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 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 needs to be both sent from the pixel and 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 of 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.

Updated 5 months ago

Facebook Conversions API


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.


We rely on cookies

to optimize our communication and to enhance your customer experience. By clicking on the Accept and Close button, you agree to the collection of cookies. You can also adjust your preferences by clicking on Manage Preferences. For more information please see our Privacy policy.

Manage cookies
Accept & close

Cookies preferences

Accept & close
Back