Links

Facebook Ads

This page describes how to use Census with Facebook Ads (Audiences and Conversions).
In this guide, we will show you how to connect Facebook Ads to Census and create your first sync.

🏃‍♀️ Getting Started

Facebook Ads support two separate authentication mechanisms: OAuth and System User. We recommend using System User for the most reliable connection long term as it does not require re-authentication every 60 days.
The steps to create a Facebook System User are more complex than using OAuth, but it's the most reliable way to connect to Facebook Ads, especially if you intend to use the connection long term.
A regular system user is recommended over an admin system user. You can use an existing system user or create a new one with the following steps:
  1. 1.
    To generate a system user token, you'll first need an application. If you don't have one already, you can create one with the following steps:
    • Open your Business Manager
    • Navigate to Business Settings > Accounts > Apps
    • Click Add and then Create New App ID
    • For use case select Other
    Facebook App UseCase Screen
    New app usecase screen
    • Then for Type select Business
    New app type
    • Then fill out the relevant details and press Create App
    New app details
  2. 2.
    Now you can generate a system user for the app. Go to your Business Manager and navigate to Business Settings > Users > System Users
    Business Manager Navigation Panel
  3. 3.
    Above your list of system users click Add to create a new System User
  4. 4.
    Provide a name and role. Census does not need an Admin role, Employee is sufficient.
  5. 5.
    Once the system user is created click on Add Assets and assign the relevant Product Catalogs that you want Census to sync to. Make sure to assign full control of the catalog to the system user.
  6. 6.
    Now generate a token for the System User by pressing Generate New Token, select the relevant app you created earlier, select the relevant scopes, and then press Generate Token
    • You will need to provide at least the business_management and catalog_management scopes for Census to sync to your product catalogs
    • Make sure to select Never for token expiration so you do not need to manually reauthorize your Census connection every 60 days.
      Token Expiration & Scopes Page
  7. 7.
    Once your token is generated be sure to save it in a safe place. This is the token you must provide to Census as a credential for your connection.

Using an Existing System User

If you already have a system user you can use it by simply generating a new token with the correct permissions. Census needs the business_management and catalog_management scopes. Also be sure to assign the catalog asset to your system user so Census can sync to it.

Using OAuth

If you'd like to use OAuth, connecting to Facebook Ads is as simple as clicking the "Connect" button and following the prompts. Census will guide you through the process of authenticating with Facebook and selecting the ad accounts you'd like to sync data from.
The downside of this method is that authentication will expire every 60 days and require re-authentication. We recommend using a System User for the most reliable connection long term.

Setting Up Connection

You are now ready to set up a connection. Head to the Census Destinations page and press New Destination. From the list, select Facebook Ads.
Select the authentication method you prefer and provide your token or complete the OAuth flow. Once you hit save, you can use your destination to create new syncs.

🗄 Supported Objects and Behaviors

Object Name
Supported
Identifiers
Behaviors
Audience
✅
​External ID​
Update or Create, Mirror
Conversions (CAPI)
✅
Any unique ID
Append
Learn more about our sync behaviors on our Core Concept page.

Data Normalization

Facebook Audiences and Conversions, like many other ads destinations, don't upload raw data but instead send hashed information for "matching" to protect user PII.
Census automatically takes care of this hashing step for you.
However, all values provided to Census must be lowercase. You can use this standard SQL function LOWER()that works across all data warehouses.
SELECT
user_id,
LOWER(email_address) AS email,
'active users audience' AS fb_audience
FROM user_activity_table;
Additionally, certain fields require removing whitespaces and punctuation. For example:
  • City changing from 'San Antonio' => 'sanantonio' using replace( ,' ','')
  • Date of birth changing from '1983-12-24' => '19831224' using replace( ,'-','')
See the Facebook documentation for more information on the specific requirements for each field. And please contact us if you have any issues with this normalization.

Audiences

