Send your event data from RudderStack to Facebook Custom Audience.
8 minute read
RudderStack lets you send your customer events for creating custom audiences by leveraging the Facebook Marketing API.
Find the open source transformer code for this destination in the GitHub repository.
The user information in your events may include email, phone number, gender, etc. See the Facebook documentation for more information on the supported fields.
Getting started
In your RudderStack dashboard, go to Directory > Destinations > Cloud Destinations and search for Facebook Custom Audience.
Connection settings
To add Facebook Custom Audience as a destination in RudderStack, you will need to configure the following settings:
Access Token: Enter the access token of your business application set up for accessing the Facebook Marketing API.
Audience Batch Size: Specify the data size you want RudderStack to send to Facebook in a single event. For example, if you want to send a total 1000 user records to Facebook and set the batch size to 50, then RudderStack will send 20 events to Facebook with 50 user records in each event.
Schema Fields Choose your schema fields (at least one) from the available options. This is a mandatory field. RudderStack expects the user events to consist of every schema field that has been chosen in the dashboard.
RudderStack ignores any user information which does not adhere to the schema fields specified in the dashboard settings.
Enable Hashing: Enabled by default, this option lets RudderStack hash encode the user data irrespective of the schema type chosen in the RudderStack dashboard. Facebook expects the user data to be hash encoded using SHA256.
Is The Data Raw: As RudderStack does not support combinational schema fields, this field is ignored if not enabled.
It is highly recommended not to exceed the batch size of 100.
Disable Formatting: Enable this option to not format the user data before sending it to Custom Audience. Facebook has fixed data formats for all the allowed schema fields. See the Explicit formatting feature section for more information.
Type: Specify the type of the custom audience.
Sub Type: Specify the sub-type of the custom audience.
The following table details the mapping of the schema fields specified in the RudderStack dashboard and the Facebook Marketing API.
Dashboard Field Name
Marketing API Schema Field (RudderStack Supported Field Name)
Guidelines
EMAIL
EMAIL
Trim any leading or trailing whitespaces and convert all the characters to lower case.
PHONE
PHONE
Remove symbols, letters, and any leading zeroes. The country code is needed as a prefix, if the COUNTRY field is not specified in the dashboard.
GENDER
GEN
Use these values: m or male for male and f or female for female.
MADID
MADID
Use lowercase and keep the hyphens. This information will not be hashed.
EXTERN_ID
EXTERN_ID
This information will not be hashed.
DOB YEAR (YYYY)
DOBY
Use the YYYY format from 1900 to the current year.
DOB MONTH (MM)
DOBM
Use the MM format from 01 to 12.
DOB DATE (DD)
DOBD
Use the DD format from 01 to 31.
LAST NAME
LN
Use a-z only. Lower case only, no punctuation. Use special characters in the UTF-8 format.
FIRST NAME
FN
Use a-z only. Lower case only, no punctuation. Use special characters in the UTF-8 format.
FIRST NAME INITIAL
FI
Use a-z only. Lower case only. Use special characters in the UTF-8 format.
CITY
CT
Use a-z only. Lower case only, with no punctuation, no special characters, and no whitespace.
US STATES
ST
Use the 2-character ANSI abbreviation code in lower case. Normalize the states outside the US in lowercase, with no punctuation, no special characters, and no white space.
ZIP
ZIP
Use lower case and no white space. For the US, use only the first 5 digits. For the UK, use the Area/District/Sector format.
COUNTRY
COUNTRY
Use lower case, 2-letter ISO 3166-1 alpha-2 country codes.
RudderStack modifies the schema names visible in the dashboard to ensure better readability. However, during the event call, the field names must be exactly the same as the schema names specified by Facebook Marketing API, as mentioned in the table above.
Explicit formatting feature
If your turn on the Disable Formatting option in the RudderStack dashboard, RudderStack will not format the user data in the format prescribed by the Facebook Marketing API. Otherwise, RudderStack formats the schema fields input by the user as shown in the table below:
Schema Field Name
Example Input
Formatted Output (Before Hashing)
EMAIL
ABC@gmail.com
abc@gmail.com
PHONE
0@96346895
96346895
GEN
FEMALE
f
DOBD
2
02
DOBM
1
01
LN & FN
Abc,@
abc@
FI
Mr.
mr.
CT
HN#
hn
ST
? AL ?
al
ZIP
11502 @bc
11502@bc
COUNTRY
IN
in
The following code snippet shows a record event with the schema fields (EMAIL and FIRST NAME) specified in the RudderStack dashboard:
Hover over Create Audience and select Custom Audience.
Select Customer List and click Next.
Prepare your customer list by selecting and mapping the identifiers. Make sure you have enough identifiers before uploading the list.
Upload the CSV file you want to use for your new custom audience. Under the Does your list include a column for customer value? setting, make sure to select No, continue with a customer list that doesn’t include customer value.
You can also download the file template CSV and upload it.
Finally, click Import and create to create the audience.
The custom audience you create should have edit permissions. Otherwise, RudderStack will not be able to add or remove users from the list.
How do I check if the custom audience has edit permissions?
To check if the audience has edit permissions enabled, go to the Audiences tab, select your custom audience, and check the Actions dropdown. You should see the Edit option as seen below:
How do I obtain the Ad Account ID?
Go to your Facebook Ads Manager account where you can find the Ad Account ID in the account’s drop-down menu:
You can click on See More Ad Accounts if the required Ad account is not visible.
Where can I find the user Access Token for the application?
To generate the user access token for your application, you must first add it as a system user asset with manage permissions.
Follow these steps to generate a user access token required to use the Facebook Marketing API:
Under the system user, click the Generate New Token button and select the app from the dropdown.
Choose the Token expiration time.
Under Available permissions, select ads_read and ads_management.
Click the Generate Token button and copy the token credentials.
Should I use sessionIdAdd or sessionIdDelete before adding or removing users in Custom Audience?
sessionIdAdd and sessionIdDelete helps you track and use a particular session ID while adding or removing users. This is useful when you are sending data in chunks. If you do not include these fields, Facebook creates a session ID itself.
This site uses cookies to improve your experience while you navigate through the website. Out of
these
cookies, the cookies that are categorized as necessary are stored on your browser as they are as
essential
for the working of basic functionalities of the website. We also use third-party cookies that
help
us
analyze and understand how you use this website. These cookies will be stored in your browser
only
with
your
consent. You also have the option to opt-out of these cookies. But opting out of some of these
cookies
may
have an effect on your browsing experience.
Necessary
Always Enabled
Necessary cookies are absolutely essential for the website to function properly. This
category only includes cookies that ensures basic functionalities and security
features of the website. These cookies do not store any personal information.
This site uses cookies to improve your experience. If you want to
learn more about cookies and why we use them, visit our cookie
policy. We'll assume you're ok with this, but you can opt-out if you wish Cookie Settings.