Documentation

Facebook Conversions API

Suggest Edits

What is Facebook Conversions API?

Facebook commands the second-largest share of ad spend among tech platforms in the US. Businesses can serve ads to highly targeted audiences across all of its properties like Instagram, Audience Network and Messenger.

What are the benefits of Facebook Conversions API?

MetaRouter provides a server-side tracking alternative to the Facebook Pixel that gives businesses complete control over every data parameter sent to Facebook. When you explicitly map and transform all of your customer data, you gain transparency and comfort that Facebook cannot collect any data without your knowledge. The integration maintains addressability and attribution for all users, similar to the Facebook Pixel.

Facebook Conversions API Key Features

  • Enables Facebook Pixel removal
  • Up to 30% more data- including conversions- tracked compared to the Facebook Pixel
  • All customer data events and attributes unlocked for custom event mapping and transformation
  • No effect on website load latency

Getting Started - From Your Meta Business Account

MetaRouter's Facebook Business account needs access to your current Facebook Pixel(s) and testing Pixel (if applicable). The steps to provide access are listed below.

  1. Create a new Facebook Pixel named: [CustomerName] or [MetaRouter Test]

  2. Add MetaRouter as a partner under your Meta Business Account and share needed assets for testing.

    1. MetaRouter's Business ID - 359422874701700

  3. Select the Pixels you want to share with MetaRouter (MR Test and Production Pixels).

  4. Connect Facebook Ad Account(s) to the new test and production pixels.

  5. Connect your Product Catalog(s) to the new test pixel.

  6. Finding your Pixel ID:

    1. Go to Meta Events Manager
    2. Go to Data Sources
    3. Click on Pixel
    4. Click on Settings to find Pixel ID (it can also appear as Dataset ID)

  7. Generating an access token:

    1. Using Business Manager (recommended)

      1. Choose Pixel you want to implement

      2. Select the Settings Tab

      3. Find the Conversions API section and click on the Generate Access Token link under “Set up direct integration” and follow the instructions on the pop-up

        1. NOTE: Only visible to users with developer privileges for the business

      4. Save your access token in a secure place.

  8. Ensuring Conversions API is enabled in your account

    1. Click on the Manage Integrations button in the Overview tab in Events Manager.
    2. In the pop-up screen, check if you have the Conversions API set up and active. If not, click on Add New Integration > Conversions API > Set up. There is no need to go through App Review or request any permissions.

Getting Started - From Your MetaRouter Account

Add a Facebook Conversions API Integration

From the integration library, add a Facebook Conversions API integration. Then, fill out the Connection Parameters:

Connection ParameterDescription
API_VERSIONAPI version for integration. Latest version is v22.0.
PIXEL_IDID of Facebook Pixel
ACCESS_TOKENAccess token generated for API

Next, configure your event mappings (see below).

Finally, save your integration and add it to a pipeline. That's it!

Add a Facebook Tag sync

Adding the Facebook Tag sync is required to include the fbc and fbp values within your event stream. To do this:

  1. From the Pipelines page, find the pipeline associated with the web property you’d like to add a sync to. Hover over the three dot dropdown and select the “Build AJS File” option.
  2. Scroll down to the Identity Syncs section, click the Select Identity Syncs dropdown, and select Facebook Tag.
  3. Fill out the following fields:
    1. Consent Type: This should align to your Facebook categorization within your Consent Management tool. Refer to the Advanced Consent Enforcement documentation for more information.
    2. Tag ID: Include your Pixel ID here.
    3. Extra Tag IDs: Extra Pixel IDs can be included here.
    4. Fire on Re-Sync. This will fire a Facebook sync whenever an Identify call is made.
  4. When you are finished configuring your AJS file, scroll down and click Save and Build File.
  5. Deploy your file to see the changes applied to your web property.

That's it! Your sync should now be deployed and can provide the fbc and fbp values to your event stream.

Event Mappings

MetaRouter provides all of the event mappings that Facebook integrations typically require, including e-commerce lifecycle events. You may add custom events, parameters or mappings in accordance with Facebook's API documentation.

Global

Global mappings will be applied to all events. If your parameter names do not match the Expected Inputs provided, you will need to overwrite the Inputs provided with your own.

