Facebook Audiences Connector Setup Guide

API Information

This connector uses the following vendor API:

• API Name: Facebook Graph API - Marketing API
• API Version: v20.0
• API Endpoint: https://graph.facebook.com
• Documentation: FaceBook Marketing API

Batch Limits

This connector 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: 10000
• Max time since oldest request: 10 minutes
• Max size of requests: 1 MB

Connector Actions

Action Name	AudienceStream	EventStream
Add User to Custom Audience	✓	✗
Remove User from Custom Audience	✓	✗
Opt Out User from All Custom Audiences	✓	✗

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:

• Ad Account ID
  • Required
  • Facebook Audiences Account ID you want to manage. (Learn more.)
  • Before you can use this connector and build a custom audience in Facebook, you must agree to the Facebook Custom Audience Terms.
  • This connection will generally expire within 60 days, causing unpredictable results for all Facebook Ad actions.
  • Reestablish the connection at any point by clicking Establish Connection/Connected.

Before clicking the Establish Connection button, ensure that you are signed into Facebook with the account that is linked with the Ad Account ID that is being used. If this is not the case issues, can arise with the token that is generated.

Settings specific to the Facebook Audiences Connector

• Facebook App ID (Required)
  The ID of the Facebook App you want to connect to.

  • Request Ads Management Standard Access to get more resources such as a better rate limit.
    For more information, see: Facebook Marketing API: Access and Authentication.
  • Make sure to request ads_management permission for for Ads Management.
    For more information, see: Facebook Login: Permissions Reference.

• Facebook App Secret (Required)

  • App Secret for the Facebook App you want to connect to, which can be found in Facebook app > Settings > Basic.

Action Settings - Parameters and Options

Click Next or go to the Actions tab. This is where you configure connector actions.

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

Action - Add User to Custom Audience

Parameters

Parameter	Description
Custom Audience to Add User To	Required. Select your Target Custom Audience. Audiences created from customer files are not displayed. Before you can use this connector and build a custom audience in Facebook, you must agree to the Facebook Custom Audience Terms.
Email Address	Identify a user based on their email address.
Phone Number	Identify a user based on their phone number. Include only digits with country code, area code, and number. For example, 16505551212.
Facebook User ID	Identify a user based on their Facebook ID. You must provide the “Facebook App ID” corresponding to the Facebook User ID (UID) when using this identifier type.
Facebook App ID	Required if the “Facebook User ID” is used as the user identifier. See “Facebook User ID”.
Mobile Advertiser ID	Use this to target a user based on the app user ID, Apple’s Advertising Identifier (IDFA), or Android’s advertising ID.
External ID	Do not hash. Any unique ID from the advertiser, such as loyalty membership IDs, user IDs, and external cookie IDs.
Zip Code	Postal code. Exact format depends on country.
City	User City. Lowercase. No punctuation or spaces.
Country	User Country. 2-letter country code. ISO 3166-1 Alpha-2 format.
US State	User State in the United States. Lowercase. 2-character ANSI abbreviation code.
First Name	User first name. Lowercase. No punctuation or special characters. UTF-8 format.
Last Name	User last name. Lowercase. No punctuation or special characters. UTF-8 format.
First Initial	First initial of user. Lowercase. No punctuation or special characters. UTF-8 format.
Year of Birth	Year of birth for user. YYYY format. Values from 1900 to current year.
Day of Birth	Day of birth for user. DD format. Values from 01 to 31.
Month of Birth	Birth month for user. MM format. Values from 01 to 12.
Gender	Gender of user. M for male, F for female
Lookalike Value	An arbitrary, numeric value for each user set when you create a seed custom audience from CRM data. Facebook uses this to determine which users in audience are worth the most to you, in a quantifiable way.
Check Box	Check this box if the Target User Identifier is already hashed. Facebook only accepts the SHA256 hashing method.

Action - Remove User from Custom Audience

Parameters

Parameter	Description
Custom Audience to Remove User From	Required. Select your Target Custom Audience. Before you can use this connector and build a custom audience in Facebook, you must agree to the Facebook Custom Audience Terms.
Email Address	Identify a user based on their email address.
Phone Number	Identify a user based on their phone number. Include only digits with country code, area code, and number. For example, 16505551212.
Facebook User ID	Identify a user based on their Facebook ID. You must provide the “Facebook App ID” corresponding to the Facebook User ID (UID) when using this identifier type.
Facebook App ID	Required if the “Facebook User ID” is used as the user identifier. See “Facebook User ID”.
Mobile Advertiser ID	Use this to target a user based on the app user ID, Apple’s Advertising Identifier (IDFA), or Android’s advertising ID.
External ID	Do not hash. Any unique ID from the advertiser, such as loyalty membership IDs, user IDs, and external cookie IDs.
Zip Code	Postal code. Exact format depends on country.
City	User City. Lowercase. No punctuation or spaces.
Country	User Country. 2-letter country code. ISO 3166-1 Alpha-2 format.
US State	User State in the United States. Lowercase. 2-character ANSI abbreviation code.
First Name	User first name. Lowercase. No punctuation or special characters. UTF-8 format.
Last Name	User last name. Lowercase. No punctuation or special characters. UTF-8 format.
First Initial	First initial of user. Lowercase. No punctuation or special characters. UTF-8 format.
Year of Birth	Year of birth for user. YYYY format. Values from 1900 to current year.
Day of Birth	Day of birth for user. DD format. Values from 01 to 31.
Month of Birth	Birth month for user. MM format. Values from 01 to 12.
Gender	Gender of user. M for male, F for female
Lookalike Value	An arbitrary, numeric value for each user set when you create a seed custom audience from CRM data. Facebook uses this to determine which users in audience are worth the most to you, in a quantifiable way.
Check Box	Check this box if the Target User Identifier is already hashed. Facebook only accepts the SHA256 hashing method.

