Facebook Conversions Connector Setup Guide

Prerequisites

If you are using the Facebook Conversions connector for web events, the client-side Facebook Pixel tag must be running in the web browser. For more information, see the Facebook Help Center.

To enable the Tealium partner integration in your Facebook Ads account settings, use the following steps:

1. Log into your Facebook Ads Manager account and select Events Manager from the menu.
2. In the menu, select Data Sources, then select the Pixel and click the Settings tab.
3. Scroll down to the Server-Side API section.
4. In the Partner Integration section, click Choose a Partner.
5. Select Authorize Tealium Connection, and click Continue to enable Tealium.

If you do not see the option to toggle a partner integration, contact your Tealium Account Manager for support.

The Facebook Pixel tag automatically hashes user data. This pixel functionality cannot be changed.

API Information

This connector uses the following vendor API:

• API Name: Facebook Graph API - Facebook Pixel
• API Version: v18.0
• API Endpoint: https://graph.facebook.com

Actions

Action Name	AudienceStream	EventStream
Send Event	✓	✓
Send Advanced Measurement Event	✓	✓
Send Lead Event	✓	✓

Configuration

Navigate to the Connector Marketplace and add a new connector. For general instructions on how to add a connector, see About Connectors.

After adding the connector, configure the following settings:

• Dataset ID

  • For your Facebook Pixel to work, ensure that you have followed the steps outlined in the Facebook Server-Side Events Connector Setup Guide to enable the partner integration for your Facebook pixel.
  • For more information, see the Facebook Pixel Setup Guide.

• Test Connection

  • If your pixel has been whitelisted and enabled for Tealium, a TealiumTestConnector event is tracked on your pixel. Click Test Connection to send a test event named TealiumConnectorTest.
  • Check the Facebook Events Manager Pixel Overview to confirm the event was received.
  • If your test fails, double-check your configuration settings.

Deduplication for web events

To configure this connector to deduplicate events from the Facebook Pixel tag, use the event IDs sent in event attributes with the following naming convention:

fb_event_id_FACEBOOKEVENT_TAGID

For example: fb_event_id_Purchase_32 or fb_event_id_PageView

Event IDs were previously generated as fb_event_id_FACEBOOKEVENT. These IDs continue to be generated but are considered legacy. The new IDs allow for use with multiple Facebook tags firing on a single page and offer a stronger tie back to the related tag. If you are using the legacy version, you must change the connector to the new ID.

Use a separate action for each type of event ID. Map the event-specific event ID attribute to Event ID with the matching event name mapped to Event Name. For example:

Tealium Attribute/Value	Facebook Parameter
fb_event_id_Purchase	Event ID
“Purchase” (Custom Text)	Event Name

See the Facebook Pixel Tag Setup Guide.

Automatic deduplication

When the Automatic Deduplication value is populated, the connector looks for the corresponding event attribute. You are no longer required to add an Event ID if this section is populated and you are using Tealium iQ. However, the following approach may still be needed when using EventStream without Tealium iQ.

The connector follow this order of operations:

• If Automatic Deduplication is populated, and the value is found in the data layer, (for example, fb_event_id_ViewContent_30) this value supersedes anything mapped in Event ID.
• If Automatic Deduplication is populated, but it cannot find the tag ID version, but it can find the legacy version (with no ID attached), that value is used (for example, fb_event_id_ViewContent).
• If Automatic Deduplication is populated, but the value isn’t found, the mapped Event ID is used, if it is populated.

Offline conversions

We recommend using the Facebook Conversions connector for offline conversions instead of the Facebook Offline Conversions connector for new integrations.

To process offline and store events through the Facebook Conversions connector, set the action_source parameter to physical_store.

Actions

Click Next or click the Actions tab. You configure connector actions in the Actions tab.

This section describes how to set up parameters and options for each action.

Send Event

Parameters

For User Data parameters, the following table notes the level of importance for some parameters. The importance level describes the parameter’s influence on your event match quality. For example, Email (em) has an importance level of Highest while Phone Number (ph) has an importance level of High.

