You can write job results in Treasure Data directly to your Facebook Custom Audience.

When you upload or create a Custom Audience, Facebook requires that you accept Custom Audience Terms. You see a notification when you export an ad object targeting a customer file or export value-based Custom Audiences. You receive subsequent reminders about Facebook Custom Audience terms every 90 days. For more information, see Better Facebook Ads ROI with Data-Driven Custom Audiences.

For sample workflows on how to write job results to Facebook Custom Audience, view Treasure Boxes.

Prerequisites

• Basic knowledge of Treasure Data, including the TD Toolbelt.

• A Facebook Ad Account.

• Authorized Treasure Data Facebook app access to a Facebook Ad Account

• Optionally, Access Token and App Secret

Obtain or Generate an Access Token 

This section is optional if you use OAuth authentication.

1. Before generating an access token,  create a user from Facebook Business Manager.
2. Enter Facebook Business Manager.
3. Navigate to Generate New Token.
4. Follow the prompts.

The following permissions are needed with the token.
public_profile,email,ads_management,ads_read,pages_manage_ads,pages_manage_metadata,pages_read_engagement,pages_read_user_content,read_insights

Using an Alternate to Generating an Access Token

If you are not able to generate an access token to connect to Facebook, review Meta - Publisher Steps in Business Manager.

Supported Facebook Data Normalization and Hashing Requirement

Before sending data to Facebook, the data must be hashed with SHA256 with no salt (is random data that is used as an additional input to a one-way function that hashes data). This requirement applies to all data except External Identifiers, App User IDs, and Page Scoped User IDs.

If you choose to prepare your data (normalization and hashing) before sending it to the connector, you can set the option No need to normalize and hash records to True.

Treasure Data result output normalizes your values automatically according to Facebook’s normalizing rules.

All values, uploaded to Facebook for matching, must be normalized using the normalizing rules of Facebook. Otherwise, the values miss chances to match (if they are not normalized). If you need to normalize the data manually, apply your own normalization before attempting to generate output results.

According to the data type, the following conversion behavior is applied while creating the resulting output.

Use the TD Console to Create Your Connection

Create a New Connection

In Treasure Data, you must create and configure the data connection prior to running your query. As part of the data connection, you provide authentication to access the integration.

Define your Query

The column name is case-insensitive, ie. you can use email or EMAIL.

Supported Column Naming

Column names are case-insensitive. For example, you can use email or EMAIL.

Output results need to follow the Facebook User schema. Supported column names are:

• EXTERN_ID: External ID

• MADID: Mobile advertiser ID

• EMAIL: Email addresses

• PHONE: Phone numbers

• GEN: Gender

• DOBY: Birth Year

• DOBM: Birth Month

• DOBD: Birthday

• LN: Last Name

• FN: First Name

• FI: First Initial

• CT: City

• ST: States

• ZIP: Zip code

• COUNTRY: Country code

• PAGEUID: Page scope user id

• LOOKALIKE_VALUE: value for value-based Custom Audience

If no supporting columns are found from the query result, you receive an error.

Integration Parameters for Facebook Custom Audiences

Example Query

You can use an alias in your query to rename columns of your query result. For example:

SELECT an_email_column AS EMAIL,
another_phone_column AS PHONE
FROM your_table;

Here is an example Audiences list before the output of a query result:

From Treasure Data, run the following query with Output results into a connection of Facebook Custom Audience:

SELECT email, fn, ln FROM (
  VALUES ('demo1@example.com', 'John', 'Doe'),
         ('demo2@example.com', 'Isaac', 'Miceli'),
         ('demo3@example.com', 'Christopher', 'Agar')
)  tbl (email, fn, ln)

or for Page scope user ID

SELECT 
  pageuid
FROM (
  VALUES('2018728488162687') ,
        ('1785406501565085') ,
        ('2341287802551031') ,
        ('2487019361340533') ,
        ('1093039407464499')
  ) tbl (pageuid)

The query will not match any real users, it’s for demo purposes only. Also, the query requires no source table (for the ease of testing out this feature), but you still must choose a database, so pick “sample_datasets” or any other arbitrary table. Uploading Page scope user ID requires Page ID, for example, Page ID: 136400506505739

The query should complete in a few seconds. After that, check your Audience List:

Optionally Schedule the Query Export Jobs

You can use Scheduled Jobs with Result Export to periodically write the output result to a target destination that you specify.

 *    *    *    *    *
 -    -    -    -    -
 |    |    |    |    |
 |    |    |    |    +----- day of week (0 - 6) (Sunday=0)
 |    |    |    +---------- month (1 - 12)
 |    |    +--------------- day of month (1 - 31)
 |    +-------------------- hour (0 - 23)
 +------------------------- min (0 - 59)

Optionally Configure Export Results in Workflow

Within Treasure Workflow, you can specify the use of this data connector to export data.

Learn more at Using Workflows to Export Data with the TD Toolbelt.

Edit Ad Placement

After you output your user list into an Instagram Custom Audience,

1. Open Facebook/Instagram Ads Manager to edit the ad placement. By default, Facebook will choose to display within Instagram Ads.
2. Automatic Placements (default):
3. Edit Placement:

Troubleshooting an Add Ad Account to Business Manager Error Message

If you see the following error:

This ad account is not connected to Business Manager. To create or edit a customer file Custom Audience, your admin needs to connect this ad account to a business account.

You must add your Ad Account to a Business Manager account.

Follow these steps:

1. Create Business Manager account: https://www.facebook.com/business/help/1710077379203657

2. Add Ad Account: https://www.facebook.com/business/help/910137316041095

   

   
   

Select one of the following: