Facebook Custom Audience

Step-by-step guide to send event data from RudderStack to Facebook Custom Audience.

Facebook Custom Audience is a popular targeting tool that lets you find people on Facebook interested in your business. It lets you create custom audiences through customer lists, Facebook engagement, and website/app traffic.

RudderStack lets you send your customer events for creating custom audiences by leveraging the Facebook Marketing API.

You can now send your customer events data list directly for adding them to already created Facebook Custom Audience through RudderStack.

The user information in your events may include email, phone number, gender, etc. For more information on the supported fields, refer the documentation here.

Find the open-source transformer code for this destination in our GitHub repo.

Getting Started

To enable sending your event data to Facebook Custom Audience, you will first need to add it as a destination in RudderStack.Once the destination is configured and enabled, events from RudderStack will start flowing to Custom Audience.

Before configuring Facebook Custom Audience as a destination, verify if the source platform supports sending events to Custom Audience by referring to the table below:

Connection Mode

Web

Mobile

Server

Device mode

-

-

-

Cloud mode

-

-

Supported

To know more about the difference between Cloud mode and Device mode in RudderStack, read the RudderStack connection modes guide.

Once you have confirmed that the platform supports sending events to Custom Audience, perform the steps below:

  • From your RudderStack dashboard, add the source. Then, select Facebook Custom Audience from the list of destinations.

Please follow our guide on How to Add a Source and Destination in RudderStack to add a source and destination in RudderStack.

  • Assign a name to the destination and click on Next. You will then see the following screen:

Facebook Custom Audience Setup

Custom Audience Connection Settings

To add 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.

Check the FAQ section for more information on how to find your User Access Token.

  • 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 on the dashboard, in the same order.

RudderStack will ignore any user information which does not adhere to the specified schema fields in the dashboard settings.

  • Map Specific Events To Audience ID: Enter the Event Name(s) you are going to use to send your user data to Rudderstack (for e.g.uploadingCustomAudience,trimmingCustomAudience etc.). Also, specify the corresponding Custom Audience ID(s) to which the audiences will be added to/removed from.

Check the FAQ section for more information on how to find your Audience ID.

You can only send track events with the event names specified in the dashboard.

  • Some other important settings are:

    • Enable Hashing: Facebook expects the user data to be hash encoded using SHA256. if this option is enabled, RudderStack will hash encode the user data irrespective of the schema type chosen in the RudderStack dashboard.

    • Disable Formatting: Facebook has fixed data formats for all the allowed schema fields. If this option is enabled, RudderStack will not format the user data before sending it to Custom Audience.

The track Event Structure to Send User Data to Custom Audience

The Facebook Custom Audience destination supports only track calls.

The userListAdd and userListDelete arrays containing the user data objects are expected inside the properties field of the track event.

  • userListAdd: Refers to the user information that needs to be added to the custom audience.

  • userListDelete: Refers to the user information that needs to be deleted from the custom audience.

A detailed description of the session fields as prescribed in the Facebook documentation is documented in the following table:

Rudderstack-supported Field Name

Marketing API Field Name

Data Type

Description

sessionIdAdd

session_id

int64

This is the advertiser-generated identifier which is used to add users to a custom audience while tracking the session. It should be unique for each ad account.

sessionIdDelete

session_id

int64

This is the advertiser-generated identifier which is used to remove users from a custom audience while tracking the session. It should be unique for each ad account.

batch_seq,batchSeq,batchSequence

batch_seq

int64

This refers to the sequence number used to identify the request in the session.

last_batch_flag,lastBatchFlag

last_batch_flag

boolean

This is set to true when sending the last request.

estimated_num_total,estimatedNumTotal

estimated_num_total

int64

Refers to the estimated total number of users to be uploaded in a particular session.

You cannot add or remove users from a custom audience using the same value for sessionIdAdd and sessionIdDelete.

For adding the session information to any user addition/deletion operation, the Facebook Marketing API expects the session_id, batch_seq, last_batch_flag fields to be present. However, note that the data addition and deletion operations are possible without explicitly specifying the session information.

Schema Fields Mapping

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)

Field Guidelines

EMAIL

EMAIL

Trim any leading or trailing whitespaces and convert all the characters to lower case.

EMAIL_SHA256

EMAIL_SHA256

In case you are already hashing your emails, they will be double-hashed and sent to Facebook if the Enable Hashing option is enabled in the RudderStack dashboard.

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.