Output KeyDescriptionExpected Input
action_source
Required		Type: string
This field allows you to specify where your conversions occurred.		Expression: Sets action_source to 'app' for iOS/Android devices; defaults to 'website' for all other device types.
event_timeType: timestamp
A Unix timestamp in seconds indicating when the actual event occurred.		N/A: Enriched Value
user_data.emType: string
Lowercase SHA256 hash of normalized email. Trim any leading and trailing
spaces. Convert all characters to lowercase.		input.context.traits.email
event_idType: string
A unique string. The event_id and event_name parameters are used to deduplicate events.		messageId
event_source_url
Required		Type: string
The browser URL where the event happened. The URL must begin with http:// or https:// and should match the verified domain.		context.page.url
user_data.client_ip_address
Required		Type: string
Do not hash. IP address.		context.ip
user_data.client_user_agent
Required		Type: string
Do not hash. User agent.		context.userAgent
user_data.external_idType: string
Anonymous 1st party cookie.		anonymousId
user_data.fbcType: string
Do not hash. Facebook click ID.		context.providers.facebookTag._fbc
user_data.fbpType: string
Do not hash. Facebook cookie.		context.providers.facebookTag._fbp
event.xdm.identityMap.FPIDType: stringanonymousId

Event Specific

The following event mappings assume that you have named your events according to the MetaRouter AJS spec. If you have implemented custom events, or event parameters do not match the Expected Inputs, you will need to overwrite the provided information your own.

page

Output KeyDescriptionExpected Input
event_nameType: string
A standard event or custom event name. Used to deduplicate events.		N/A: Enriched Value
custom_data.content_categoryType: string
The category of the content associated with the event.		properties.category
custom_data.content_nameType: string
The name of the page or product associated with the event.		properties.name

products_searched

Output KeyDescriptionExpected Input
event_nameType: string
A standard event or custom event name. Used to deduplicate events.		N/A: Enriched Value
customer_data.search_stringType: string
Use only with Search events. A search query made by a user.		properties.query

product_viewed

Output KeyDescriptionExpected Input
event_nameType: string
A standard event or custom event name. Used to deduplicate events.		N/A: Enriched Value
custom_data.content_typeType: string
Should be set to product or product_group.		N/A: Enriched Value
custom_data.content_categoryType: string
The category of the content associated with the event.		properties.category
custom_data.content_nameType: string
The name of the page or product associated with the event.		properties.name
custom_data.content_idsType: array of integers or strings
The content IDs associated with the event, such as product SKUs for items in an AddToCart event.		properties.product_id
custom_data.currencyType: string
The currency for the value specified, if applicable. Currency must be a valid ISO 4217 three-digit currency code. Default USD.		properties.currency
custom_data.valueType: string
A numeric value associated with this event. This could be a monetary value or a value in some other metric .		properties.price
custom_data.valueType: integer or float
A numeric value associated with this event. This could be a monetary value or a value in some other metric .		properties.quantity
custom_data.contentsType: array of objects
A list of JSON objects that contain the product IDs associated with the event plus information about the products.		properties.product_id
custom_data.contentsType: array of objects
A list of JSON objects that contain the product IDs associated with the event plus information about the products.		properties.quantity
custom_data.contentsType: string
A list of JSON objects that contain the product IDs associated with the event plus information about the products.		properties.price

product_list_viewed

Output KeyDescriptionExpected Input
event_nameType: string
A standard event or custom event name. Used to deduplicate events.		N/A: Enriched Value
custom_data.content_typeType: string
Should be set to product or product_group.		N/A: Enriched Value
custom_data.content_categoryType: string
The category of the content associated with the event.		properties.category
custom_data.content_nameType: string
The name of the page or product associated with the event.		properties.name
custom_data.content_idsType: array of integers or strings
The content IDs associated with the event, such as product SKUs for items in an AddToCart event.		properties.product_id
custom_data.currencyType: string
The currency for the value specified, if applicable. Currency must be a valid ISO 4217 three-digit currency code. Default USD.		properties.currency
custom_data.valueType: integer or float
A numeric value associated with this event. This could be a monetary value or a value in some other metric .		properties.products
custom_data.valueType: string
A numeric value associated with this event. This could be a monetary value or a value in some other metric .		properties.price
custom_data.valueType: integer or float
A numeric value associated with this event. This could be a monetary value or a value in some other metric .		properties.quantity
custom_data.contentsType: array of objects
A list of JSON objects that contain the product IDs associated with the event plus information about the products.		properties.product_id
custom_data.contentsType: integer or float
A list of JSON objects that contain the product IDs associated with the event plus information about the products.		properties.quantity
custom_data.contentsType: string
A list of JSON objects that contain the product IDs associated with the event plus information about the products.		properties.price

product_added