Parameter	Description
Event Source URL	The browser URL where the event happened. This parameter is required if the Action Source is set to the website. EventStream - If the Action Source is set to website and this field is not mapped, it is automatically mapped to the attribute Current URL in EventStream. AudienceStream - If the Action Source is set to website and this field is not mapped, it is automatically mapped to the Last Event URL attribute in AudienceStream.
Test Event Code	Send the test ID in the test_event_code parameter to start seeing event activity in the Test Events window. Events sent with test_event_code are not dropped, instead they flow into Events Manager and are used for targeting and ads measurement purposes.
Data Processing Options	(Required) Map this value to LDU to have Facebook process event with Limited Data Use restrictions. Otherwise map this value to None to specify that the event should not be processed with Limited Data Use restrictions. For more information, see Facebook Data Processing Options.
Event Name	(Required) A Facebook pixel standard or custom event name.
Debugging Level	Specifies the trace level for the event. 1 for Error 2 for Info 3 for Debug If you use Trace to verify hashing of data, the data shown at the top of Trace, such as user_data - EMAIL, is the data that came into the connector, not the data sent to Facebook. The data sent to Facebook is shown in the Request Body Section of Trace.
Action Source	(Required) This field specifies where your conversions occurred. Valid action sources are: email website app phone_call chat physical_store system_generated other
Dataset ID Override	This string value can be used to override the value used for the initial connector configuration. If not provided, the Dataset ID from the connector configuration is used.
Data Processing Options Country	Map the country code associated with the user event. This parameter is required if Data Processing Options is mapped to LDU. Accepted code values: 1 for the United States of America 0 to request country to be geolocated by Facebook Geolocation also requires mapping the Client IP Address attribute.
Event ID	An ID used by Facebook to de-duplicate the same event sent from both server and browser. Verify that this value is a unique ID to one pair of events sent from browser and server.
Event Time	A Unix timestamp in seconds indicating when the actual event occurred. The connector converts a mapped date attribute to seconds and, if the attribute is absent, auto-populates the event time.
Data Processing Options State	This parameter is required if Data Processing Options is mapped to LDU. Map state code associated with user event. Accepted code values: 1000 for California 0 to request state to be geolocated by Facebook Geolocation also requires also mapping the Client IP Address attribute.
Opt Out	A boolean indicating to not use this event for ads delivery optimization. Set this value to true to only use the event for attribution.
Zip (zip)	Postal zip code. For example, 94035. Importance: Medium
FB Login ID	ID issued by Facebook when a person first logs into an instance of an app. This parameter is also known as the App-Scoped ID. Do not hash this value.
Partner ID	The partner’s ID. This parameter can be used by third-party ID providers such as Liveramp and TradeDesk as an additional user identifier. Do not hash this value.
Partner Name	The partner’s name. This parameter can be used by third-party ID providers such as Liveramp and TradeDesk as an additional user identifier. Do not hash this value.
Client User Agent (ua)	This parameter is required if the Action Source is set to website. The user agent for the browser corresponding to the event. Do not hash this value. EventStream - If the Action Source is set to website and this field is not mapped, it is automatically mapped to the User Agent attribute in EventStream. AudienceStream - If the Action Source is set to website and this field is not mapped, it is automatically mapped to the visitor’s last User Agent in AudienceStream. Importance: High
Client IP Address (ip)	The IP address of the browser corresponding to the event. Tealium can capture the client IP address, but it is not available by default. To enable this feature, contact your Customer Success Manager. For more information, see Enabling IP Address Collection in Server-Side Tealium Products. Do not hash this value. Importance: High
Phone (ph)	A phone number. Include only digits with country code, area code, and number. For example, 16505551212. Importance: High
State (st)	US State abbreviation. For example, ca. Importance: Medium
Email (em)	Email address. For example, user@example.com. Importance: Highest
Last Name (ln)	Last name in lowercase. For example, smith. Importance: Medium
First Name (fn)	First name in lowercase. For example, joe. Importance: Medium
Lead ID	ID associated with a lead generated by Facebook Lead Ads. Do not hash this value.
City (ct)	City in lowercase without spaces or punctuation. For example, menlopark. Importance: Medium
Country (country)	Two-letter country code in lowercase. For example, us. Importance: Medium
External ID	Any unique ID from the advertiser, such as loyalty membership IDs, user IDs, and external cookie IDs. Map array type attributes to add multiple IDs. This mapping is automatically populated with the Tealium Visitor ID unless automapping is disabled.
Browser ID (fpb)	The browser ID value stored in Facebook’s _fbp cookie. This parameter is automapped unless you disable automapping. Do not hash this value. Importance: High
Subscription ID	The subscription ID for the user in this transaction. This is similar to the order ID for an individual product. For example, anid1234. Do not hash this value.
Gender	Lowercase single-letter value for gender. Options are: f for female m for male
Date of Birth	Date of birth given as year, month, and day. For example, 19971226 for December 26, 1997.
Click ID (fbc)	The Facebook click ID value stored in Facebook’s _fbc cookie. This parameter is automapped unless automapping is disabled. Do not hash this value. Facebook recommends storing and persisting the fbclid cookie. Importance: High
User Data is already hashed	The Facebook Conversions connector requires the Facebook Pixel tag, which automatically hashes user data. This pixel functionality cannot be changed. Select this option to avoid hashing the data again.
Currency	The currency for the value specified if applicable. Currency must be a valid ISO 4217 three-digit currency code. For example, usd.
Content Name	The name of the page or product associated with the event. For example, lettuce.
Number of Items	Use only with InitiateCheckout events. The number of items that a user tries to buy during checkout. For example, 4.
Search String	A search query made by a user. Use only with search events. For example, lettuce
Order ID	The order ID for this transaction. For example, order1234.
Content Type	This value must be either product or product_group. Set to product if the keys you send are in Content IDs or Content Product. Content Product represents products. Set to product_group if the keys you send are in Content IDs. Content Product represents product groups.
Predicted Lifetime Value	The predicted lifetime value of a conversion event. For example, 432.12.
Content IDs	The Content IDs associated with the event, such as product SKUs for items in an AddToCart event. For example, ['ABC123', 'XYZ789']. If a non-array event attribute is provided, it is converted into a single-item array. If Content Type is product, this mapped value must be a non-array event attribute or single-element array.
Value	A numeric value associated with this event. This may be a monetary value or a value in another metric. For example, 142.54.
Content Category	The category of the content associated with the event. For example, grocery.
Quantities	Product quantities.
Prices	Product individual prices.
IDs	Product IDs.
JSON Template Variables	Provide template variables as data input for templates. For more information, see Template Variables Guide. Name nested template variables with the dot notation. For example, items.name. Nested template variables are typically built from data layer list attributes.
JSON Templates	Provide valid JSON templates to be referenced in Custom Data section. Templates are injected by name with double curly braces into supported fields. For example, {{SomeTemplateName}}. For additional information, see Webhook - Send Custom Request - Trimou Templating Engine Guide.
Tealium iQ Tag ID	The Facebook Pixel Tag ID.
Disable Automapping	Disable automapping of parameters.
Automatic Deduplication	When you provide the Tealium iQ Tag ID, the connector automatically looks for the Event ID value that Tealium iQ sends.
Advertiser Tracking Enabled	Required. Use this field to specify ATT permission on an iOS 14.5+ device. Set to 0 for disabled or 1 for enabled.
Application Tracking Enabled	Required. This parameter enables ad tracking at the app level. Your SDK should allow an app developer to put an opt-out setting into their app. Use this field to specify the person’s choice. Use 0 for disabled, 1 for enabled.
App Version	Required. The Version must be a2 for Android or i2 for iOS.
OS Version	Required. OS version, for example: 13.4.1.
App Package Name	The app package name, for example: com.facebook.sdk.samples.hellofacebook.
Short Version	The short version, for example: 1.0.
Long Version	The long version, for example: 1.0 long.
Device Model Name	The device model name, for example: iPhone5,1.
Locale	The locale, for example: En_US.
Timezone Abbreviation	The timezone abbreviation, for example: PDT.
Carrier	The carrier, for example: AT&T.
Screen Width	The screen width, for example: 320.
Screen Height	The screen height, for example: 568.
Screen Density	The screen density, for example: 2.
CPU Cores	The CPU cores, for example: 2.
Storage Size (GB)	The external storage size in GB, for example: 13.
Free Storage (GB)	The free space on external storage in GB, for example: 8.
Device Timezone	The device timezone, for example: USA/New York.
Campaign IDs	An encrypted string and non-user metadata appended to the outbound URL (for example, ad_destination_url) or deep link (for App Aggregated Event Manager) when a user clicks a link from Facebook.
Install Referrer	Third party install referrer, currently available for Android only. For more information, see Campaign Measurement.
Installer Package	Used internally by the Android SDKs.
URL Schemes (Array)	Used internally by the iOS and Android SDKs.
Windows Attribution ID	Attribution token used for Windows 10.
Anon ID	Your install ID. This field represents unique application installation instances.
MADID	Your mobile advertiser ID, which is usually the advertising ID from an Android device or the Advertising Identifier (IDFA) from an Apple device.

