FacebookAds

Overview

The FacebookAds class allows you to interact with parts of the Facebook Business API. Currently the connector provides methods for creating and deleting custom audiences, and for adding users to audiences.

The FacebookAds connector is a thin wrapper around the FB Business SDK, so some of that SDK is exposed, e.g., you may see exceptions like FacebookRequestError.

Facebook’s advertising and Pages systems are massive. Check out the overviews for more information:

• Facebook Business Overview

• Facebook Custom Audiences

• Facebook Marketing API

Note

Authentication

Before using FacebookAds, you’ll need the following: * A FB application, specifically the app ID and secret. See https://developers.facebook.com to find your app details or create a new app. Note that a Facebook app isn’t necessarily visible to anyone but you: it’s just needed to interact with the Facebook API. * A FB ad account. See https://business.facebook.com to find your ad accounts or create a new one. * A FB access token representing a user that has access to the relevant ad account. You can generate an access token from your app, either via the Facebook API itself, or via console at https://developers.facebook.com.

Quickstart

To instantiate the FacebookAds class, you can either store your authentication credentials as environmental variables (FB_APP_ID, FB_APP_SECRET, FB_ACCESS_TOKEN, and FB_AD_ACCOUNT_ID) or pass them in as arguments:

from parsons import FacebookAds

# First approach: Use environmental variables
fb = FacebookAds()

# Second approach: Pass credentials as argument
fb = FacebookAds(app_id='my_app_id',
                 app_secret='my_app_secret',
                 access_token='my_access_token',
                 ad_account_id='my_account_id')

You can then use various methods:

# Create audience
fb.create_custom_audience(name='audience_name', data_source='USER_PROVIDED_ONLY')

# Delete audience
fb.delete_custom_audience(audience_id='123')

API

class parsons.FacebookAds(app_id=None, app_secret=None, access_token=None, ad_account_id=None)

Instantiate the FacebookAds class

Args:

app_id: str

A Facebook app ID. Required if env var FB_APP_ID is not populated.

app_secret: str

A Facebook app secret. Required if env var FB_APP_SECRET is not populated.

access_token: str

A Facebook access token. Required if env var FB_ACCESS_TOKEN is not populated.

ad_account_id: str

A Facebook ad account ID. Required if env var FB_AD_ACCOUNT_ID isnot populated.

static get_match_table_for_users_table(users_table)

Prepared an input table for matching into a FB custom audience, by identifying which columns are supported for matching, renaming those columns to what FB expects, and cutting away the other columns.

See FacebookAds.create_custom_audience for more details.

Args:

users_table: Table

The source table for matching

Returns:

Table

The prepared table

create_custom_audience(name, data_source, description=None)

Creates a FB custom audience.

Args:

name: str

The name of the custom audience

data_source: str

One of USER_PROVIDED_ONLY, PARTNER_PROVIDED_ONLY, or BOTH_USER_AND_PARTNER_PROVIDED. This tells FB whether the data for a custom audience was provided by actual users, or acquired via partners. FB requires you to specify.

description: str

Optional. The description of the custom audience

Returns:

ID of the created audience

delete_custom_audience(audience_id)

Deletes a FB custom audience.

Args:

audience_id: str

The ID of the custom audience to delete.

add_users_to_custom_audience(audience_id, users_table)

Adds user data to a custom audience.

Each user row in the provided table should have at least one of the supported columns defined. Otherwise the row will be ignored. Beyond that, the rows may have any other non-supported columns filled out, and those will all be ignored.

Column Type	Valid Column Names
Email Address	email, email address, voterbase_email
First Name	fn, first, first name, vb_tsmart_first_name
Last Name	ln, last, last name, vb_tsmart_last_name
Phone Number	phone, phone number, cell, landline, vb_voterbase_phone, vb_voterbase_phone_wireless
City	ct, city, vb_vf_reg_city, vb_tsmart_city
State	st, state, state code, vb_vf_source_state, vb_tsmart_state, vb_vf_reg_state, vb_vf_reg_cass_state
Zip Code	zip, zip code, vb_vf_reg_zip, vb_tsmart_zip
County	country, country code
Gender	gen, gender, sex, vb_vf_reg_zip
Birth Year	doby, dob year, birth year
Birth Month	dobm, dob month, birth month
Birth Day	dobd, dob day, birth day
Date of Birth	dob, vb_voterbase_dob, vb_tsmart_dob (Format: YYYYMMDD)

The column names will be normalized before comparing to this list - eg. removing whitespace and punctuation - so you don’t need to match exactly.

If more than one of your columns map to a single FB key, then for each row we’ll use any non-null value for those columns. Eg. If you have both vb_voterbase_phone and vb_voterbase_phone_wireless (which both map to the FB “phone” key), then for each person in your table, we’ll try to pick one valid phone number.

For details of the expected data formats for each column type, see Facebook Audience API, under “Hashing and Normalization for Multi-Key”.

Note that you shouldn’t have to do normalization on your data, as long as it’s reasonably close to what FB expects. Eg. It will convert “Male” to “m”, and “ JoSH” to “josh”.

FB will attempt to match the data to users in their system. You won’t be able to find out which users were matched. But if you provide enough data, FB will tell you roughly how many of them were matched. (You can find the custom audience in your business account at https://business.facebook.com).

Note that because FB’s matching is so opaque, it will hide lots of data issues. Eg. if you use “United States” instead of “US” for the “country” field, the API will appear to accept it, when in reality it is probably ignoring that field. So read the docs if you’re worried.

Args:

audience_id: str

The ID of the custom audience to delete.

users_table: obj

Parsons table