Output KeyDescriptionExpected Input
event_nameType: string
A standard event or custom event name. Used to deduplicate events.		N/A: Enriched Value
custom_data.content_typeType: string
Should be set to product or product_group.		N/A: Enriched Value
custom_data.content_categoryType: string
The category of the content associated with the event.		properties.category
custom_data.content_nameType: string
The name of the page or product associated with the event.		properties.name
custom_data.content_idsType: array of integers or strings
The content IDs associated with the event, such as product SKUs for items in an AddToCart event.		properties.product_id
custom_data.currencyType: string
The currency for the value specified, if applicable. Currency must be a valid ISO 4217 three-digit currency code. Default USD.		properties.currency
custom_data.valueType: string
A numeric value associated with this event. This could be a monetary value or a value in some other metric ._		properties.price
custom_data.valueType: integer or float
A numeric value associated with this event. This could be a monetary value or a value in some other metric .		properties.quantity
custom_data.contentsType: array of objects
A list of JSON objects that contain the product IDs associated with the event plus information about the products.		properties.product_id
custom_data.contentsType: integer or float
A list of JSON objects that contain the product IDs associated with the event plus information about the products.		properties.quantity
custom_data.contentsType: string
A list of JSON objects that contain the product IDs associated with the event plus information about the products.		properties.price

cart_viewed

Output KeyDescriptionExpected Input
event_nameType: string
A standard event or custom event name.		N/A: Enriched Value
custom_data.content_typeType: string
Should be set to product or product_group.		N/A: Enriched Value
custom_data.content_idsType: array of integers or strings
The content IDs associated with the event, such as product SKUs for items in an AddToCart event.		properties.products
custom_data.currencyType: string
The currency for the value specified, if applicable. Currency must be a valid ISO 4217 three-digit currency code. Default USD.		properties.currency
custom_data.valueType: string
A numeric value associated with this event. This could be a monetary value or a value in some other metric .		properties.price
custom_data.valueType: integer or float
A numeric value associated with this event. This could be a monetary value or a value in some other metric .		input.properties.quantity
custom_data.contentsType: array of objects
A list of JSON objects that contain the product IDs associated with the event plus information about the products.		properties.products

product_added_to_wishlist

Output KeyDescriptionExpected Input
event_nameString: Facebook standard event name.Enrichment – Static value "AddToWishlist"
custom_data.content_categoryString: Product category.properties.category
custom_data.content_nameString: Product name.properties.name
custom_data.content_idsString: ID of the product added to wishlist.properties.product_id
custom_data.currencyString: ISO currency code (e.g., "USD").properties.currency (uppercase, defaults to "USD")
custom_data.valueFloat: Total value of the wishlisted item(s).Expression – price * quantity
custom_data.contentsArray: Array of product objects with id, quantity, and item_price.Derived from input.properties

checkout_started

Output KeyDescriptionExpected Input
event_nameString: Facebook standard event name.Enrichment – Static value "InitiateCheckout"
custom_data.content_idsArray: List of product IDs being purchased.Plucked from properties.products[].product_id
custom_data.currencyString: ISO currency code.properties.currency (uppercase, defaults to "USD")
custom_data.valueFloat: Total order value.Expression – Sum of price * quantity
custom_data.num_itemsInteger: Number of items in the checkout.Expression – Sum of quantity from all products
custom_data.contentsArray: List of product objects with id, quantity, and item_price.Derived from input.properties.products
custom_data.order_idString: Unique order ID.properties.order_id

payment_info_entered

Output KeyDescriptionExpected Input
event_nameString: Facebook standard event name.Enrichment – Static value "AddPaymentInfo"
custom_data.order_idString: Unique ID associated with the order.properties.order_id
custom_data.content_idsArray: List of related checkout and order identifiers.Expression – Combines checkout_id and order_id into an array

order_completed

Output KeyDescriptionExpected Input
event_nameType: string
A standard event or custom event name.		N/A: Enriched Value
custom_data.content_typeType: string
Should be set to product or product_group.		N/A: Enriched Value
custom_data.content_idsType: array of integers or strings
The content IDs associated with the event, such as product SKUs for items in an AddToCart event.		properties.product_id
custom_data.currencyType: string
The currency for the value specified, if applicable. Currency must be a valid ISO 4217 three-digit currency code. Default USD.		properties.currency
custom_data.valueType: string
A numeric value associated with this event. This could be a monetary value or a value in some other metric .		properties.price
custom_data.valueType: integer or float
A numeric value associated with this event. This could be a monetary value or a value in some other metric .		input.properties.quantity
custom_data.contentsType: array of objects
A list of JSON objects that contain the product IDs associated with the event plus information about the products.		properties.product_id
custom_data.contentsType: integer or float
A list of JSON objects that contain the product IDs associated with the event plus information about the products.		properties.quantity
custom_data.contentsType: string
A list of JSON objects that contain the product IDs associated with the event plus information about the products.		properties.price
custom_data.order_idType: string
The order ID for this transaction as a string.		properties.order_id

Required & Recommended Identifiers

These identifiers must be mapped to Facebook in order for successful user matching to occur. Without these IDs, any events sent to Facebook Conversions API will be rejected. For your convenience, required and recommended IDs are mapped as Global parameters to ensure they are added to every event.