Disable Automapping

The connector automaps the following parameters by default:

• Browser ID (fbp)
• User Agent (fbc)

To disable automapping, set Disable Automapping to true. Any automapped parameters will not be sent to the vendor.

Send Advanced Measurement Event

This Facebook action has limited availability. Contact your Facebook representative to request access. If this action has not been activated in your Facebook account, it returns errors such as “Application does not have the capability to make this API call.” or “This pixel is not authorized to report server events.”

Event Data

Parameter	Description
Event Name	(Required) A Facebook pixel standard event name.
Event Time	A Unix timestamp, in seconds, indicating when the actual event occurred. The connector will convert a mapped date attribute to seconds and will auto-populate the event time if absent.
Event Source Url	The browser URL where the event happened. Required if Action Source is set to website. If Action Source is set to website and this field is not mapped, in EventStream it will be auto-mapped to the attribute Current URL. If Action Source is set to website and this field is not mapped, in AudienceStream it will be auto-mapped to the attribute Last Event URL.
Opt Out	A flag that indicates we should not use this event for ads delivery optimization. Set this to true to use the event for attribution only.
Event ID	An ID used by Facebook to de-duplicate the same event sent from both server and browser. Verify this is an ID unique to one pair of events sent from browser and server.
Debugging Level	Set the trace level for the event. Accepted values: 1 for Error, 2 for Info, or 3 for Debug.
Test Event Code	Send the test ID as a test_event_code parameter to start seeing event activity appear in the Test Events window. Events sent with test_event_code are not dropped. They flow into Events Manager and are used for targeting and ads measurement purposes.
Pixel/Dataset ID Override	If not provided, then the Pixel ID from the connector configuration is used.

