# Facebook Conversions Destination Setup Guide


This guide will help you set up Facebook Conversions as a destination in RudderStack.

## Setup

1. In your [RudderStack dashboard](https://app.rudderstack.com/), go to **Directory** > **Destinations** > **Cloud Destinations**  and search for **Facebook Conversions**.
2. Connect your source and click **Continue**.

### Connection settings

Configure the following settings to set up Facebook Conversions as a destination in RudderStack:

- **Name**: Assign a name to uniquely identify the destination.
- **Dataset ID**: Enter the dataset ID. If an existing pixel is linked to your dataset, your dataset ID will be the same as your [Pixel ID](https://www.rudderstack.com/docs/destinations/streaming-destinations/fb-pixel/setup-guide/#where-can-i-find-the-pixel-id).
- **Business Access Token**: Enter the business access token from your Facebook business account. This is required to send events in cloud mode. For more information on obtaining the business access token, see the [FAQ](#where-can-i-find-the-business-access-token).

### Connection compatibility

{{< destination-config >}}

### Configuration settings

After completing the initial setup, configure the following settings to correctly receive your data in Facebook:

#### Event settings

- **Action Source**: From the dropdown, select the fallback `action_source` value you want to set **if** `action_source` is not present in your event properties. RudderStack provides the following options:

{{< image src="images/event-stream-destinations/fb-conversions-action-source.webp" alt="Action source setting" >}}

#### Destination settings

- **Limited Data Usage**: If turned on, RudderStack takes the data processing information from the payload and sends it to Facebook. The data in the RudderStack payload should be in the following format:

```javascript
"context": {
  "dataProcessingOptions": [
    [
      "LDU"
    ],
    1,
    1000
  ],
  "fbc": "fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890",
  "fbp": "fb.1.1554763741205.234567890",
  "fb_login_id": "fb_id",
  "lead_id": "lead_id",
  "device": {
    "id": "df16bffa-5c3d-4fbb-9bce-3bab098129a7R",
    "manufacturer": "Xiaomi",
    "model": "Redmi 6",
    "name": "xiaomi"
  },
  "network": {
    "carrier": "AirCarrier"
  },
  "os": {
    "name": "android",
    "version": "8.1.0"
  },
  "screen": {
    "height": "100",
    "density": 50
  },
  "traits": {
    "email": "john@example.com",
    "anonymousId": "c82cbdff-e5be-4009-ac78-cdeea09ab4b1"
  }
}
```

{{< warning >}}
If this setting is turned on, RudderStack maps the values in the `context.dataProcessingOptions` array to `commonData.data_processing_options`, `commonData.data_processing_options_country`, and `commonData.data_processing_options_state` fields.
{{< /warning >}}

You can set the value of the [`fbc`](https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/fbp-and-fbc/#fbc) parameter using the `context.fbc` field as shown in the above payload. 

If not set explicitly, RudderStack autogenerates it using the following values:

- Fetches `fbclid` from `context.page.url`.
- Uses `originalTimestamp` as the creation time.
- Sets `subdomainIndex` to `1`.
- Sets `version` to `fb`. <br /><br />

- **Use as Test Destination**: Turn on this setting if you are using this destination for testing purposes and enter the **Test Event Code**. You can find this code in your Facebook dashboard. When turned on, you can check your events in the Facebook dashboard in realtime.

{{< info >}}
RudderStack maps the `context.dataProcessingOptions` to `data_processing_options` in Facebook according to the [Facebook developer documentation](https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/server-event#data-processing-options).
{{< /info >}}

- **Don't send external_id for user**: If turned on, RudderStack does not send either `userId` or `anonymousId` as the `external_id` to Facebook.

#### Other settings

- **Client-side event filtering**: Specify the events to be discarded or allowed to flow through. For more information, see [Client-side Event Filtering]({{< ref "sources/event-streams/sdks/event-filtering.md" >}}).
- **Consent management settings**: Configure the consent management settings for the specified source by choosing the **Consent management provider** from the dropdown and entering the relevant consent category IDs. See [Consent Management in RudderStack]({{< ref "data-governance/consent-management/overview.md" >}}) for more information on this feature.

#### Event mapping

Click the **Set up mapping** button to map your RudderStack events and properties to specific Facebook custom events.

{{< info >}}
RudderStack expects the `timestamp` and `originalTimestamp` fields to be present at the root level of the `track` event payload in the **ISO 8601** format. 

When you connect a Reverse ETL source to this destination and map your warehouse columns using the [JSON mapper]({{< ref "data-pipelines/reverse-etl/developer-guides/json-data-mapping.md" >}}), these fields get placed inside `properties`. Hence, you need to use a [transformation]({{< ref "transformations/overview.md" >}}) and move them to the root level so RudderStack can map them correctly.

See the [Cloud Mode Integration Guide]({{< ref "destinations/streaming-destinations/fb-conversions/cloud-mode.md#common-data" >}}) for full details.
{{< /info >}}

##### **PII properties**

{{< info >}}
The allowlist/denylist settings control only the standard Facebook PII fields listed below. They **do not affect** other mapped properties or top-level RudderStack identifiers like `userId` or `anonymousId`.

To control whether RudderStack sends `userId` or `anonymousId` as `external_id`, use the [Don't send external_id for user](#destination-settings) setting.
{{< /info >}}

- **Denylist PII Properties**: RudderStack drops the PII properties specified in this field. However, if you toggle on the **Denylist PII Hash Property** setting, RudderStack encrypts the properties in SHA256 format before sending them to Facebook. Facebook identifies the following standard fields as PII properties and they are **denylisted by default**:

  - `email`
  - `firstName`
  - `lastName`
  - `firstname`
  - `lastname`
  - `first_name`
  - `last_name`
  - `gender`
  - `city`
  - `country`
  - `phone`
  - `state`
  - `zip`
  - `postalCode`
  - `birthday`

{{< info >}}
To hash and send any of the above properties instead of denylisting them, enter the property name in the **Denylist PII Properties** field and toggle on the **Hash Denylist PII Property** toggle.
{{< /info >}}

- **Allowlist PII Properties**: The PII properties mentioned in this field are sent to Facebook if they are present in the event's properties.

{{< image src="images/event-stream-destinations/fb-conversions-pii-settings.webp" alt="PII settings" >}}

## FAQ 

#### Where can I find the dataset ID?

To get your dataset ID, go to your Facebook Ads Manager account. From the left navigation bar, select **Business Tools**, and click **Events Manager** under **Manage Business**.

{{< image src="images/event-stream-destinations/fb-conversions-dataset-id-1.webp" alt="Dataset ID" >}}

You should be able to see the ID underneath your site name under **Data Sources**: 

{{< image src="images/event-stream-destinations/fb-conversions-dataset-id-2.webp" alt="Dataset ID" >}}

#### Where can I find the Business Access Token?

In order to use the Facebook Conversions API, you need to generate an access token using the Facebook Events Manager:

1. Choose the relevant Facebook Pixel and click the **Settings** tab.
2. In the Conversions API section, click **Generate access token** under the **Set up manually** section:

{{< image src="images/event-stream-destinations/fb-conversions-generate-access-token.webp" alt="FB Conversions generate access token" >}}

{{< info >}}
For more information on how to use this access token or to generate your access token via your own app, see the [Facebook developer documentation](https://developers.facebook.com/docs/marketing-api/conversions-api/get-started/#via-events-manager).
{{< /info >}}

#### Can I hash my event data before sending it to RudderStack?

Yes. Facebook requires all user data, including data coming from `context.traits`, to be hashed. This includes `email`, `phone`, `birthday`, `address`, etc. By default, RudderStack automatically hashes all of the necessary properties for you. However, to hash these traits before sending to RudderStack, you need to send your event as follows:

```javascript
rudderanalytics.track(
  "event_name", {
    properties
  }, {
    integrations: {
      "Facebook Conversions": {
        hashed: true,
      },
    },
  }
)
```

{{< info >}}
RudderStack accepts any of the following names for Facebook Conversions in the `integrations` object:

- `fb_conversions`
- `fb conversions`
- `FacebookConversions`
- `Facebook Conversions`
- `FB Conversions`
- `Facebook_Conversions`
{{< /info >}}

The `integrations` object with these key-values notifies RudderStack to not hash the traits in `context.traits` as they are already hashed. Otherwise, RudderStack will hash your data again and Facebook will not be able to match the traits. Keep in mind that Facebook rejects any un-hashed data.

#### Why can I see my events in the RudderStack dashboard but not in the Facebook dashboard?

It may take up to 24 hours for your events to reflect in the Facebook dashboard.

You can also verify if your events are flowing correctly by toggling on the **Use as Test Destination** setting in the RudderStack dashboard - this reflects the events in the Facebook dashboard in real time.

<br />