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':

Events Manager

Here you have to create a new Web Pixel:

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.

Find the Pixel ID

You can now copy and paste this ID on our connector.

Then you need the Access Token

Where can I find the access token?

1. Go to Meta Event Manager
2. On the left menu, select (1) Data sources .

1. Locate your (2) existing dataset and select it or create a new dataset.

1. Click the tab (3) Settings

1. 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.

1. 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": "[e-mail]",
    "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)

Server Event Parameters - Conversions API - Documentation - Meta for DevelopersMeta for Developers

Most properties can be remapped using our "Smart Mapping" feature.

Commanders Act Properties	Facebook Properties
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]

[1] Set based on available properties, in the reported order on the left. Default to a random generated value based on the timestamp. [2] In the base path/root of your event. [3] In integrations.facebook of your event. [4] See Mapping: event_name for more details. [5] If no value is provided the current timestamp is used. [6] See Mapping: action_source for more details. [7] See more details following this LINK.

Mapping: 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

Commanders Act Events	Facebook Events
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 an AddToCart to Facebook CAPI

• If the destinations sees a custom_name event (NOT IN the list), it will send an custom_name to Facebook CAPI (no transformation)

Remark: You can customise the event_name using Properties Transformations in Destination settings.

Mapping: action_source

Server Event Parameters - Conversions API - Documentation - Meta for DevelopersMeta for Developers

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 property type='offline'

• THEN the Facebook Event will have action_source='physical_store'

• ELSE the Facebook Event will have action_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

Customer Information Parameters - Conversions API - Documentation - Meta for DevelopersMeta for Developers

Most properties can be remapped using our "Smart Mapping" feature.

Commanders Act Properties	Facebook Properties
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]

[1] Comma-separated string: values in the order provided on the left. [2] In integrations.facebook or in the root of your events with the first having priority. [3] In context.device of your event. [4] Automatically set if generated by Commanders Act OneTag. [5] Automatically created by the Facebook Pixel client-side tag. [6] Only for app events. [7] In integrations.facebook of your event.

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 Parameters - Conversions API - Documentation - Facebook for DevelopersFacebook for Developers

Most properties can be remapped using our "Smart Mapping" feature. The fields custom_data.contents and custom_data.content_ids are mutually exclusive, meaning that just one of them can be present following this logic:

• If all these properties are present and set within items: product.id , quantity , and product.price , then custom_data.contents is set with all product information.

• otherwise, custom_data.content_ids is set with all available product.id .

Commanders Act Properties	Facebook Properties
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]

[1] Mutually exclusive with custom_data.content_ids . [2] Array containing all product identifiers. Mutually exclusive with custom_data.contents. [3] Depending on the selected value for Content type value , which can be found under Advanced Settings , this is either product or not set. [4] When Send all your event properties as custom data is checked all properties in your event with type "string", "number" and "boolean" will be included in custom_data with the same property name. [5] In integrations.facebook in your event.

Default behavior

Facebook specifies rules for standard properties. The rest is completely free.

By default, we fill custom_data as follows :

1. We copy all CommandersAct Event properties into custom_data (except some context fields like source_key)

2. Then we map the standard properties according to the table above (can overwrite 1. values)

3. Finally, we overwrite with integrations.facebook.custom_data.<property> if exists

Overwrite 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 Parameters - Conversions API - Documentation - Meta for DevelopersMeta for Developers

Most properties can be remapped using our "Smart Mapping" feature.

Commanders Act Properties	Facebook Properties
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]

[1] In context.device of your event. [2] In integrations.facebook or in the root of your events with the first having priority. [3] When context.device.type is set with Android or iOS (case insensitive), this is set with a2 or i2 respectively. [4] Can be set in Smart Mapping → App Data → Device Abbreviated Timezone . [5] Can be set in Smart Mapping → App Data → CPU Cores . [6] Can be set in Smart Mapping → App Data → External Storage Size . [7] Can be set in Smart Mapping → App Data → Available Storage Size .

integrations.facebook.* deprecation

integrations.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