How to Extract Marketing Campaign Statistics from Facebook API Using R

Facebook becomes more and more popular as a marketing platform. However, the Facebook Ads Manager tool isn’t user-friendly enough to carry out statistical analysis. One of the alternative ways to do that is to import data into R and visualize it. In this article, I’m going to share the detailed steps on how to extract data from API and work with it in R.

I’ve written a set of functions to work with Facebook API and gathered them in a rfacebookstat package available at GitHub and CRAN.

1. Create an App in Facebook

1.1. To start work with Facebook API, you should create a new app. Follow this link and click “App Manager” in a left side navigation menu.

1.2. In facebook platform for developers click “+ Add a New App”.

Fill in the textboxes “Display Name”, “Contact Email”, “Category” and hit “Create App ID”.

1.3.  You’ll see the “Product Installation and Setup” menu. Select “Facebook Login” and click “Set Up”.

1.4. Select WWW.

1.5. Type https://selesnow.github.io in the “Site URL” textbox and hit “Save” → “Continue”.

1.6. Select “Facebook Login” on a sidebar menu. Type “https://selesnow.github.io/rfacebookstat/getToken/get_token.html” in the “Valid OAuth Redirect URLs” textbox.

1.7. Select one more product: “API Marketing”:

Finish creating and setting the app. Select “Settings” → “Basic” and copy the App ID and App Secret.

You’ll need this data to authorize later.

Important: Many people flip the switch on for the “In Development” status and get an authorization error afterward as one must complete a detailed verification process on Facebook to publish an app. Thankfully, if you register your app for personal us, you don’t have to flip the switch on.

2. Install rfacebookstat Package

A rfacebookstat package is available for install from CRAN and GitHub.

2.1. To install CRAN packages, use a standard command install.packages().

install.packages("rfacebookstat")

2.2. Enable the rfacebookstat package.

The package may be considered a separate software program, so you have to install it first and launch every time you need it. Enable packages in R using a library() function.

library(rfacebookstat)

3. Get Facebook API Access Token

Get authorized to start work with Facebook API. Use a fbAuth() function in the rfacebookstat package. 

3.1. Select “Settings” → “Basic”, copy the App ID and App Secret and paste them into the corresponding function arguments.

fbAuth(app_id     = 00000000000000,      app_secret = "xxxxxxxxxxxxx",       username   = "your login")

Paste your Facebook login as a username argument.

3.2. If this is the first time you get a token, you may get a warning notification that some things aren’t approved by Facebook yet. Skip this by clicking “Continue as...”.

Confirm Facebook Login.

As you get redirected to a website with my packages https://selesnow.github.io, a short-lived authorization token is generated for you.

If JavaScript is enabled in your browser, the token will be copied to the clipboard, and in thirty seconds you’ll be redirected to an official page with a package help. If JavaScript is disabled, you’ll have to copy the token manually.

3.3. Enter a value into the R console.

3.4. Your short-lived token will be replaced with the long-lived one and you’ll see the following notification: 

Token changed to long time successfully
Do you want save your access token into rds file 
C:/Users/Username/Documents/blog_login.rfb_auth.rds 
for use it between R sessions? y / n (recmedation y) ?:

The first line that informs you of the token replacement is followed by the second one that asks if you’d like to save the data to use it later in various R sessions. I strongly recommend you to choose ’y’ as it will save you the trouble of getting authorized via browser every time later.

3.5. Request a list of available accounts to check if authorization is successful.

fbGetAdAccounts(username = "your login")

If you get a list of accounts, the authorization is successful; if you get an error, you’ve probably configured an app improperly.

4. Get Facebook Advertising Statistics

The preparation stage is over, we can proceed with data import.

The main function of the rfacebookstat package is fbGetMarketingStat(). Let’s go into detail on how to work with this function as it can help you get any data on any advertising account performance.

4.1. Syntax

stat <- fbGetMarketingStat(accounts_id  = "act_0000000000",                           
sorting      = NULL,                           level        = "account",                          
 breakdowns   = NULL,                           fields       = "account_id,                                            
campaign_name,                                           impressions,                                           
 clicks,                                            reach,                                           
 spend",                           filtering    = NULL,                           
date_start   = Sys.Date() - 30,                          
 date_stop    = Sys.Date(),                           
username     = getOption("rfacebookstat.username"),                           
token_path = fbTokenPath())

The code above contains most of the arguments of a function fbGetMarketingStat() set as default values.

4.2. Function arguments

4.2.1. accounts_id: an ad account ID. It’s a required argument. You can get it from a URL if you open a Facebook advertising account you need.

As you have to indicate an ad account ID every time you open API, you can avoid such data duplication by inserting the list of accounts you need at the beginning of a script in the rfacebookstat.accounts_id option.

options( rfacebookstat.accounts_id = c("47725506", "361373151") )

After that every function of the rfacebookstat package will automatically import accounts specified in the rfacebookstat.accounts_id option.

4.2.2. sorting: data sorting. It’s an optional argument. Available options are ‘field list’ and ‘sorting direction’ (in either ascending or descending order). For example, reach_descending, impressions_ascending.

4.2.3. level: the Ads object level. It’s a required argument. Available options are ‘ad’, ‘adset’, ‘campaign’, ‘account’. For example, level = "account".

4.2.4. fields provide data you want to import. It’s a required argument. For example, fields = "account_id,account_name,campaign_name,impressions,unique_impressions,clicks,unique_clicks,reach,spend".

See the table below for a more detailed field list available in API 2.8. or refer to official documentation.

4.2.5. Breakdowns are used to capture Ads Insights responses that are grouped into different sets or cohorts. Supported breakdowns are:

• age;
• country;
• gender;
• frequency_value;
• hourly_stats_aggregated_by_advertiser_time_zone;
• hourly_stats_aggregated_by_audience_time_zone;
• impression_device;
• place_page_id;
• placement;
• device_platform;
• product_id;
• region;
• actions;
• publisher_platform;
• platform_position;
• impression_device.

Breakdowns can be combined. The following combinations are available now: 

• action_type *;
• action_target_id *;
• action_device *;
• action_device, placement *;
• action_device, placement, impression_device *;
• action_device, publisher_platform *;
• action_device, publisher_platform, impression_device *;
• action_device, publisher_platform, platform_position *;
• action_device, publisher_platform, platform_position, impression_device *;
• action_reaction;
• action_type, action_reaction;
• age *;
• gender *;
• age, gender *;
• country *;
• region *;
• placement *;
• placement, impression_device *;
• publisher_platform *;
• publisher_platform, impression_device *;
• publisher_platform, platform_position *;
• publisher_platform, platform_position, impression_device *;
• product_id *;
• hourly_stats_aggregated_by_advertiser_time_zone *;
• hourly_stats_aggregated_by_audience_time_zone *;
• action_carousel_card_id / action_carousel_card_name;
• action_carousel_card_id / action_carousel_card_name, placement;
• action_carousel_card_id / action_carousel_card_name, placement, impression_device;
• action_carousel_card_id / action_carousel_card_name, country;
• action_carousel_card_id / action_carousel_card_name, age;
• action_carousel_card_id / action_carousel_card_name, gender;
• action_carousel_card_id / action_carousel_card_name, age, gender.

For example: breakdowns = "region"

4.2.6. filtering: data filtering. An optional argument. Filters are specified as JSON objects “key:value”. Indicate three properties:

• field: a filtering field;
• operator: a logical operator ('EQUAL', 'NOT_EQUAL', 'GREATER_THAN', 'GREATER_THAN_OR_EQUAL', 'LESS_THAN', 'LESS_THAN_OR_EQUAL', 'IN_RANGE', 'NOT_IN_RANGE', 'CONTAIN', 'NOT_CONTAIN', 'IN', 'NOT_IN', 'ANY', 'ALL', 'NONE');
• value: a filtering value.

For example:

filtering = "impressions LESS_THAN 5000"

4.2.7. Date_start: This shows the start date of a campaign if it’s already running or the date when it’s scheduled to begin in a YYYY-MM-DD format.

4.2.8. date_stop: This shows the end date of the campaign in a YYYY-MM-DD format.

4.2.9. api_version: Facebook API version.

4.2.10. access_token: an access token.

5. Examples of how to use fbGetMarketingStat

5.1. Before you launch the examples below, you should generate an API token and save it as a file with the help of a fbAuth() function.

fbAuth(app_id     = 00000000000000,       app_secret = "xxxxxxxxxxxxx",        username   = "your login")

5.2. Enter the following code to get the statistics on the number of impressions, clicks and ads spends at the account level and separately for each region:

AccStat <- fbGetMarketingStat(                      
 accounts_id = “act_0000000000”,                     
 level = "account",                      fields = "account_id,                               
 account_name,                                impressions,                              
  clicks,                                spend",                     
 breakdowns = "region",                      date_start = "2020-03-01",                      
date_stop = "2020-03-30",                      username   = "your login")

5.3. Get the statistics on the number of unique impressions and unique clicks filtered by age groups “18-24”, “25-34” and data sorting in decreasing order of unique impressions (the ‘reach’ field).

CampStat <-     fbGetMarketingStat(accounts_id = "act_0000000000",                          
level = "campaign",                          fields = "campaign_name,                                    
reach,                                    unique_clicks",                          
breakdowns = "age",                          sorting = "reach_descending",                          
filtering  = "age IN 18-24,25-34",                          date_start = "2020-03-01",                         
 date_stop  = "2020-03-30",                          username   = "your login")

Conclusions

Utilizing Facebook API and rfacebookstat R package enables you to:

• get the data on all advertising accounts, campaigns, ads etc. from different perspectives.
• create data visualizations using all power of R.
• transfer the data to any database or save it as a CSV.