User Data

Parameter	Description
Email	Unhashed lowercase or hashed SHA-256.
First Name	A first name in lowercase.
Last Name	A last name in lowercase.
Phone	A phone number. Digits only including country code and area code: 16505554444.
Gender	Single lowercase letter, f or m, if unknown, leave blank.
Date of Birth	A date of birth given as year, month, and day: 19971226 for December 26, 1997.
City	A city in lower-case without spaces or punctuation: menlopark.
State or Province	A two-letter state code in lowercase: ca.
Zip or Postal Code	A five-digit zip code: 94035.
Country	A two-letter country code in lowercase. Example: us.
Advanced Measurement Table	The data table for Advanced Measurement API.

Custom Data

Map custom data either as plain test values or using a JSON template by referencing its name in the format: {{template_name}}.

Parameter	Description
Value	A numeric value associated with this event. This could be a monetary value or a value in some other metric: 142.54.
Currency	The currency for the value specified if applicable. Currency must be a valid ISO 4217 three digit currency code: usd.
Content Name	The name of the page or product associated with the event: lettuce.
Content Category	The category of the content associated with the event: grocery.
Content IDs	The content IDs associated with the event, such as product SKUs for items in an AddToCart event: [ABC123, XYZ789]. If a non-array event attribute is provided, it will be converted into a single-item array. If Content Type is product, this mapped value must be a non-array event attribute or single-element array.
Content Type	Must be either product or product_group. Set to product if the keys you send Content IDs: or Content Product represent products. Set to product_group if the keys you send in Content IDs: represent product groups.
Order ID	The order ID for this transaction: order1234.
Predicted Lifetime Value	The predicted lifetime value of a conversion event: 432.12.
Number of Items	Use only with InitiateCheckout events. The number of items that a user tries to buy during checkout: 4.
Search String	Use only with Search events. A search query made by a user: lettuce.
Status	Use only with CompleteRegistration events. The status of the registration event: registered.

Contents Data

Parameter	Description
IDs	Product IDs.
Quantities	Product quantities.
Prices	Product individual prices.