PHONE_SHA256

PHONE_SHA256

In case you are already hashing the phone numbers, they will be double-hashed and sent to Facebook if the Enable Hashing option is enabled in the RudderStack dashboard.

GENDER

GEN

Use these values: m or male for male and f or female for female.

MOBILE ADVERTISER ID

MOBILE_ADVERTISER_ID

Use lowercase and keep the hyphens. This information will not be hashed.

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 the Disable Formatting option is enabled in the RudderStack dashboard, RudderStack will not format the user data in the format prescribed by the Facebook Marketing API. If it is disabled, 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

[email protected]

[email protected]

PHONE

[email protected]

96346895

GEN

FEMALE

f

DOBD

2

02

DOBM

1

01

LN & FN

Abc,@

[email protected]

FI

Mr.

mr.

CT

HN#

hn

ST

? AL ?

al

ZIP

11502 @bc

[email protected]

COUNTRY

IN

in

The following code snippet shows a track event with the schema fields (e.g.EMAIL,FIRST NAME) specified in the RudderStack dashboard:

import rudder_analytics
rudder_analytics.write_key = WRITE_KEY
rudder_analytics.data_plane_url = DATA_PLANE_URL
rudder_analytics.track('USER-ID', 'EVENT-NAME', {
'sessionIdAdd': 123,
'sessionIdDelete':456,
'batchSequence': 10,
'lastBatchFlag': true,
'userListAdd': [
{
'EMAIL': '[email protected]',
'FN': 'name1'
},
{
'EMAIL': '[email protected]',
'FN': 'name2'
}
],
'userListDelete': [
{
'Email': '[email protected]',
'FN': 'name3'
},
{
'Email': '[email protected]',
'FN': 'name4'
}
]
})

Facebook Custom Audience Payload Restrictions

Payload Field Name

Transformed?

Using only userListAdd

Yes

Using only userListDelete

Yes

Using both userListAdd and userListDelete

Yes

Not using both userListAdd and userListDelete

No

Not using only sessionIdAdd

Yes (RudderStack will not explicitly create a session for the add operation.)

Not using only sessionIdDelete

Yes ( Rudderstack will not explicitly create a session for the delete operation.)

Not using both sessionIdAdd and sessionIdDelete

Yes ( Rudderstack will not explicitly create sessions for both the delete and add operations.)

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.

Refer to the Facebook documentation for more information on this.

The following code snippet shows a track event having only userListAdd with the schema fields (e.g.EMAIL,FIRST NAME) specified in the RudderStack dashboard:

rudder_analytics.track('USER-ID', 'EVENT-NAME', {
sessionIdDelete: 456,
batchSequence: 10,
lastBatchFlag: true,
userListAdd: [
{
FN: 'name1',
},
{
FN: 'name2',
},
],
})

As the sessionIdAdd field is absent, the above example does not create a session explicitly but successfully adds users to Facebook Custom Audience.

Similarly, you can use userListDelete in order to remove users from a particular custom audience without creating a session.

The event payload must include userListAdd or userListDelete . Otherwise, the user data won’t be transformed and sent to Custom Audience.

FAQs

Where can I find the Custom Audience ID?**

  • To get your Custom Audience ID, go to your Facebook Ads Manager account. On the left navigation bar, select Audiences and choose the Ad account you have created the custom audience for.

  • Then, click on All Audience and select the specific custom audience from the list.

  • Finally, click on History tab. Here, you will find the audience ID under the Item Changed column, as shown:

Where can I find the user Access Token for the application?

To use the Facebook Marketing API, you need to generate a user access token. Follow these steps to generate a user access token using your Facebook Developer account:

  • Log into your Facebook Developer account.

  • If you haven't created an app already, do so with the type Business, as shown:

  • Set your app up with the Marketing API as the product, as shown:

  • Next, click on the Tools tab , followed by the View All Tools link.

  • Then, click on the Access Token Tool as shown:

  • Find your app and click on the need to grant permissions link in the User Token row. This will generate the user access token, as shown:

For more information on using this access token or generating the access token via your app, check out Facebook's developer documentation.

Should I use sessionIdAdd or sessionIdDelete before adding/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.

Refer to the Facebook documentation for more information on this.

Contact Us

If you come across any issues while configuring Facebook Custom Audience with RudderStack, feel free to contact us or start a conversation on our Slack channel.