Meta's Conversions API integration

This guide shows you how to set up and configure Meta Conversions API integration with Bloomreach Engagement using scenarios and action nodes.

Before you start

You'll need:

• A Meta pixel ID from Meta Events Manager.
• An authorization token generated in Meta Events Manager.
• Access to Bloomreach Engagement scenarios.

Quick start resources

Read the Meta Conversions API overview to understand how the API works and why you'd use it.

📘

Conversions API in 60 minutes

Check out how our client integrated Meta Conversions API in 1 hour.

How to set up the integration

You send Meta conversion events using scenarios. Connect an on-event trigger (like "on event purchase") with the Send Event to Meta Conversions API action node from the Actions > Other toolbar.

The webhook template works with all standard Meta events, including:

• Purchase events (with total price and currency)
• Cart updates (cart_update)
• Registration completion
• Product searches

This data helps optimize campaigns in the Meta platform.

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.

Configuration parameters

When you configure the action node, specify these parameters.

Pixel ID

Your unique Meta pixel identification number. Copy this from pixel settings in Meta Events Manager.

Example: 1234567890123456.

Authorization token

A security key that prevents unauthorized tracking into your Meta pixels. Generate this in Meta Events Manager for each pixel.

Example: GiZCiKJSOAwjU2z6ALlpqb7Xj9Mbz2tNVOOZSSH436YJfReMh5eB

Meta event name

Standard Meta events are predefined visitor actions for common conversion activities like searching, viewing, or purchasing products.

See Meta's list of all standard events.

Examples: Purchase, AddToCart

Action source

Where your events occurred. This helps Meta show your ads to the right people. This is a required parameter.

You may send events where the action_source has potential values of app or physical_store. However, Conversions API doesn't currently support the optimization of non-website data like app or offline events.

📘

Note

If you set the action source to website, you must also include Event Source URL and Client User Agent parameters.

Example: website or app

Event source URL

The browser URL where the event happened. Use a static value or Jinja personalization to get the full URL from events.

Example: https://demo.bloomreach.com/cart

Client user agent

The browser's user agent string for the event. Use Jinja personalization to include this from a customer attribute. You'll need to track user agent strings separately. This is a required parameter if Action source is set to website.

Example: Chrome/86.0.4240.111, or Windows NT 10.0; Win64; x64

Client IP address

The browser's IP address for the event. Use Jinja personalization to create this aggregate separately. This is a required parameter in case the only other identification parameter used is Client User Agent.

Example: 10.20.30.40

Test event code

Use this code to verify that Meta receives your server events correctly through the Test Events feature in Events Manager.
This is an optional parameter that is usually used only during testing. Remove this for production use so Meta doesn't consider it a test event.

Example: TEST1234567

Customer identification parameters

Meta identifies your customers using the identification parameters in the webhook's payload (viewable in the Editor tab). For best results, Meta needs to match customers accurately.

The action nodes include these customer information parameters by default:

Click ID (FBC)

Appears as a query parameter in the URL when customers click Meta ads. Track this using a JavaScript tag.

Example: fb.1.1602686895.IwAR3xruhRZhD77zSpA669v9xdo3I0VHHoz2gXwvpE8uWPb8qN5Eq2TfgGr6s

Browser ID (FBP)

Read from the cookie that Meta Pixel sets on your website.

Example: fb.1.1603122906825.1012802381

Personal information

• First name (from customer attribute first_name)
• Last name (from customer attribute last_name)
• Email (from customer attribute email, in lowercase)
• Phone number (from customer attribute phone, digits only with country code)

Location

• City (from customer attribute city)
• Country (from customer attribute country)

After you send events to Meta, you'll see the matching quality and personalized recommendations in Meta's Events Manager. When matching quality is lower, Meta might recommend additional customer information parameters. Check Meta's documentation for all possible customer information parameters.

📘

Data scope and privacy

Balance your data scope carefully. More customer data increases Meta's chances of matching customers to users, but minimize the data you provide and follow customer consent preferences.

Our standard action node templates already include hashing by default. Remember that you can only send PII to Meta when customers give appropriate consent.

Consent management and data privacy

You must use the Conversions API with our consent management framework to stay compliant with data protection regulations. Our framework provides effective solutions for collection, storage, and opt-out requirements:

Use the created consent categories in scenarios to target only customers with relevant consent.

Use cases

• Improve conversion tracking data quality: Track conversions happening in your app or website directly using backend API without relying on browser event tracking.
• Use predictive data: Add an AI edge to your retargeting by pairing the Conversions API with our predictions module. Use forward-looking data from advanced machine learning models to find segments with higher conversion potential or those you're about to lose. Feed this data into Meta for more accurate, targeted ads.
• Increase email open rates: Send a conversion event to Meta every time customers open emails. This optimizes Meta campaigns to drive more conversions and email opens.
• Track customer information parameters: You might implement additional website tracking using Bloomreach Engagement Tag Manager to increase event match quality. Some tracked data counts as PII (Personal identifiable information), so only fire these tags when you have explicit customer consent.

JavaScript tracking tags

Track 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 "";
}

Track 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, ' '));
}

Track client user agent

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

Customer aggregates

For website events, you must provide the event source URL parameter. If the URL isn't available in the triggering event's attributes, use this customer aggregate:

last page_visit location

Track Client IP Address

last session_start ip

Deduplication

The solution supports two deduplication methods:

• Event ID: Send the same ID from the pixel using API. This works especially well for purchase events, where you can use an order ID or transaction ID as the event_id for deduplication.
• FBP parameter deduplication: Set up automatic FBP tracking (see above). Webhook presets automatically send the FBP parameter with each API request, and most events get deduplicated this way.

See Meta's article on event deduplication for more details.

Limitations

• The access token appears in the webhook endpoint URL field.
• Although Conversions API supports sending the external_id parameter to identify customers using external IDs (like cookie or CRM IDs), our Meta ads retargeting doesn't support creating audiences based on external_id.