Action - Opt Out User from All Custom Audiences

Parameters

Parameter	Description
Email Address	Identify a user based on their email address.
Phone Number	Identify a user based on their phone number. Include only digits with country code, area code, and number. For example, 16505551212.
Facebook User ID	Identify a user based on their Facebook ID. You must provide the “Facebook App ID” corresponding to the Facebook User ID (UID) when using this identifier type.
Facebook App Id	Required if the “Facebook User ID” is used as the user identifier See “Facebook User ID”.
Mobile Advertiser ID	Use this to target a user based on the app user ID, Apple’s Advertising Identifier (IDFA), or Android’s advertising ID.
External ID	Do not hash. Any unique ID from the advertiser, such as loyalty membership IDs, user IDs, and external cookie IDs.
Zip Code	Postal code. Exact format depends on country.
City	User City. Lowercase. No punctuation or spaces.
Country	User Country. 2-letter country code. ISO 3166-1 Alpha-2 format.
US State	User State in the United States. Lowercase. 2-character ANSI abbreviation code.
First Name	User first name. Lowercase. No punctuation or special characters. UTF-8 format.
Last Name	User last name. Lowercase. No punctuation or special characters. UTF-8 format.
First Initial	First initial of user. Lowercase. No punctuation or special characters. UTF-8 format.
Year of birth	Year of birth for user. YYYY format. Values from 1900 to current year.
Day of birth	Day of birth for user. DD format. Values from 01 to 31.
Month of Birth	Birth month for user. MM format. Values from 01 to 12.
Gender	Gender of user. M for male, F for female
Lookalike Value	An arbitrary, numeric value for each user set when you create a seed custom audience from CRM data. Facebook uses this to determine which users in audience are worth the most to you, in a quantifiable way.
Check Box	Check this box if the Target User Identifier is already hashed. Facebook only accepts the SHA256 hashing method.

Using the Facebook Audiences Connector

Create a Visitor ID Attribute

The Facebook Audiences connector requires at least one Visitor ID attribute with the ability to be passed through to Facebook Audiences.

Use the following resources to set up a Visitor ID attribute:

• Setting up a Visitor ID attribute
• Facebook Marketing API

Define an Audience

Your account may have several Visitor ID attributes defined. In this case, it is important to create a visitor-scoped attribute of the Boolean data type and named Known Visitor to check for the existence of any of the Visitor IDs. Using this attribute ensures that the audience only contains visitors with an assigned Visitor ID that can be passed to Facebook. You cannot target an unknown visitor.

This connector also has required ID parameters, such as email, phone, app, or user IDs. At least one of these IDs is required. Including these IDs in your audience filter helps avoid connector errors.

Use the following example to create an audience filter of visitors that have a “Known Visitor” Boolean data type set to true. You can add the badge and Boolean attributes in advance or add them when creating the filter.

Connect Tealium to Your Facebook Audiences Account

You will need the account ID to configure the connector with your Facebook Audiences account.

Use the following steps to get your Facebook Audiences account ID:

1. Log in to your Facebook Audiences account.

2. Click an ad account, campaign, ad set, or ad in Ads Manager.

3. Copy the account_id parameter value from the URL in your browser then return to the connector in AudienceStream.
   

   

4. In the Configure window, add your title and any relevant notes and your Ad Account ID (copied from above).

5. Click Establish Connection to verify the connection.

Create Custom Audience

Now that you are connected to your Facebook Audiences account, it’s time to create a Custom Audience. You will need to create your first Custom Audience on the Facebook site to accept the terms and conditions before you are able to create a Custom Audience via the connector.

Use the following steps to create a custom audience:

1. In the connector configuration, click the Create tab.
2. Enter the desired Custom Audience name and a short description.
3. Click Create.
   The customer_file_source parameter supports the following values:

• USER_PROVIDED_ONLY
• PARTNER_PROVIDED_ONLY
• BOTH_USER_AND_PARTNER_PROVIDED

On the Facebook Audiences site, you have the option to create audiences based on a customer list, website traffic, or app activity. For this example, create your audience based on a customer list.

In order to use your custom audience, it must contain a minimum of 20 entries. If your audience has been created successfully, a small check icon displays beside the button.

Specify Connector Actions

You must now specify the actions you want the connector to take.

Use the following steps to specify actions for the connector:

1. Click the Actions tab.
2. Select Add User to Custom Audience.
   

   

3. Click + Create Action.

Configure Connector Actions

Use the following steps to configure actions for the connector:

1. From the Audience menu, select the Shoe-Fans audience you created earlier.
   The Custom Audience to Add User To menu displays audiences that exist in your Facebook Audiences account.
2. From the Custom Audience to Add User To drop-down list, select the audience you want to add visitors to.
3. In the Target User Identifier drop-down list, map the visitor email attribute to the matching visitor identifier in your Facebook Audiences account.
4. Leave the WHEN set to Joined Audience.
5. Click Save.

Testing

The most effective testing method is to run a Trace to ensure that your events are handled properly and to check your Facebook dashboard to verify that your Custom Audience was created and populated.

FAQ

Why can’t I see my audiences in the AudienceStream drop-down list?

If you have more than 2,000 audiences in Facebook, they are not all selectable in the drop-down list from an AudienceStream connector.

Use the following steps in Facebook to view all audiences and select the identifier for a specific audience:

1. Log in to Facebook as the user that has access to the Facebook Audiences account.

2. Go to https://www.facebook.com/adsmanager/audiences.

3. Find the audience you are looking for and copy the Audience ID.

   If the Audience ID does not display, you can modify your table column view to include it.

   

4. Return to AudienceStream and enter the Audience ID as custom value for your AudienceStream connector.