Automatic Deduplication

Parameter	Description
Tealium iQ Tag ID	When the Tealium iQ Tag ID is provided, we automatically look for your Event ID value that is sent from Tealium iQ.

App Data

Required for app events.

Parameter	Description
Advertiser Tracking Enabled	(Required) Use this field to specify ATT permission on an iOS 14.5+ device. Set to 0 for disabled or 1 for enabled.
Application Tracking Enabled	(Required) Users can enable ad tracking on an app level. Your SDK should allow an app developer to put an opt-out setting into their app. Use this field to specify the user’s choice. Use 0 for disabled, 1 for enabled.
App Version	(Required) The Version must be a2 for Android or i2 for iOS.
App Package Name	The app package name, for example: com.facebook.sdk.samples.hellofacebook.
Short Version	The short version, for example: 1.0.
Long Version	The long version, for example: 1.0 long.
OS Version	(Required) OS version, for example: 13.4.1.
Device Model Name	The device model name, for example: iPhone5,1.
Locale	The locale, for example: En_US.
Timezone Abbreviation	The timezone abbreviation, for example: PDT.
Carrier	The carrier, for example: AT&T.
Screen Width	The screen width, for example: 320.
Screen Height	The screen height, for example: 568.
Screen Density	The screen density, for example: 2.
CPU Cores	The CPU cores, for example: 2.
Storage Size (GB)	The external storage size in GB, for example: 13.
Free Storage (GB)	The free space on external storage in GB, for example: 8.
Device Timezone	The device timezone, for example: USA/New York.
Campaign IDs	An encrypted string and non-user metadata appended to the outbound URL (for example, ad_destination_url) or deep link (for App Aggregated Event Manager) when a user clicked on a link from Facebook.
Install Referrer	Third-party install referrer, currently available for Android only. For more information, see Google Analytics (Android) > Campaign Measurement.
Installer Package	Used internally by the Android SDKs.
Url Schemes (Array)	Used internally by the iOS and Android SDKs.
Windows Attribution ID	Attribution token used for Windows 10.

Send Lead Event

Batch Limits

This action uses batched requests to support high-volume data transfers to the vendor. For more information, see Batched Actions. Requests are queued until one of the following thresholds is met or the profile is published:

• Max number of requests: 1000
• Max time since oldest request: 10 minutes
• Max size of requests: 1 MB

Parameters

Parameter	Description
Lead ID	(Required) The Facebook-generated 15 or 16 digit leadgen_id from your downloaded leads. This number is obtained from the leadgen_id field in the lead generation webhook and included in the user_data parameter.
Event Name	(Required) Capture the lead stages you use in your CRM. The event_name parameter indicates a lead moving through the sales funnel in your CRM. Make sure to send all stages as they are updated, including the raw lead.
Event Time	A Unix timestamp in seconds indicating when the lead stage update event is updated by your CRM. The timestamp must occur after the lead generation time or the event may be discarded. If this field is not mapped, it is initialized with the current timestamp.
Test Event Code	Verify that your server events are received correctly by Facebook by using the Test Events feature in Events Manager. To find the tool, navigate to Events Manager > Data Sources > Your Pixel > Test Events.
Lead Event Source	The name of the CRM where the events are coming from.

Setup

There are several options available to setup and manage the Tealium server-side API partner integration with Facebook.

• The Facebook Partner Integration Gallery
  

  

• The Pixel Settings tab through the Choose Partner button:

  

• The web signal setup flow and Server-side API guidance card:

  

Verify Events

After sending your events, verify that Facebook has received them in the overview and breakdown views:

1. Go to Business Manager > Pixels.
2. Click on the pixel corresponding to the PIXEL_ID in your POST request.

Overview Tab

In the Overview tab, change the view from All to Server to see the number of events you have successfully sent.

Breakdown Tab

The Breakdown tab displays the breakdown of successfully sent events. Dropped events do not appear in the Server Events Received column.

You can verify events within 20 minutes after sending them from your server.

Validation

For validation, use Facebook’s Payload Helper with your data parameter fields to see how to structure your payload when it’s sent to Facebook from your server. For more information, see Facebook’s Support page for troubleshooting issues.

For more information about the Conversions API, see Facebook’s Using the Conversions API.