├── .DS_Store ├── .Rbuildignore ├── .gitignore ├── DESCRIPTION ├── NAMESPACE ├── R ├── batch_strata_ads.R ├── create_target.R ├── data.R └── strata_ad.R ├── README.md ├── data ├── fb_US_states.Rdata ├── fb_edu_level.Rdata ├── fb_ethnicity.Rdata └── fb_politics.Rdata ├── fbsample.Rproj └── man ├── batch_strata_ads.Rd ├── create_target.Rd ├── fb_US_states.Rd ├── fb_edu_level.Rd ├── fb_ethnicity.Rd ├── fb_politics.Rd └── strata_ad.Rd /.DS_Store: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/13bzhang/fbsample/ac570aef554707440ac04ce464a3a229823f9da1/.DS_Store -------------------------------------------------------------------------------- /.Rbuildignore: -------------------------------------------------------------------------------- 1 | ^.*\.Rproj$ 2 | ^\.Rproj\.user$ 3 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .Rproj.user 2 | .Rhistory 3 | .RData 4 | -------------------------------------------------------------------------------- /DESCRIPTION: -------------------------------------------------------------------------------- 1 | Package: fbsample 2 | Type: Package 3 | Title: Quota Sampling Using Facebook Advertisements 4 | Version: 0.1 5 | Date: 2017-01-07 6 | Author: Baobao Zhang 7 | Maintainer: Baobao Zhang 8 | Description: A tool to design and manage quota sampling using Facebook Advertisements. 9 | License: MIT License 10 | LazyData: true 11 | Imports: 12 | fbRads, 13 | RCurl, 14 | jsonlite, 15 | digest, 16 | futile.logger, 17 | bit64, 18 | plyr, 19 | data.table 20 | RoxygenNote: 6.0.1 21 | -------------------------------------------------------------------------------- /NAMESPACE: -------------------------------------------------------------------------------- 1 | # Generated by roxygen2: do not edit by hand 2 | 3 | export(batch_strata_ads) 4 | export(create_target) 5 | export(strata_ad) 6 | import(fbRads) 7 | -------------------------------------------------------------------------------- /R/batch_strata_ads.R: -------------------------------------------------------------------------------- 1 | #' Create Facebook ads for a batch of strata 2 | #' @param fbacc \code{FB_Ad_account} object that identifies your Facebook Ad account. Note this is not your Ad account number. 3 | #' @param strata_targeting list. Information about each strata that you plan to target. 4 | #' @param optimization_goal character. Optimization goal. 5 | #' @param billing_event character. The billing event. 6 | #' @param promoted_object list. See at \url{https://developers.facebook.com/docs/marketing-api/reference/ad-campaign/promoted-object}. 7 | #' @param campaign_id character. Parent Ad Campaign ID. 8 | #' @param wait_interval integer. Number of seconds to wait between creation of each ad to avoid exceeding the API rate limit. 9 | #' @param show_wait logical. If \code{TRUE}, the console will display a wait time progress bar. 10 | #' @param ... further arguments passed to the API endpoint 11 | #' @return A data.frame with Strata IDs, Ad Set IDs, Ad IDs for ads that have been successfully created. 12 | #' @import fbRads 13 | #' @export 14 | #' @references \url{https://developers.facebook.com/docs/marketing-api/reference/ad-campaign#Creating} 15 | 16 | batch_strata_ads <- function(fbacc, 17 | strata_targeting, 18 | optimization_goal = c( 19 | 'NONE', 20 | 'APP_INSTALLS', 21 | 'CLICKS', 22 | 'ENGAGED_USERS', 23 | 'EXTERNAL', 24 | 'EVENT_RESPONSES', 25 | 'IMPRESSIONS', 26 | 'LINK_CLICKS', 27 | 'OFFER_CLAIMS', 28 | 'OFFSITE_CONVERSIONS', 29 | 'PAGE_ENGAGEMENT', 30 | 'PAGE_LIKES', 31 | 'POST_ENGAGEMENT', 32 | 'REACH', 33 | 'SOCIAL_IMPRESSIONS', 34 | 'VIDEO_VIEWS' 35 | ), 36 | billing_event = c( 37 | 'APP_INSTALLS', 38 | 'CLICKS', 39 | 'IMPRESSIONS', 40 | 'LINK_CLICKS', 41 | 'OFFER_CLAIMS', 42 | 'PAGE_LIKES', 43 | 'POST_ENGAGEMENT', 44 | 'VIDEO_VIEWS' 45 | ), 46 | promoted_object, 47 | campaign_id, 48 | wait_interval = 100, 49 | show_wait, 50 | ...) { 51 | ## progress bar 52 | total <- 20 53 | pb <- txtProgressBar( 54 | min = 0, 55 | max = 10, 56 | style = 3, 57 | title = "Waiting for next ad upload." 58 | ) 59 | ## check the number of strata 60 | num_strata <- sum(names(unlist(strata_targeting)) == "strata_id") 61 | ## upload ads 62 | if (num_strata > 1) { 63 | ## upload ads one by one, with wait time between each upload to avoid 64 | ## exceeding API limit rate 65 | strata_output <- data.frame(strata_id = rep(NA, length(strata_targeting)), 66 | adset_id = rep(NA, length(strata_targeting)), 67 | ad_id = rep(NA, length(strata_targeting))) 68 | for (i in 1:length(strata_targeting)) { 69 | tryCatch ( 70 | strata_output[i,] <- strata_ad( 71 | fbacc = fbacc, 72 | adset_name = paste0("Ad set: ", strata_targeting[[i]]$strata_id), 73 | optimization_goal = optimization_goal, 74 | billing_event = billing_event, 75 | campaign_id = campaign_id, 76 | bid_amount = strata_targeting[[i]]$bid_amount, 77 | adset_status = strata_targeting[[i]]$adset_status, 78 | daily_budget = strata_targeting[[i]]$daily_budget, 79 | ad_status = strata_targeting[[i]]$ad_status, 80 | targeting = strata_targeting[[i]]$targets, 81 | creative_id = strata_targeting[[i]]$creative_id, 82 | start_time = strata_targeting[[i]]$start_time, 83 | end_time = strata_targeting[[i]]$end_time, 84 | ad_name = paste0("Ad: ", strata_targeting[[i]]$strata_id), 85 | strata_id = strata_targeting[[i]]$strata_id 86 | ), 87 | error = function(e) { 88 | message(e) 89 | message(paste0(strata_targeting[[i]]$strata_id, ": ad could not be created.")) 90 | }, 91 | finally = { 92 | if (i != length(strata_targeting)) { 93 | message( 94 | paste0( 95 | "Wait ", 96 | wait_interval , 97 | " seconds for next ad to be created. ", 98 | i, 99 | " out of ", 100 | length(strata_targeting), 101 | " ads created." 102 | ) 103 | ) 104 | } else { 105 | message(paste0("\n", i, " out of ", length(strata_targeting), " ads created.")) 106 | } 107 | } 108 | ) 109 | 110 | ## wait time progress bar 111 | if (i != length(strata_targeting) & show_wait) { 112 | for (i in 1:total) { 113 | Sys.sleep(wait_interval / total) 114 | setTxtProgressBar(pb, i) 115 | } 116 | close(pb) 117 | } 118 | } 119 | } else if (num_strata == 1) { 120 | strata_output <- data.frame(strata_id = NA, 121 | adset_id = NA, 122 | ad_id = NA) 123 | tryCatch ( 124 | strata_output[1,] <- strata_ad( 125 | fbacc = fbacc, 126 | adset_name = paste0("Ad set: ", strata_targeting$strata_id), 127 | optimization_goal = optimization_goal, 128 | billing_event = billing_event, 129 | campaign_id = campaign_id, 130 | bid_amount = strata_targeting$bid_amount, 131 | adset_status = strata_targeting$adset_status, 132 | daily_budget = strata_targeting$daily_budget, 133 | ad_status = strata_targeting$ad_status, 134 | targeting = strata_targeting$targets, 135 | creative_id = strata_targeting$creative_id, 136 | start_time = strata_targeting$start_time, 137 | end_time = strata_targeting$end_time, 138 | ad_name = paste0("Ad: ", strata_targeting$strata_id), 139 | strata_id = strata_targeting$strata_id 140 | ), 141 | error = function(e) { 142 | message(e) 143 | message(paste0(strata_targeting$strata_id, ": ad could not be created.")) 144 | }, 145 | finally = { 146 | message(paste0("\n", 1, " out of ", 1, " ads created.")) 147 | } 148 | ) 149 | } else { 150 | message("Error: the number of strata is undefined.") 151 | } 152 | 153 | ## return data.frame with Ad Set IDs and Ad IDs of successful ad creations 154 | return(strata_output) 155 | } 156 | -------------------------------------------------------------------------------- /R/create_target.R: -------------------------------------------------------------------------------- 1 | #' Create targeting attributes for a strata 2 | #' @param strata_id character. Strata ID. 3 | #' @param geo_locations list. A list specifying geographic location of the strata. See \url{https://developers.facebook.com/docs/marketing-api/buying-api/targeting#location}. 4 | #' @param age_min integer. Minimum age. If used, must be 13 or higher. Default to 18. 5 | #' @param age_max integer. Maximum age. If used, must be 65 or lower. 6 | #' @param genders integer. 1=male, 2=female. 7 | #' @param education_statuses integer. Vector of Facebook IDs to target based on education level. See \url{https://developers.facebook.com/docs/marketing-api/targeting-specs/v2.8}. 8 | #' @param interests list. A list of Facebook IDs for interests. 9 | #' @param behaviors list. A list of Facebook IDs for behaviors. Note that \code{ethnic_affinity} is now under the \code{behavior} category. 10 | #' @param exclusions list. A list of Facebook IDs for excluding certain demographics. 11 | #' @param other_demographics list. A list of Facebook IDs for other demographic targeting parameters. 12 | #' @param bid_amount integer. The amount you set for bid and budget are at ad account currencies minimum denomination level. For example cents for US dollars. 13 | #' @param is_autobid logical. If \code{TRUE}, bidding amount is automated and you do not need to include a \code{bid_amount}. 14 | #' @param daily_budget integer. The amount you set for bid and budget are at ad account currencies minimum denomination level. For example cents for US dollars. 15 | #' @param creative_id character. Creative ID that identifies the ad creative object you plan to display as your ad. See \url{https://developers.facebook.com/docs/marketing-api/reference/ad-creative}. 16 | #' @param adset_status character. Ad Set status. 17 | #' @param ad_status character. Ad status. 18 | #' @param start_time (optinal) UTC UNIX timestamp. 19 | #' @param end_time (optional) UTC UNIX timestamp. 20 | #' @return A list with targeting attributes for a strata that can be used to create ads. 21 | #' @export 22 | #' @references \url{https://developers.facebook.com/docs/marketing-api/buying-api/targeting} 23 | 24 | create_target <- 25 | function(strata_id, 26 | geo_locations, 27 | age_min = NULL, 28 | age_max = NULL, 29 | genders = NULL, 30 | education_statuses = NULL, 31 | ethnic_affinity = NULL, 32 | interests = NULL, 33 | behaviors = NULL, 34 | exclusions = NULL, 35 | other_demographics = NULL, 36 | is_autobid = FALSE, 37 | bid_amount = NULL, 38 | daily_budget, 39 | adset_status = c("ACTIVE", "PAUSED"), 40 | ad_status = c("ACTIVE", "PAUSED"), 41 | start_time = NULL, 42 | end_time = NULL, 43 | creative_id) { 44 | if (is.null(geo_locations)) { 45 | stop("You must provide at least one geographic location.") 46 | } else { 47 | targets <- 48 | list(geo_locations = geo_locations) 49 | if (!is.null(age_min)) { 50 | targets$age_min = unbox(age_min) 51 | } 52 | if (!is.null(age_max)) { 53 | targets$age_max = unbox(age_max) 54 | } 55 | if (!is.null(genders)) { 56 | targets$genders = list(as.integer(genders)) 57 | } 58 | if (!is.null(education_statuses)) { 59 | targets$education_statuses = as.integer(education_statuses) 60 | } 61 | if (!is.null(interests)) { 62 | targets$interests = interests 63 | } 64 | if (!is.null(behaviors)) { 65 | targets$behaviors = behaviors 66 | } 67 | if (!is.null(exclusions)) { 68 | targets$exclusions = exclusions 69 | } 70 | if (!is.null(other_demographics)) { 71 | targets <- c(targets, other_demographics) 72 | } 73 | } 74 | 75 | return(list(strata_id = strata_id, 76 | targets = targets, 77 | is_autobid = is_autobid, 78 | bid_amount = bid_amount, 79 | daily_budget = daily_budget, 80 | adset_status = adset_status, 81 | ad_status = ad_status, 82 | creative_id = creative_id, 83 | start_time = start_time, 84 | end_time = end_time 85 | )) 86 | } 87 | -------------------------------------------------------------------------------- /R/data.R: -------------------------------------------------------------------------------- 1 | #' Education Level 2 | #' 3 | #' A dataset that contains the keys for targeting specific levels of education. 4 | #' 5 | #' @docType data 6 | #' 7 | #' @usage data(fb_edu_level) 8 | #' 9 | #' @format A dataset with two variables: \code{key} and \code{description}. 10 | "fb_edu_level" 11 | 12 | #' U.S. Ethnic Affinity 13 | #' 14 | #' A dataset that contains the ids for targeting specific ethnic groups in the U.S. 15 | #' 16 | #' @docType data 17 | #' 18 | #' @usage data(fb_ethnicity) 19 | #' 20 | #' @format A data frame with six variables including the ethnic affinity \code{id} and 21 | #' \code{description}, along with metadata from the API Targeting Search results. 22 | "fb_ethnicity" 23 | 24 | #' U.S. Politics 25 | #' 26 | #' A data set that contains the ids for targeting specific political ideologies 27 | #' or behaviors in the U.S. 28 | #' 29 | #' @docType data 30 | #' 31 | #' @usage data(fb_politics) 32 | #' 33 | #' @format A dataset with 10 variables including the political 34 | #' ideologies/behaviors \code{id} and \code{description}, along with metadata 35 | #' from the API Targeting Search results. 36 | "fb_politics" 37 | 38 | #' U.S. States and Regions 39 | #' 40 | #' A data set that contains the keys for targeting states or regions within the U.S. 41 | #' 42 | #' @docType data 43 | #' 44 | #' @usage data(fb_US_states) 45 | #' 46 | #' @format A dataset with 5 variables including the \code{key} for each of the 50 U.S. 47 | #' states along with its corresponding Census region. 48 | "fb_US_states" 49 | 50 | -------------------------------------------------------------------------------- /R/strata_ad.R: -------------------------------------------------------------------------------- 1 | #' Create a Facebook ad for a strata 2 | #' @param fbacc \code{FB_Ad_account} object that identifies your Facebook Ad account. Note this is not your Ad account number. 3 | #' @param strata_id character. Strata ID. 4 | #' @param adset_name character. Name of the Ad Set. 5 | #' @param optimization_goal character. Optimization goal. 6 | #' @param billing_event character. The billing event. 7 | #' @param bid_amount integer. The amount you set for bid and budget are at ad account currencies minimum denomination level. For example cents for US dollars. 8 | #' @param promoted_object list. See at \url{https://developers.facebook.com/docs/marketing-api/reference/ad-campaign/promoted-object}. 9 | #' @param campaign_id character. Parent Ad Campaign ID. 10 | #' @param daily_budget integer. The amount you set for bid and budget are at ad account currencies minimum denomination level. For example cents for US dollars. 11 | #' @param end_time UTC UNIX timestamp. 12 | #' @param start_time UTC UNIX timestamp. 13 | #' @param targeting list. Describes the demographics of your strata. 14 | #' @param creative_id character. Creative ID that identifies the ad creative object you plan to display as your ad. See \url{https://developers.facebook.com/docs/marketing-api/reference/ad-creative}. 15 | #' @param adset_status character. Ad Set status. 16 | #' @param ad_status character. Ad status. 17 | #' @param ... further arguments passed to the API endpoint 18 | #' @return A data.frame with Strata ID, Ad Set ID, Ad ID 19 | #' @import fbRads 20 | #' @export 21 | #' @references \url{https://developers.facebook.com/docs/marketing-api/reference/ad-campaign#Creating} 22 | 23 | strata_ad <- function(fbacc, 24 | strata_id, 25 | adset_name, 26 | ad_name, 27 | optimization_goal = c( 28 | 'NONE', 29 | 'APP_INSTALLS', 30 | 'CLICKS', 31 | 'ENGAGED_USERS', 32 | 'EXTERNAL', 33 | 'EVENT_RESPONSES', 34 | 'IMPRESSIONS', 35 | 'LINK_CLICKS', 36 | 'OFFER_CLAIMS', 37 | 'OFFSITE_CONVERSIONS', 38 | 'PAGE_ENGAGEMENT', 39 | 'PAGE_LIKES', 40 | 'POST_ENGAGEMENT', 41 | 'REACH', 42 | 'SOCIAL_IMPRESSIONS', 43 | 'VIDEO_VIEWS' 44 | ), 45 | billing_event = c( 46 | 'APP_INSTALLS', 47 | 'CLICKS', 48 | 'IMPRESSIONS', 49 | 'LINK_CLICKS', 50 | 'OFFER_CLAIMS', 51 | 'PAGE_LIKES', 52 | 'POST_ENGAGEMENT', 53 | 'VIDEO_VIEWS' 54 | ), 55 | bid_amount, 56 | promoted_object, 57 | campaign_id, 58 | status = c('ACTIVE', 'PAUSED', 'ARCHIVED', 'DELETED'), 59 | daily_budget, 60 | end_time = NULL, 61 | start_time = NULL, 62 | creative_id, 63 | targeting, 64 | adset_status = c("ACTIVE", "PAUSED"), 65 | ad_status = c("ACTIVE", "PAUSED"), 66 | ...) { 67 | 68 | ## create the ad set 69 | adset <- 70 | fbRads::fbad_create_adset(fbacc = fbacc, 71 | name = adset_name, 72 | optimization_goal = optimization_goal, 73 | billing_event = billing_event, 74 | bid_amount = bid_amount, 75 | campaign_id = campaign_id, 76 | status = adset_status, 77 | daily_budget = daily_budget, 78 | start_time = start_time, 79 | end_time = end_time, 80 | promoted_object = promoted_object, 81 | targeting = targeting 82 | ) 83 | ## create the ad 84 | ad <- 85 | fbRads::fbad_create_ad( 86 | fbacc = fbacc, 87 | name = ad_name, 88 | campaign_id = campaign_id, 89 | creative_id = creative_id, 90 | adset_id = adset, 91 | status = ad_status 92 | ) 93 | # return strata ID, ad set ID, and ad ID 94 | return(c( 95 | strata_id = as.character(strata_id), 96 | adset_id = as.character(adset), 97 | ad_id = as.character(ad) 98 | )) 99 | } 100 | 101 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # fbsample 2 | 3 | R Package for Quota Sampling on Facebook 4 | 5 | This R package makes it easier for one to conduct quota sampling via Facebook advertisements. `fbsample` serves two main functions. First, it allows one to specify which demographic groups to target. Second, it uses R wrapper functions in [fbRads](https://github.com/cardcorp/fbRads) to create ads in batches and upload them via the [Facebook Marketplace API](https://developers.facebook.com/docs/marketing-apis). 6 | 7 | ----------------------------- 8 | 9 | ## Updates 10 | 11 | 3/18/2017: I added four helpful datasets in the `data` folder that include the ids and keys for ad targets. Now you can easily look up targets for level of education, ethnicity (US), politics (US), and US states/regions. 12 | 13 | 3/19/2017: Facebook has removed `ethnic_affinity` as an ad target category after [receiving negative press](https://www.nytimes.com/2016/11/12/business/media/facebook-will-stop-some-ads-from-targeting-users-by-race.html?_r=0). But you can still recruit people by ethnic affinity using the `behavior` category. I removed `ethnic_affinity` as a parameter from the function `create_target` to reflect this change. To sample white respondents, you would need to exclude all the minority ethnic affinity groups. I am providing this information for social scientific purposes only. Don't use the functionality for racist purposes! 14 | 15 | ----------------------------- 16 | 17 | ## In a nutshell 18 | 19 | Facebook allows advertisers to target audiences by demographic groups. Using the [Facebook Marketing API](https://developers.facebook.com/docs/marketing-apis), researchers can create ads that target a large number of strata for quota sampling. Researchers recruit respondents by advertising their online survey using Facebook ads. 20 | 21 | ## Understanding the structure of Facebook ad campaigns 22 | 23 | Facebook ad campaigns have a three-level structure. For the purposes of quota sampling, each sampling project is a **Campaign**. The Campaign objective determines how you pay to recruit respondents. For instance, you can pay for per completed survey using the [conversion objective](https://www.facebook.com/business/learn/facebook-create-ad-website-conversions) or you can pay for clicks to your survey link. 24 | 25 | Targeting of individual strata occurs at the **Ad set** level. For each Ad set, you input the demographics of the strata and how much you are willing to spend to advertise to that strata. Finally, for each **Ad set**, you create an **Ad** that uses an **Ad Creative** (ad text, image, and survey link) to recruit respondents. 26 | 27 | ![](https://static1.squarespace.com/static/56c4d0b94d088e1c92d242af/t/5723e35e746fb941a5c16fdb/1461969760920/?format=750w) 28 | 29 | ## How to quota sample using Facebook ads 30 | 31 | 1. Set up a [Facebook Page](https://www.facebook.com/business/learn/set-up-facebook-page) so you can create and manage ads. 32 | 33 | 2. Create a Facebook App and authorize it to manage the ads of your Facebook Page. Follow the directions outlined in [fbRads](https://github.com/cardcorp/fbRads/blob/master/README.md) to crate your Facebook App and connect with the OAuth token. 34 | 35 | 3. Draft [a post](https://www.facebook.com/business/learn/facebook-page-create-posts) for your Facebook Page that you will use as your [Ad Creative](https://developers.facebook.com/docs/marketing-api/reference/ad-creative). The post should contain a catchy image, a short description of your survey, and a link to your survey. Do not publish the post but instead save it as a draft to be published later as part of your ad. 36 | 37 | 4. Use `fb_campaign` in `fbRads` to create a [Campaign](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign-group) for your quota sample. All ads will be a part of this campaign. 38 | 39 | 5. Use `create_target` in `fbsample` to create [demographic targets](https://www.facebook.com/business/a/online-sales/ad-targeting-details) for each strata in your quota sample. In addition to each strata's demographics information, you should also provide information about how much you plan to spend on each strata. 40 | 41 | 6. Use `batch_strata_ads` in `fbsample` to create ads for each strata in your quota sample. For each strata, the function creates an Ad set and an Ad. 42 | 43 | -------------------------------------------------------------------------------- /data/fb_US_states.Rdata: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/13bzhang/fbsample/ac570aef554707440ac04ce464a3a229823f9da1/data/fb_US_states.Rdata -------------------------------------------------------------------------------- /data/fb_edu_level.Rdata: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/13bzhang/fbsample/ac570aef554707440ac04ce464a3a229823f9da1/data/fb_edu_level.Rdata -------------------------------------------------------------------------------- /data/fb_ethnicity.Rdata: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/13bzhang/fbsample/ac570aef554707440ac04ce464a3a229823f9da1/data/fb_ethnicity.Rdata -------------------------------------------------------------------------------- /data/fb_politics.Rdata: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/13bzhang/fbsample/ac570aef554707440ac04ce464a3a229823f9da1/data/fb_politics.Rdata -------------------------------------------------------------------------------- /fbsample.Rproj: -------------------------------------------------------------------------------- 1 | Version: 1.0 2 | 3 | RestoreWorkspace: Default 4 | SaveWorkspace: Default 5 | AlwaysSaveHistory: Default 6 | 7 | EnableCodeIndexing: Yes 8 | UseSpacesForTab: Yes 9 | NumSpacesForTab: 2 10 | Encoding: UTF-8 11 | 12 | RnwWeave: Sweave 13 | LaTeX: pdfLaTeX 14 | 15 | AutoAppendNewline: Yes 16 | StripTrailingWhitespace: Yes 17 | 18 | BuildType: Package 19 | PackageUseDevtools: Yes 20 | PackageInstallArgs: --no-multiarch --with-keep.source 21 | -------------------------------------------------------------------------------- /man/batch_strata_ads.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/batch_strata_ads.R 3 | \name{batch_strata_ads} 4 | \alias{batch_strata_ads} 5 | \title{Create Facebook ads for a batch of strata} 6 | \usage{ 7 | batch_strata_ads(fbacc, strata_targeting, optimization_goal = c("NONE", 8 | "APP_INSTALLS", "CLICKS", "ENGAGED_USERS", "EXTERNAL", "EVENT_RESPONSES", 9 | "IMPRESSIONS", "LINK_CLICKS", "OFFER_CLAIMS", "OFFSITE_CONVERSIONS", 10 | "PAGE_ENGAGEMENT", "PAGE_LIKES", "POST_ENGAGEMENT", "REACH", 11 | "SOCIAL_IMPRESSIONS", "VIDEO_VIEWS"), billing_event = c("APP_INSTALLS", 12 | "CLICKS", "IMPRESSIONS", "LINK_CLICKS", "OFFER_CLAIMS", "PAGE_LIKES", 13 | "POST_ENGAGEMENT", "VIDEO_VIEWS"), promoted_object, campaign_id, 14 | wait_interval = 100, show_wait, ...) 15 | } 16 | \arguments{ 17 | \item{fbacc}{\code{FB_Ad_account} object that identifies your Facebook Ad account. Note this is not your Ad account number.} 18 | 19 | \item{strata_targeting}{list. Information about each strata that you plan to target.} 20 | 21 | \item{optimization_goal}{character. Optimization goal.} 22 | 23 | \item{billing_event}{character. The billing event.} 24 | 25 | \item{promoted_object}{list. See at \url{https://developers.facebook.com/docs/marketing-api/reference/ad-campaign/promoted-object}.} 26 | 27 | \item{campaign_id}{character. Parent Ad Campaign ID.} 28 | 29 | \item{wait_interval}{integer. Number of seconds to wait between creation of each ad to avoid exceeding the API rate limit.} 30 | 31 | \item{show_wait}{logical. If \code{TRUE}, the console will display a wait time progress bar.} 32 | 33 | \item{...}{further arguments passed to the API endpoint} 34 | } 35 | \value{ 36 | A data.frame with Strata IDs, Ad Set IDs, Ad IDs for ads that have been successfully created. 37 | } 38 | \description{ 39 | Create Facebook ads for a batch of strata 40 | } 41 | \references{ 42 | \url{https://developers.facebook.com/docs/marketing-api/reference/ad-campaign#Creating} 43 | } 44 | -------------------------------------------------------------------------------- /man/create_target.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/create_target.R 3 | \name{create_target} 4 | \alias{create_target} 5 | \title{Create targeting attributes for a strata} 6 | \usage{ 7 | create_target(strata_id, geo_locations, age_min = NULL, age_max = NULL, 8 | genders = NULL, education_statuses = NULL, ethnic_affinity = NULL, 9 | interests = NULL, behaviors = NULL, exclusions = NULL, 10 | other_demographics = NULL, is_autobid = FALSE, bid_amount = NULL, 11 | daily_budget, adset_status = c("ACTIVE", "PAUSED"), 12 | ad_status = c("ACTIVE", "PAUSED"), start_time = NULL, end_time = NULL, 13 | creative_id) 14 | } 15 | \arguments{ 16 | \item{strata_id}{character. Strata ID.} 17 | 18 | \item{geo_locations}{list. A list specifying geographic location of the strata. See \url{https://developers.facebook.com/docs/marketing-api/buying-api/targeting#location}.} 19 | 20 | \item{age_min}{integer. Minimum age. If used, must be 13 or higher. Default to 18.} 21 | 22 | \item{age_max}{integer. Maximum age. If used, must be 65 or lower.} 23 | 24 | \item{genders}{integer. 1=male, 2=female.} 25 | 26 | \item{education_statuses}{integer. Vector of Facebook IDs to target based on education level. See \url{https://developers.facebook.com/docs/marketing-api/targeting-specs/}.} 27 | 28 | \item{ethnic_affinity}{integer. Vector of Facebook IDs for each ethnic group.} 29 | 30 | \item{interests}{list. A list of Facebook IDs for interests.} 31 | 32 | \item{behaviors}{list. A list of Facebook IDs for behaviors.} 33 | 34 | \item{exclusions}{list. A list of Facebook IDs for excluding certain demographics.} 35 | 36 | \item{other_demographics}{list. A list of Facebook IDs for other demographic targeting parameters.} 37 | 38 | \item{is_autobid}{logical. If \code{TRUE}, bidding amount is automated and you do not need to include a \code{bid_amount}.} 39 | 40 | \item{bid_amount}{integer. The amount you set for bid and budget are at ad account currencies minimum denomination level. For example cents for US dollars.} 41 | 42 | \item{daily_budget}{integer. The amount you set for bid and budget are at ad account currencies minimum denomination level. For example cents for US dollars.} 43 | 44 | \item{adset_status}{character. Ad Set status.} 45 | 46 | \item{ad_status}{character. Ad status.} 47 | 48 | \item{start_time}{(optinal) UTC UNIX timestamp.} 49 | 50 | \item{end_time}{(optional) UTC UNIX timestamp.} 51 | 52 | \item{creative_id}{character. Creative ID that identifies the ad creative object you plan to display as your ad. See \url{https://developers.facebook.com/docs/marketing-api/reference/ad-creative}.} 53 | } 54 | \value{ 55 | A list with targeting attributes for a strata that can be used to create ads. 56 | } 57 | \description{ 58 | Create targeting attributes for a strata 59 | } 60 | \references{ 61 | \url{https://developers.facebook.com/docs/marketing-api/buying-api/targeting} 62 | } 63 | -------------------------------------------------------------------------------- /man/fb_US_states.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/data.R 3 | \docType{data} 4 | \name{fb_US_states} 5 | \alias{fb_US_states} 6 | \title{U.S. States and Regions} 7 | \format{A dataset with 5 variables including the \code{key} for each of the 50 U.S. 8 | states along with its corresponding Census region.} 9 | \usage{ 10 | data(fb_US_states) 11 | } 12 | \description{ 13 | A data set that contains the keys for targeting states or regions within the U.S. 14 | } 15 | \keyword{datasets} 16 | -------------------------------------------------------------------------------- /man/fb_edu_level.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/data.R 3 | \docType{data} 4 | \name{fb_edu_level} 5 | \alias{fb_edu_level} 6 | \title{Education Level} 7 | \format{A dataset with two variables: \code{key} and \code{description}.} 8 | \usage{ 9 | data(fb_edu_level) 10 | } 11 | \description{ 12 | A dataset that contains the keys for targeting specific levels of education. 13 | } 14 | \keyword{datasets} 15 | -------------------------------------------------------------------------------- /man/fb_ethnicity.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/data.R 3 | \docType{data} 4 | \name{fb_ethnicity} 5 | \alias{fb_ethnicity} 6 | \title{U.S. Ethnic Affinity} 7 | \format{A data frame with six variables including the ethnic affinity \code{id} and 8 | \code{description}, along with metadata from the API Targeting Search results.} 9 | \usage{ 10 | data(fb_ethnicity) 11 | } 12 | \description{ 13 | A dataset that contains the ids for targeting specific ethnic groups in the U.S. 14 | } 15 | \keyword{datasets} 16 | -------------------------------------------------------------------------------- /man/fb_politics.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/data.R 3 | \docType{data} 4 | \name{fb_politics} 5 | \alias{fb_politics} 6 | \title{U.S. Politics} 7 | \format{A dataset with 10 variables including the political 8 | ideologies/behaviors \code{id} and \code{description}, along with metadata 9 | from the API Targeting Search results.} 10 | \usage{ 11 | data(fb_politics) 12 | } 13 | \description{ 14 | A data set that contains the ids for targeting specific political ideologies 15 | or behaviors in the U.S. 16 | } 17 | \keyword{datasets} 18 | -------------------------------------------------------------------------------- /man/strata_ad.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/strata_ad.R 3 | \name{strata_ad} 4 | \alias{strata_ad} 5 | \title{Create a Facebook ad for a strata} 6 | \usage{ 7 | strata_ad(fbacc, strata_id, adset_name, ad_name, optimization_goal = c("NONE", 8 | "APP_INSTALLS", "CLICKS", "ENGAGED_USERS", "EXTERNAL", "EVENT_RESPONSES", 9 | "IMPRESSIONS", "LINK_CLICKS", "OFFER_CLAIMS", "OFFSITE_CONVERSIONS", 10 | "PAGE_ENGAGEMENT", "PAGE_LIKES", "POST_ENGAGEMENT", "REACH", 11 | "SOCIAL_IMPRESSIONS", "VIDEO_VIEWS"), billing_event = c("APP_INSTALLS", 12 | "CLICKS", "IMPRESSIONS", "LINK_CLICKS", "OFFER_CLAIMS", "PAGE_LIKES", 13 | "POST_ENGAGEMENT", "VIDEO_VIEWS"), bid_amount, promoted_object, campaign_id, 14 | is_autobid = FALSE, status = c("ACTIVE", "PAUSED", "ARCHIVED", "DELETED"), 15 | daily_budget, end_time = NULL, start_time = NULL, creative_id, targeting, 16 | adset_status = c("ACTIVE", "PAUSED"), ad_status = c("ACTIVE", "PAUSED"), 17 | ...) 18 | } 19 | \arguments{ 20 | \item{fbacc}{\code{FB_Ad_account} object that identifies your Facebook Ad account. Note this is not your Ad account number.} 21 | 22 | \item{strata_id}{character. Strata ID.} 23 | 24 | \item{adset_name}{character. Name of the Ad Set.} 25 | 26 | \item{optimization_goal}{character. Optimization goal.} 27 | 28 | \item{billing_event}{character. The billing event.} 29 | 30 | \item{bid_amount}{integer. The amount you set for bid and budget are at ad account currencies minimum denomination level. For example cents for US dollars.} 31 | 32 | \item{promoted_object}{list. See at \url{https://developers.facebook.com/docs/marketing-api/reference/ad-campaign/promoted-object}.} 33 | 34 | \item{campaign_id}{character. Parent Ad Campaign ID.} 35 | 36 | \item{is_autobid}{logical. If \code{TRUE}, bidding amount is automated and you do not need to include a \code{bid_amount}.} 37 | 38 | \item{daily_budget}{integer. The amount you set for bid and budget are at ad account currencies minimum denomination level. For example cents for US dollars.} 39 | 40 | \item{end_time}{UTC UNIX timestamp.} 41 | 42 | \item{start_time}{UTC UNIX timestamp.} 43 | 44 | \item{creative_id}{character. Creative ID that identifies the ad creative object you plan to display as your ad. See \url{https://developers.facebook.com/docs/marketing-api/reference/ad-creative}.} 45 | 46 | \item{targeting}{list. Describes the demographics of your strata.} 47 | 48 | \item{adset_status}{character. Ad Set status.} 49 | 50 | \item{ad_status}{character. Ad status.} 51 | 52 | \item{...}{further arguments passed to the API endpoint} 53 | } 54 | \value{ 55 | A data.frame with Strata ID, Ad Set ID, Ad ID 56 | } 57 | \description{ 58 | Create a Facebook ad for a strata 59 | } 60 | \references{ 61 | \url{https://developers.facebook.com/docs/marketing-api/reference/ad-campaign#Creating} 62 | } 63 | --------------------------------------------------------------------------------