Facebook Conversions Connector Setup Guide

This article describes how to set up the Facebook Conversions connector in your account.

Prerequisites

The Facebook Conversions connector requires the client-side Facebook Pixel tag to be running in the web browser. Learn more in the Facebook Help Center.

For the Facebook Pixel to work with the Facebook Conversions connector, enable the Tealium partner integration in your Facebook Ads account settings as follows:

  1. Log into your Facebook Ads Manager account and click 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: v12.0
  • API Endpoint: https://graph.facebook.com

Connector Actions

Action Name AudienceStream EventStream
Send Event

Configure Settings

Go to the Connector Marketplace and add a new connector. Read the Connector Overview article for general instructions on how to add a connector.

After adding the connector, configure the following settings:

  • Pixel ID

  • 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 the steps described in the Facebook Server-Side Events Connector Setup Guide.

Action Settings - Parameters and Options

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.

Deduplication for Facebook Pixel and Facebook Conversions API for Web Events

To configure this connector action to receive event IDs from the Facebook Pixel tag in your iQ Tag Management account, look for event attributes using the following naming convention:

fb_event_id_<Facebook Event>_<Tag UID>

For example: fb_event_id_Purchase_32 or fb_event_id_PageView

IDs were previously generated as fb_event_id_<Facebook Event>. 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 will look for the corresponding variable within the UDO object. 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 TealiumiQ.

The connector uses the following 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 can’t find the tag ID version, but 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 valie isn’t found, the mapped Event ID is used, if it is populated.

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
  • Optional.
  • Required if the Action Source is set to website.
  • The browser URL where the event happened.
  • 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
  • Optional.
  • 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 value to LDU to have Facebook process event with Limited Data Use restrictions.
  • Otherwise map 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 event name.
Debugging Level
  • Optional.
  • 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 allows you to specify where your conversions occurred.
  • Valid action sources are:
    • email
    • website
    • app
    • phone_call
    • chat
    • physical_store
    • system_generated
    • other
Pixel ID Override
  • Optional.
  • String
  • Can be used to override the value used for the initial connector configuration.
  • If not provided, the Pixel ID from the connector configuration is used.
Data Processing Options Country
  • Required if Data Processing Options is mapped to LDU.
  • Map the country code associated with the user event.
  • 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
  • Optional.
  • An ID used by Facebook to de-duplicate the same event sent from both server and browser.
  • Verify that this is a unique ID to one pair of events sent from browser and server.
Event Time
  • Optional.
  • A Unix timestamp in seconds indicating when the actual event occurred (auto-populated at execution time if absent).
Data Processing Options State
  • 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
  • Optional.
  • A flag indicating to not use this event for ads delivery optimization.
  • Set this to true to only use the event for attribution.
    Zip (zip)
    • Postal zip code.
    • Example: 94035.
    • Importance: Medium
    FB Login ID
    • ID issued by Facebook when a person first logs into an instance of an app.
    • This is also known as the App-Scoped ID.
    • Do not hash.
    Client User Agent (ua)
    • Optional.
    • Required if the Action Source is set to website.
    • The user agent for the browser corresponding to the event.
    • Do not hash.
    • 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)
    • Do not hash.
    • 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.
    • Importance: High
    Phone (ph)
    • A phone number.
    • Include only digits with country code, area code, and number.
    • Example: 16505551212
    • Importance: High
    State (st)
    • US State abbreviation.
    • Example: ca.
    • Importance: Medium
    Email (em)
    • Email address.
    • Example: user@example.com.
    • Importance: Highest
    Last Name (ln)
    • Last name in lowercase.
    • Example: smith.
    • Importance: Medium
    First Name (fn)
    • First name in lowercase.
    • Example: joe.
    • Importance: Medium
    Lead ID
    • ID associated with a lead generated by Facebook Lead Ads.
    • Do not hash.
    City (ct)
    • City in lower-case without spaces or punctuation.
    • Example: menlopark.
    • Importance: Medium
    Country (country)
    • Two-letter country code in lowercase.
    • Example: us.
    • Importance: Medium
    External ID
    • Do not hash.
    • Any unique ID from the advertiser, such as loyalty membership IDs, user IDs, or external cookie IDs.
    Browser ID (fpb)
    • Do not hash.
    • The browser ID value stored in Facebook’s _fbp cookie.
    • Importance: High
    Subscription ID
    • Do not hash.
    • The subscription ID for the user in this transaction.
    • This is similar to the order ID for an individual product.</li
    • Example: anid1234
    Gender
    • Lowercase.
    • Options are:
      • f for female
      • m for male
    Date of Birth
    • Date of birth given as year, month, and day.
    • Example: 19971226 for December 26, 1997.
    Click ID (fbc)
    • Do not hash.
    • The Facebook click ID value stored in Facebook’s _fbc 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.
    • Example: usd
    Content Name
    • The name of the page or product associated with the event.
    • Example: lettuce
    Number of Items
    • Use only with InitiateCheckout events.
    • The number of items that a user tries to buy during checkout.
    • Example: 4
    Search String
    • A search query made by a user.
    • Use only with Search events.
    • Example: lettuce
    Order ID
    • The order ID for this transaction.
    • Example: order1234
    Content Type
    • Must be either product or product_group.
    • Set to product if the keys you send are in Content IDs or Content Product.
    • Content Product represent 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.
    • Example: 432.12
    Content IDs
    • The Content IDs associated with the event, such as product SKUs for items in an AddToCart event.
    • 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 some other metric.
    • Example: 142.54
    Content Category
    • The category of the content associated with the event.
    • Example: grocery
    Quantities
    • Product quantities.
    Prices
    • Product individual prices.
    IDs
    • Product IDs.
    JSON Template Variables
    • Provide template variables as data input for templates.
    • See the Template Variables Guide.
    • Name nested template variables with the dot notation.
    • Example items.name.
    • Nested template variables are typically built from data layer list attributes.
    JSON Templates
    Automatic Deduplication
    • When the Tealium iQ Tag ID is provided, we will automatically look for your Event ID value that is sent from Tealium iQ.

    Setup

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

    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.
    Data Sources

    Overview Tab

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

    Overview

    Breakdown Tab

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

    Breakdown

    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 structure your payload when it’s sent to Facebook from your server. See Facebook’s Support page for troubleshooting issues.

    Learn more at Facebook’s Using the Conversions API.

    Was this page helpful?

    This page was last updated: August 11, 2022