Audiences provide a way to group users together for targeting in Facebook Ads. This is useful for creating custom audiences for ad targeting, lookalike audiences, and more.
Here's a few things to keep in mind when syncing to Facebook Audiences:
  • You can reuse existing audiences or have Census create new ones.
  • Update or Create will add or update users to the audience, but will never remove users. Mirror will also remove users that have disappeared from the source. Note: If you're reusing an existing Facebook Audience, Census will not remove any users already added to that audience through other means. Census only removes users that it created initially.

Conversions

Send web events directly to Facebook from your warehouse, exactly as if they were pixel events using the Facebook Conversions API.
When sending conversions, you'll need to do a bit more work to ensure that the data is in the right format for Facebook. Here's a quick guide to get you started:

1. Choose or create a conversion event in Facebook, Collect the Pixel ID

To view all your Facebook Ads accounts' Pixel IDs go to the Events Manager: https://business.facebook.com/events_manager2/list/.
Be sure to select the specific ads account you want to work on. You can switch ad accounts in the navigation bar on the left side of the screen.
In the events manager, you can view all your ad account's pixels and existing events. If a custom event doesn't exist already, Census will create it for you.

2. Event ID

Census requires source data to have a column that stores a unique identifier for each row so that Census never sends any duplicate records. We call this unique identifier column "Event ID". If you have an identifier that you are already passing via your pixel on the website for online versions of this conversion event, use this identifier. Some common examples include user_id, lead_id, and order_id.

3. Minimum Event Parameters

The Facebook Conversions API requires 4 fields for every event:
  • Pixel ID - Covered above.
  • ​Action Source - This field allows you to specify where your conversions occurred. It accepts one of the following values: "email", "website", "phone_call", "chat", "physical_store", "system_generated", and "other".
  • ​Event Name - A Facebook pixel Standard Event or Custom Event name.
  • ​Event Time - can be up to 7 days before you send an event to Facebook. This date must be sent in GMT timezone.

4. Customer Information Parameters

Facebook attributes conversions back to ad campaigns by identifying the users that saw or interacted with ad content. To do so, they accept the following user identifiers and will attempt to match each conversion to a facebook user. Sending more identifiers will improve match rates.
Census also supports custom fields on Conversions, simply Create New Field when creating a Conversions sync.
For a more complete description of each identifier, please see Facebook's API documentation. When Facebook requires a field's value to be hashed, you may choose to use a pre-hashed value (if you have one), or for Census to perform the hashing for you.
  • Email
  • Phone
  • Gender
  • Date of Birth
  • Last Name
  • First Name
  • City
  • State
  • Zip
  • Country
  • External ID
  • Client IP address
  • Client user agent
  • Click ID
  • Browser ID
  • Subscription ID
  • Facebook Login ID
  • Lead ID

Sample Data Requirements

event_id
pixel_id
action_source
timestamp
event_name
email
other customer information parameters
1234
1000294785
website
2022-01-01 00:00:00+000
sample_event

🆘 Common Errors

Sometimes error messages can be a little cryptic. Here's some Facebook errors that pop up on occasion and what they mean.

Authentication errors when syncing Custom Audiences:

Custom Audience terms have not been accepted: Accept the Custom Audience terms at [url] to create or edit an audience with an uploaded customer list.
In order to get around this error, the user that does the authentication to Census should be the same user that accepts the policy updates. For example, you may have a "Business" account on Facebook, but to authenticate to Census you might use personal Facebook accounts that are "attached" to the business account. The corresponding personal account would need to accept the policy. If you are unsure if your team has already accepted the terms and conditions, you can make a GET call to see if your account has signed the terms and conditions. The API call is: GET act_<AD_ACCOUNT_ID>?fields=tos_accepted A sample response would be something like this:
{
"tos_accepted": {
"custom_audience_tos": 1 // this means the terms were signed
},
"id": "act_<AD_ACCOUNT>"
}

🚑 Need help connecting to Facebook?

​Contact us via [email protected] or start a conversation with us via the in-app chat.