Facebook is an online social media and social networking service owned by Meta.

Facebook is an online social media and social networking service owned by Meta. This destination leverages Conversions API to help you get improved performance in lead ads by sharing your CRM data about your leads back to Meta to unlock quality lead optimization.

Key features

The Facebook Lead Ads destination provides the following key features:

• Events structure: our Events reference leverages Facebook events, meaning that your data is properly bridged to the expected fields in an optimized way.

• Prebuilt mappings: data mapping for event-based destinations happens automatically, which simplifies user inputs.

• Smart mapping: data mapping can be readjusted using your datalayer defined fields.

Destination setup

Configuration

Quick reference

Field Mappings

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?

Click on the settings tab.

Scroll until the section 'Conversions API'

Click on the button 'Create Access Token':

Then you can copy and paste the Access Token on our connector.

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.

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

{
  "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: 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

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)

Mapping: action_source

By default, action_source will be set to 'website' (most events relate to online activity)

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

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

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

integrations.facebook.* deprecation

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

Commanders Act provides a GTM template to connect your existing GTM implementation to our serverside endpoint, enabling "Facebook CAPI" in a secured environment.

Setup

1. Add our bridge tag

2. Update your Facebook tags

1. Add our bridge tag

First, access GTM and then add our template "Commanders Act | Serverside events bridge" You can follow our dedicated guide:

2. Update your Facebook tags

If you're planning to keep running your existing Facebook pixels while using "Facebook CAPI" through GTM, it's really important that you update them following these guidelines. This will allow to deduplicate and keep consistent measurements of your events.

The process is straightforward as for every event you're sending via pixel tags you just need to add the event identifier - On GTM, open your "Facebook Pixel" tag and expand (14) "More Settings" to locate the "Event ID" and click (15) its icon on the right.

A new window will slide-in. Click on (16) the plus on the top right.

Click on (17) the "Variable Configuration".

Click (18) the "JavaScript Variable".

Rename your (19) variable as window.tC.uniqueEventId and set the same name in (20) the "Global Variable Name" then click (21) the "Save" button.

Back on the tag configuration, expand (22) "Advanced Settings" and (23) "Tag Sequencing" to check (24) the option "Fire a tag before Facebook Pixel fires". In "Set-up Tag", select (25) "Commanders Act | Serverside events bridge" and save your tag.

The Performance tab can now display Event Match Quality insights, coming from Facebook. It represents the matching quality, referring to the quality of events sent (completeness of data, like events with email, phone, fbp, fbc...). More identifiers are present on events sent, better is the score.

First, select (or login) the Facebook account to which belongs the pixel defined in the Settings step.

You can click on a specific event to get more details about the score.

For each event, you can get the details of matching keys and the corresponding volume (%).

This information is also available on Facebook Business Manager interface (Events Manager).

Facebook is an online social media and social networking service owned by Meta. ​An API based Facebook Connector can be set up with the following procedure. The connector will send users data of all the users belonging to a given segment. The audience sent can contain both FB subscribers and non subscribers.

User variables mapping

More information you send to Facebook, better is the matching with Facebook. You can choose to send email, phone number or any other information to increase the matching with Facebook.

If users don't have enough information, we will reject them (example: if a user only have a zip code, Facebook will not be able to match this user with only this information).

It takes up to 24 hours for Facebook to match users.

Configuration

You need 2 information for the Facebook connector:

• Ad Account ID

• Access Token

Where can I find the Ad Account ID?

You have to go on Facebook Business https://business.facebook.com/ and login to your account.

Then you have to go to ‘Ad Account settings’:

And you will find the Ad Account ID:

Copy and paste it on our Facebook connector.

Where can I find the Access Token?

For this part, you have to go to Facebook Developers https://developers.facebook.com/ and create or login to your account (you need to have a dedicated account for Facebook Developer).

Create a new app

Add the product ‘Marketing API’.

Go on ‘Settings’ and ‘Advanced’ section

Link your app to your Business Manager account and add your Ad Account ID in the ‘Authorized Ad Account ID’ section:

Then click on 'App Review' and 'Permissions and features'. Find the 'Ads Management Standard Access' component and, if you don't already have it, submit a request:

https://developers.facebook.com/docs/marketing-api/access#standard​

Wait for the validation of your request.

Now you have an App linked to your Facebook Business Manager Account (https://business.facebook.com/). Please check this page to be sure that the App is well associated with the Business account:

You should see in your Facebook Business account the new App you created.

Generate the access token

You can choose here to generate a token without any expiration date (1st method, recommended) or with an expiration date (60 days - 2nd method, not recommended).

1st method: generate a token without any expiration date

You have to create a system user on your Facebook Business Account (https://business.facebook.com/).

When it is done, you can Generate New Token:

Select the App you have created before and select the right permission:

Then copy and paste the generated token on our connector:

2nd method: generate an access token with an expiration date (60 days)

On the Facebook developers, on your App you created, click on ‘Marketing API’ and ‘Tools’.

On ‘Get Access Token’, tick ‘ads_management’ and click on ‘Get Token’.

You can now copy and paste this token on our Facebook connector.

Common errors

Check new audience created on Facebook

Save the connector and users who will enter the segment will be pushed to Facebook new custom audience.

Then on Facebook, click on Audiences.

A new custom audience will be created.