Facebook Conversions API
Aka Facebook CAPI
Facebook is an online social media and social networking service owned by Meta. This destination allows you to push every kind of event directly to Facebook through API: by sending online and offline conversions to you can increase the reach and accuracy of your campaigns.
You can, for example, not send campaigns related to a specific product to users who already bought it, or you can also send campaigns to users who bought a specific product in cross-sell logic.
How to send events to Facebook?
Facebook developed an API called 'Facebook Conversions API' https://developers.facebook.com/docs/marketing-api/conversions-api
You need a Facebook Business Manager account https://business.facebook.com/
Then on the menu, click on 'Events Manager':

Here you have to create a new Web Pixel:

Select Conversions API and give a name to your connection:

Now your pixel is created and you will have access to the IDs needed on our connector.
Where can I find the Pixel ID?
You need to fill the pixel ID on our connector, it is the ID of the pixel you just created on steps above.
You can find this ID when you click on the pixel's name and on the right of the graph activities. You can find it also on the settings tab.

You can now copy and paste this ID on our connector.
Then you need the Access Token
Where can I find the access token?
Go to Meta Event Manager
On the left menu, select
(1)
Data sources
.
Locate your
(2)
existing dataset and select it or create a new dataset.
Click the tab
(3)
Settings
Locate the link
(4)
Generate access token
and click it to generate an access token
If you can't click the link "Generate access token" then you don't have the admin rights.
Copy and paste your access token into the field
API Access Token
in your destination.
How to manage consents?
Only events with a consent will be sent to Facebook
Only conversions with personal information (email and/or phone number...) will be sent to Facebook
For customers with our product TRUST Commander:
TRUST Commander is our Consent Management Platform. (More information: https://www.commandersact.com/en/solutions/trustcommander/)
On the connector, the consent is managed with the field 'User Consent Category'. You should enter a category ID, the one corresponding to Facebook (advertising) on Trust consent categories.
For customers without our product TRUST Commander:
We should distinguish 3 cases:
Your online events are collected through our Commanders Act event's tag: You have to provide, in the event tags, the list of category ids consented by the user, through the
consent_categories
property.You are pushing your events to us through API or CSV file: a field
consent_categories
must be added on the JSON or CSV to precise the consent category IDs of the user. Then inside the connector setting, use the field 'User Consent Category' to enter a category ID, the one corresponding to Facebook (advertising)You already manage consents on your side and you only send us, from your server,
events that obtained the consent for the category advertising. In this case, do not fill the field ‘User Consent Category’ in the connector.
How the deduplication between the pixel and server is managed?
Using both the pixel and server is recommended per Facebook as it could avoid losing data.
To make it works, you should have the same configuration for both the pixel and server, using same Facebook parameters.
event_id should be the same
On the pixel, event_id
is automatically generated by our Commanders Act Tag and we retrieve the same value for the server on integrations.facebook.event_id
. As a result, these 2 values should be the same.
Event_name
should be the same also.
Fbp
parameter is automatically retrieved to keep the same value between pixel and server.
Deduplication works when the same event is sent first from the browser and then from the server, otherwise it creates a duplicate. Events are pushed in real-time.
Examples
On pixel:
fbq('track', 'AddToCart', {
value: #CARTVALUE#,
currency: #CURRENCY#,
contents: fb_addtocart_products,
content_type: 'product'
}, { eventID: tC.uniqueEventId });
eventID: tC.uniqueEventId
is automatically generated.
On server:
integrations.facebook.event_id
integrations.facebook.event_id
automatically retrieves the eventID value coming from the pixel (eventID: tC.uniqueEventId
) for standard events.
Mappings to Facebook Standard Events
The Facebook CAPI Destination will turn the Commanders Act event like...
{
"event_name": "purchase",
"id": "purchase_id_1234",
"type": "online",
"user": {
"email": "[email protected]",
"id": "user_example_id",
"tcId": "202205231352367212315156",
"consistent_anonymous_id": "202205231352367212315156",
"consent_categories": [ "1", "2", "3", "4" ]
}
"value": 246.9,
"currency": "EUR",
"items": [
{
"product": {
"id": "product123"
},
"price": "123.45",
"id": "ET",
"item_category": "Car",
"item_quantity": 2
}
],
"context": {
"event_id": "1a01c3e940f150eb9b8c542587f1abfd8f0e1cc1f",
"event_timestamp": 1707830130234,
"page": {
"location": {
"href": "https://site.com/path?s=2",
"hostname": "site.com",
"pathname": "/path",
"search": "?s=2"
},
"url": "https://site.com/path?s=2"
},
"device": {
"ip": "123.123.123.123",
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36"
},
"cookie": "_fbp=fb.1.1653472342558.832801021; some_other=cookie;"
},
"integrations": {
"facebook": {
"custom_data": {
"category": "category1"
},
"user_data": {
"fbp": "fb.1.1558571054389.1098115397"
}
}
},
}
...into Facebook CAPI events like :
{
"event_name": "Purchase",
"event_time": 1707830130,
"event_source_url": "https://site.com/path?s=2",
"action_source": "website",
"user_data": {
"em": [
"b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514"
],
"external_id": [
"user_example_id"
],
"client_ip_address": "123.123.123.123",
"client_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36",
"fbc": "fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890",
"fbp": "fb.1.1558571054389.1098115397"
},
"custom_data": {
"id": "purchase_id_1234",
"currency": "EUR",
"value": 246.9,
"contents": [
{
"id": "product123",
"quantity": 2,
"item_price": 123.45
}
]
}
}
The following mappings are fully automated and do not require any additional configuration by default. You can still customize each as follows.
Mapping: (root)
event_id
[2][3]
event_id
[1]
event_name
event_name
[4]
context.event_timestamp
event_time
[5]
context.page.url
event_source_url
context.page.referrer
referrer_url
Enable App tracking
type
action_source
[6]
opt_out
[3]
opt_out
[7]
data_processing_options
[3]
data_processing_options
[7]
data_processing_options_country
[3]
data_processing_options_country
[7]
data_processing_options_state
[3]
data_processing_options_state
[7]
Mapping: event_name
event_name
Facebook Pixel specifies Standard Events whose semantics correspond to events in the Commanders Act Standard
If the destination receives a Commanders Act Event with event_name
matching the list, it will automatically be sent under the associated Facebook Standard Event name. Otherwise, it will be sent without any transformation
begin_checkout
InitiateCheckout
purchase
Purchase
add_to_cart
AddToCart
view_item
ViewContent
view_item_list
ViewContent
search
Search
add_payment_info
AddPaymentInfo
add_to_wishlist
AddToWishlist
generate_lead
Lead
page_view
PageView
sign_up
CompleteRegistration
contact
Contact
customize_product
CustomizeProduct
donate
Donate
find_location
FindLocation
schedule
Schedule
search
Search
start_trial
StartTrial
submit_application
SubmitApplication
subscribe
Subscribe
Examples:
If the destinations sees a
add_to_cart
event (IN the list), it will send anAddToCart
to Facebook CAPIIf the destinations sees a
custom_name
event (NOT IN the list), it will send ancustom_name
to Facebook CAPI (no transformation)
Mapping: action_source
action_source
By default, action_source
will be set to 'website'
(most events relate to online activity).
IF
Enable App tracking
is checked THEN action_source='app'
Offline conversions specificity:
IF
your event has the propertytype='offline'
THEN
the Facebook Event will haveaction_source='physical_store'
ELSE
the Facebook Event will haveaction_source='website'
Example :
// CommandersAct
{
"event_name": "purchase",
"type": "offline",
// ...
}
// Event sent to Facebook API:
{
"event_name": "Purchase",
"action_source": "physical_store"
"custom_data": { /* */ }
// ...
}
If you need to overwrite this value, you currently can use Properties Transformation to set the integrations.facebook.action_source
.
Mapping: user_data
user_data
user.id
(hashed)
context.device.sdk_id
user.tcId
, user.tcid
or user.tc_id
user_data.external_id
[1]
user.email
user_data.em
(email, hashed)
user.phone
user_data.ph
(phone, hashed)
user.gender
user_data.ge
(gender, hashed)
user.birthdate
user_data.db
(birthdate, hashed)
user.lastname
user_data.ln
(last name, hashed)
user.firstname
user_data.fn
(first name, hashed)
user.city
user_data.ct
(city, hashed)
user.state
user_data.st
(state, hashed)
user.zipcode
user_data.zp
(zip code, hashed)
user.country
user_data.country
(hashed)
ip
[3][4]
user_data.client_ip_address
user_agent
[3][4]
user_data.client_user_agent
fbc
[2]
The cookie "_fbc"
[5]
user_data.fbc
(Click ID)
fbp
[2]
The cookie "_fbp"
[5]
user_data.fbp
(Browser ID)
advertising_id
[3]
user_data.anon_id
[6]
user_data.madid
[6]
user_data[Property Name]
[7]
user_data[Property Name]
Every property can be overridden using integrations.facebook.user_data.<property>
Minimal required information
Events can only be used if there is enough information to match a user. Facebook expects at least one user_data
property, but strongly advises sending as many properties as possible.
Here are our conditions to send the events :
at least 1 of those fields:
em
,ph
,external_id
,fbp
,fbc
at least 3 of the other fields
Note : external_id, fbp, fbc will allow matching event with other events. But to match a user, one of those events shall contain additional information (em
and ph
are best suited for matching)
Mapping: custom_data
custom_data
value
custom_data.value
currency
items.0.currency
custom_data.currency
id
custom_data.order_id
search_term
custom_data.search_string
items.X.id
custom_data.contents.X.id
[1]
items.X.quantity
custom_data.contents.X.quantity
[1]
items.X.product.price
custom_data.contents.X.item_price
[1]
items.0.product.name
custom_data.content_name
items.0.product.category_1
custom_data.content_category
items.X.id
custom_data.content_ids
[2]
Content type value
custom_data.content_type
[3]
status
custom_data.status
items.length
custom_data.num_items
Send all your event properties as custom data
custom_data[Property Name]
[4]
custom_data[Propery Name]
[5]
custom_data[Property Name]
Default behavior
Facebook specifies rules for standard properties. The rest is completely free.
By default, we fill custom_data
as follows :
We copy all CommandersAct Event properties into
custom_data
(except some context fields likesource_key
)Then we map the standard properties according to the table above (can overwrite 1. values)
Finally, we overwrite with
integrations.facebook.custom_data.<property>
if exists
Overwrite custom_data
custom_data
Best choice would be to use Properties Transformation to modify your event properties which will be copied into custom_data
.
But you can override the final value using integrations.facebook.custom_data.<property>
.
Example :
cact('trigger', 'purchase', {
"currency": "EUR",
"value": 101,
"integrations": {
"facebook": {
"custom_data": {
"content_name": "some_custom_name",
"your_field": "your_value"
}
}
}
});
Mapping: app_data
app_data
ad_tracking_enabled
[1]
advertiser_tracking_enabled
application_tracking_enabled
[1]
application_tracking_enabled
context.campaign.name
campaign_ids
install_referrer
[2]
install_referrer
installer_package
[2]
installer_package
url_schemes
[2]
url_schemes
windows_attribution_id
[2]
windows_attribution_id
type
[1]
extinfo[0]
[3]
app.namespace
[1]
extinfo[1]
app.build
[1]
extinfo[2]
app.version
[1]
extinfo[3]
os.version
[1]
extinfo[4]
model
[1]
extinfo[5]
language
[1]
extinfo[6]
[No default field]
[4]
extinfo[7]
network.carrier
[1]
extinfo[8]
screen.width
[1]
extinfo[9]
screen.height
[1]
extinfo[10]
screen.density
[1]
extinfo[11]
[No default field]
[5]
extinfo[12]
[No default field]
[6]
extinfo[13]
[No default field]
[7]
extinfo[14]
timezone
[1]
extinfo[15]
integrations.facebook.*
deprecation
integrations.facebook.*
deprecationintegrations.facebook.*
usage will be deprecated.
The feature is still working, but it is recommended to use the destination settings instead for maintenance and reliability purpose.
Check results on Facebook interface
To view quality matching on Facebook interface, go here: Events manager > select the event > View Details > Event Matching > Rating Background
How to send offline conversions
The recommanded way is to use the HTTP Tracking API source to send your offline events from your servers (or any other emmiter).
You just need to send a purchase event with the type
property equals to offline
More details on the automatic mapping here: Mapping action_source
Last updated
Was this helpful?