AttributeExampleSync Injector Required?
client_user_agent*
Required		Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101 Firefox/42.0No
client_ip_address**
Required		IPV4: 168.212.226.204
IPV6: 2001:0db8:85a3:0000:0000:8a2e:0370:7334		No
external_id
Recommended		402DA762-201E-42C1-961B-C1fA6CBCF566 Yes
fbc
Recommended		fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890Yes
fbp
Recommended		fb.1.1596403881668.1116446470Yes

*Required for web events

**IP Address should be sent if state & country is not available to "limit data use" for persons in California

Additional Identifiers

These identifiers should be mapped to Facebook whenever possible to ensure the highest user match rates possible. If using these identifiers, they must be added as Global or Event Specific mappings.

AttributeDescriptionExample
emLowercase SHA256 hash of normalized email. Trim any leading and trailing spaces. Convert all characters to lowercase.Before hashing: [email protected]
After hashing: 542d240129883c019e106e3b1b2d3f3cb3537c43c425364de8e951d5a3083345
phHashing required. Remove symbols, letters, and any leading zeros. Phone numbers must include a country code to be used for matching.Before normalisation: +44 844 412 4653
After normalisation: 448444124653
After SHA-256 hash:
dc008fda46e2e64002cf2f82a4906236282d431c4f75e5b60bfe79fc48546383
fnFirst name hashed in SHA256 format. Using Roman alphabet a-z characters is recommended. Lowercase only with no punctuation. If using special characters, the text must be encoded in UTF-8 format.Before normalisation: Jerry
After normalisation: jerry
After SHA-256 hash: 3a5a2512949399115565867a73a413ec6ba215c8f2df385f78b33238a6639b7c
lnLast name hashed in SHA256 format. Using Roman alphabet a-z characters is recommended. Lowercase only with no punctuation. If using special characters, the text must be encoded in UTF-8 format.Before normalisation: Seinfeld
After normalisation: seinfeld
After SHA-256 hash: 0c957e9f09a2444a8868737bf42b16f40d4e3533b57dc31a61124c2cd1bae31b
ctCity hashed in SHA256 format. Using Roman alphabet a-z characters is recommended. Lowercase only with no punctuation, no special characters, and no spaces. If using special characters, the text must be encoded in UTF-8 format.Before normalisation: Beverly Hills
After normalisation: beverlyhills
After SHA-256 hash: 6195198aeec54576f52474bf92cb02ec1c5e117d1dd9ddbceb08f5bfc545a0b8
stState hashed in SHA256 format. Use the 2-character ANSI abbreviation code in lowercase. Normalize states outside the U.S. in lowercase with no punctuation, no special characters, and no spaces.Before normalisation: California
After normalisation: ca
After SHA-256 hash: 6959097001d10501ac7d54c0bdb8db61420f658f2922cc26e46d536119a31126
zpZip Code hashed in SHA256 format. Use lowercase with no spaces and no dash. Use only the first 5 digits for U.S. zip codes. Use the area, district, and sector format for the UK.Before normalisation: 90210-1002
After normalisation: 90210
After SHA-256 hash: b83c588da0c6931625f42e0948054a3ade722bfd02c27816305742ed7390ac6c
dbDate of Birth hashed in SHA256 format. MetaRouter accepts the YYYYMMDD format accommodating a range of month, day and year combinations, with or without punctuation.Before normalisation: 4/29/1954
After normalisation: 19540429
After SHA-256 hash: 8704e3f1c5795aacf516e43c24a3914d657be55c2d643523fdb233a9d094237c
geGender hashed in SHA256 format. We accept gender in the form of an initial in lowercase.Before normalisation: MALE
After normalisation: m
After SHA-256 hash: 62c66a7a5dd70c3146618063c344e531e6d4b59e379808443ce962b3abd63c5a
countryCountry hashed in SHA256 format. Use the lowercase, 2-letter country codes in ISO 3166-1 alpha-2. Always include your customers' countries’ even if all of your country codes are from the same country.Before normalisation: United States
After normalisation: us
After SHA-256 hash: 79adb2a2fce5c6ba215fe5f27f532d4e7edbac4b6a5e09e1ef3a08084a904621
anon_idDo not hash. Your install ID. This field represents unique application installation instances.Firebase Installation ID or FID for Android or IDFV for iOS
madidDo not hash. Your mobile advertiser ID, the advertising ID from an Android device or the Advertising Identifier (IDFA) from an Apple device.GAID for Android: 385c7219-aceb-4f78-8946-738b568e0590
IDFA for iOS: 6D92078A-8246-4BA4-AE5B-76104861E7DC

Additional Facebook Conversions API Documentation

https://developers.facebook.com/docs/marketing-api/conversions-api/best-practices/
https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/customer-information-parameters
https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/server-event#event-id

Integration Change Log

Updated 3 days ago