# Facebook Conversions API [Facebook ](https://www.facebook.com/)is an online social media and social networking service owned by [Meta](https://www.meta.com).\ 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' You need a Facebook Business Manager account Then on the menu, click on 'Events Manager': ![Events Manager](https://1259070148-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Mk6XpTQ2LaRLcr2tA-d%2Fuploads%2Fgit-blob-05193d4de0332f3d3712f960e42bce6a1085de0c%2Fcapture-de-cran-2020-10-29-a-10.30.43.png?alt=media\&token=136c164e-6ddd-4703-8eaa-d3c5068b5c3f) Here you have to create a new Web Pixel: ![New web Pixel](https://1259070148-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Mk6XpTQ2LaRLcr2tA-d%2Fuploads%2Fgit-blob-42e8808fc941ff07a1b58f89f384978ea0bbc9c5%2Fcapture-de-cran-2020-10-29-a-12.01.41.png?alt=media\&token=bbafefdc-1a11-499f-8a9f-884a29f2e0e0) Select Conversions API and give a name to your connection: ![](https://1259070148-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Mk6XpTQ2LaRLcr2tA-d%2Fuploads%2Fgit-blob-bc0ed9d57cb8dd326ba7b7eb2b3954ccd57278c3%2Fcapture-de-cran-2020-10-29-a-12.02.46.png?alt=media\&token=cd961d98-381f-4ba5-b95f-95ccd66b5ee9) 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](https://1259070148-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Mk6XpTQ2LaRLcr2tA-d%2Fuploads%2Fgit-blob-c4a4c3fff2991ca0e75e8388e8528d6652b306f0%2Fcapture-de-cran-2020-10-29-a-12.13.54.png?alt=media\&token=e1d0e725-c854-4e78-9617-7e276e53e726) You can now copy and paste this ID on our connector. Then you need the Access Token ## Where can I find the access token? You can set your access token in two ways: 1. Facebook Login For Business Authentication 2. Generate a long-lived token {% hint style="info" %} If you configure both, the "Facebook Login For Business Authentication" will be prioritized. {% endhint %} ### Facebook Login For Business Authentication {% hint style="success" %} This is the recommended authentication method. {% endhint %} 1. In [your Commanders Act account](https://app.commandersact.com/), access `(1) Administration` → `(2) Connector Credentials` or click the link `add a new account` in the destination settings.\ \ ![](https://1259070148-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Mk6XpTQ2LaRLcr2tA-d%2Fuploads%2Fgit-blob-c29c9035ed0f8f9a9ca72da232341c8914423f1a%2Ftoken_1.png?alt=media)\\ 2. Click `(3) Add connector credentials` on the top right:\ \ ![](https://1259070148-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Mk6XpTQ2LaRLcr2tA-d%2Fuploads%2Fgit-blob-d11166531dd35851086dd43afed2317a0bfcecf8%2Ftoken_2.png?alt=media)\\ 3. Select `(4) Facebook Ads`\ \ ![](https://1259070148-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Mk6XpTQ2LaRLcr2tA-d%2Fuploads%2Fgit-blob-c568d18392c4e6d7d5232caf4179b6894e7ef1df%2Ftoken_3.png?alt=media)\\ 4. Log in with your Facebook account credentials. 5. Go to your destination settings and select your added credentials in the drop-down menu under `(5) API Authentication` → `(6) Credentials`\ \ ![](https://1259070148-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Mk6XpTQ2LaRLcr2tA-d%2Fuploads%2Fgit-blob-13a4fd19caef40d786074f302982a133c6b9cc95%2Ftoken_4.png?alt=media) 6. Save your destination settings. ### Generate a long-lived token 1. Go to [Meta Event Manager](https://www.facebook.com/events_manager2/) 2. On the left menu, select `(1)` `Data sources` . ![](https://1259070148-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Mk6XpTQ2LaRLcr2tA-d%2Fuploads%2Fgit-blob-0408a68e9579210479f2439b3cd870219ef827b7%2Ffacebook_capi_1.png?alt=media) 3. Locate your `(2)` existing dataset and select it or [create a new dataset](https://www.facebook.com/business/help/5818684664831465?id=490360542427371). ![](https://1259070148-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Mk6XpTQ2LaRLcr2tA-d%2Fuploads%2Fgit-blob-201de67954592e6f286a7104b5f6e6eea84911c9%2Ffacebook_capi_2.png?alt=media) 4. Click the tab `(3)` `Settings` ![](https://1259070148-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Mk6XpTQ2LaRLcr2tA-d%2Fuploads%2Fgit-blob-a682f428fd56018a4f256526061ee75dba3cf85b%2Ffacebook_capi_3.png?alt=media) 5. Locate the link `(4)` `Generate access token` and click it to generate an access token ![](https://1259070148-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Mk6XpTQ2LaRLcr2tA-d%2Fuploads%2Fgit-blob-657c8883aa160ff85195ed0a48450c30c9d7bde9%2Ffacebook_capi_4.png?alt=media) {% hint style="warning" %} If you can't click the link "Generate access token" then you don't have the admin rights. {% endhint %} 6. Copy and paste your access token into the field `API Access Token` in your destination and save your destination settings. ## 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: ) 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. {% hint style="warning" %} **event\_id** should be the same {% endhint %} 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... ```json { "event_name": "purchase", "id": "purchase_id_1234", "type": "online", "user": { "email": "user@example.com", "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 : ```json { "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) {% embed url="" %} {% hint style="info" %} Most properties can be remapped using our "Smart Mapping" feature. {% endhint %}
Commanders Act PropertiesFacebook Properties
event_id [2][3]event_id [1]
event_nameevent_name [4]
context.event_timestampevent_time [5]
context.page.urlevent_source_url
context.page.referrerreferrer_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]
{% hint style="info" %} > **\[1]** Set based on available properties, in the reported order on the left. Default to a random generated value based on the timestamp.\ > \&#xNAN;**\[2]** In the base path/root of your event.\ > \&#xNAN;**\[3]** In `integrations.facebook` of your event.\ > \&#xNAN;**\[4]** See [Mapping: event\_name](#mapping-event_name) for more details.\ > \&#xNAN;**\[5]** If no value is provided the current timestamp is used.\ > \&#xNAN;**\[6]** See [Mapping: action\_source](#mapping-action_source) for more details.\ > \&#xNAN;**\[7]** See more details following this [LINK](https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/server-event). > {% endhint %} ### Mapping: `event_name` Facebook Pixel specifies [*Standard Events*](https://developers.facebook.com/docs/facebook-pixel/implementation/conversion-tracking#standard-events) whose semantics correspond to events in the [*Commanders Act Standard*](https://community.commandersact.com/platform-x/developers/tracking/events-reference) 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)* {% hint style="info" %} **Remark:** You can customise the event\_name using *Properties Transformations* in Destination settings. {% endhint %} ### Mapping: `action_source` {% embed url="" %} 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 : ```json // 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` {% embed url="" %} {% hint style="info" %} Most properties can be remapped using our "Smart Mapping" feature. {% endhint %}
Commanders Act PropertiesFacebook Properties
user.id (hashed)
context.device.sdk_id
user.tcId , user.tcid or user.tc_id		user_data.external_id [1]
user.emailuser_data.em (email, hashed)
user.phoneuser_data.ph (phone, hashed)
user.genderuser_data.ge (gender, hashed)
user.birthdateuser_data.db (birthdate, hashed)
user.lastnameuser_data.ln (last name, hashed)
user.firstnameuser_data.fn (first name, hashed)
user.cityuser_data.ct (city, hashed)
user.stateuser_data.st (state, hashed)
user.zipcodeuser_data.zp (zip code, hashed)
user.countryuser_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]
partners.facebook.fb_login_iduser_data.fb_login_id [7]
user_data[Property Name] [8]user_data[Property Name]
{% hint style="info" %} > **\[1]** Comma-separated string: values in the order provided on the left. \ > \&#xNAN;**\[2]** In `integrations.facebook` or in the root of your events with the first having priority. \ > \&#xNAN;**\[3]** In `context.device` of your event. \ > \&#xNAN;**\[4]** Automatically set if generated by Commanders Act OneTag. \ > \&#xNAN;**\[5]** Automatically created by the Facebook Pixel client-side tag. \ > \&#xNAN;**\[6]** Only for app events. \ > \&#xNAN;**\[7]** The identifier issued by Meta when a person first logs into an instance of an app. This is also known as App-Scoped ID.\ > \&#xNAN;**\[8]** In `integrations.facebook` of your event. > {% endhint %} Every property can be overridden using `integrations.facebook.user_data.` #### 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` {% embed url="" %} {% hint style="info" %} 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` . {% endhint %} | 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.product.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.product.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]` | {% hint style="info" %} > **\[1]** Mutually exclusive with `custom_data.content_ids` and set if all the following properties are present and valid: `items.X.product.id` , `items.X.product.price` , `items.x.quantity` . \ > \&#xNAN;**\[2]** Array containing all product identifiers. Mutually exclusive with `custom_data.contents`. \ > \&#xNAN;**\[3]** Depending on the selected value for `Content type value` , which can be found under `Advanced Settings` , this is either `product` or not set. \ > \&#xNAN;**\[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. \ > \&#xNAN;**\[5]** In `integrations.facebook` in your event. > {% endhint %} #### Default behavior Facebook specifies rules for [standard properties](https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/custom-data). 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.` 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.`. Example : ``` cact('trigger', 'purchase', { "currency": "EUR", "value": 101, "integrations": { "facebook": { "custom_data": { "content_name": "some_custom_name", "your_field": "your_value" } } } }); ``` ### Mapping: `app_data` {% embed url="" %} {% hint style="info" %} Most properties can be remapped using our "Smart Mapping" feature. {% endhint %} | 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]` | {% hint style="info" %} > **\[\*]** Mandatory property. \ > \&#xNAN;**\[1]** In `context.device` of your event. \ > \&#xNAN;**\[2]** In `integrations.facebook` or in the root of your events with the first having priority. \ > \&#xNAN;**\[3]** When `context.device.type` is set with `Android` or `iOS` (case insensitive), this is set with `a2` or `i``2` respectively. \ > \&#xNAN;**\[4]** Can be set in `Smart Mapping` → `App Data` → `Device Abbreviated Timezone` . \ > \&#xNAN;**\[5]** Can be set in `Smart Mapping` → `App Data` → `CPU Cores` . \ > \&#xNAN;**\[6]** Can be set in `Smart Mapping` → `App Data` → `External Storage Size` . \ > \&#xNAN;**\[7]** Can be set in `Smart Mapping` → `App Data` → `Available Storage Size` . > {% endhint %} ### `integrations.facebook.*` deprecation {% hint style="warning" %} `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. {% endhint %} ## 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](https://doc.commandersact.com/features/sources/sources-catalog/server/http-tracking-api) source to send your offline events from your servers (or any other emmiter).\ You just need to send a [purchase event](https://doc.commandersact.com/developers/tracking-and-integrations/tracking/events-reference#purchase) with the `type` property equals to `offline`\ More details on the automatic mapping here: [Mapping action\_source](#offline-conversions-specificity)