diff --git a/R/fb_ad.R b/R/fb_ad.R index 05491be..a858e19 100644 --- a/R/fb_ad.R +++ b/R/fb_ad.R @@ -1,42 +1,22 @@ -#' Create ad +#' Create Ad #' @inheritParams fbad_request -#' @param name Ad group name -#' @param adset_id Ad Set id -#' @param creative_id creative ID -#' @param status initial status of the Ad group -#' @param ... further parameters passed to the Facebook API +#' @param ... further parameters passed to the API, see below references #' @return ad id #' @export #' @references \url{https://developers.facebook.com/docs/marketing-api/reference/adgroup#Creating} -fbad_create_ad <- function(fbacc, - name, - adset_id, - creative_id, - status = c('ACTIVE', 'PAUSED'),...) { +fbad_create_ad <- function(fbacc, ...) { - fbacc <- fbad_check_fbacc() - stopifnot(!missing(name), !missing(adset_id), !missing(creative_id)) - - ## initial status of the ad to be created - status <- match.arg(status) + ## lookup caller fn name and the API endpoint based on that + endpoint <- switch(this_function_name(), + 'fbad_create_ad' = 'ads', + 'fbad_create_adset' = 'adsets', + 'fbad_create_campaign' = 'campaigns') - ## build params list - params <- list( - name = name, - creative = toJSON(list(creative_id = unbox(creative_id))), - adset_id = adset_id, - status = status) - ## add further params if provided - if (length(list(...)) > 0) { - params <- c(params, list(...)) - } - - ## get results - res <- fbad_request(fbacc, - path = paste0('act_', fbacc$account_id, '/ads'), + res <- fbad_request(fbad_check_fbacc(), + path = paste0('act_', fbacc$account_id, '/', endpoint), method = "POST", - params = params) + params = list(...)) ## return campaign ID on success fromJSONish(res)$id diff --git a/R/fb_adset.R b/R/fb_adset.R index 7594732..2160627 100644 --- a/R/fb_adset.R +++ b/R/fb_adset.R @@ -1,123 +1,9 @@ #' Create Ad Set -#' @inheritParams fbad_request -#' @param name name of the Ad Set -#' @param optimization_goal optimization goal -#' @param billing_event the billing event -#' @param is_autobid logical. If \code{TRUE}, autobid is set and you do not need to specify \code{bid_amount} -#' @param bid_amount integer -#' @param promoted_object see at \url{https://developers.facebook.com/docs/marketing-api/reference/ad-campaign/promoted-object} -#' @param campaign_id parent Ad Campaign id -#' @param status Ad Set status -#' @param daily_budget using account currency -#' @param lifetime_budget using account currency -#' @param end_time UTC UNIX timestamp -#' @param start_time UTC UNIX timestamp -#' @param targeting list -#' @param ... further arguments passed to the API endpoint +#' @inheritParams fbad_create_ad #' @return Ad Set id #' @export #' @references \url{https://developers.facebook.com/docs/marketing-api/reference/ad-campaign#Creating} -fbad_create_adset <- function(fbacc, - name, - optimization_goal = c('NONE', 'APP_INSTALLS', 'CLICKS', 'ENGAGED_USERS', 'EXTERNAL', 'EVENT_RESPONSES', 'IMPRESSIONS', 'LINK_CLICKS', 'OFFER_CLAIMS', 'OFFSITE_CONVERSIONS', 'PAGE_ENGAGEMENT', 'PAGE_LIKES', 'POST_ENGAGEMENT', 'REACH', 'SOCIAL_IMPRESSIONS', 'VIDEO_VIEWS'), - billing_event = c('APP_INSTALLS', 'CLICKS', 'IMPRESSIONS', 'LINK_CLICKS', 'OFFER_CLAIMS', 'PAGE_LIKES', 'POST_ENGAGEMENT', 'VIDEO_VIEWS'), - is_autobid = FALSE, bid_amount, - promoted_object, - campaign_id, - status = c('ACTIVE', 'PAUSED', 'ARCHIVED', 'DELETED'), - daily_budget, lifetime_budget, - end_time, start_time, - targeting, - ...) { - - fbacc <- fbad_check_fbacc() - - optimization_goal <- match.arg(optimization_goal) - billing_event <- match.arg(billing_event) - - ## update args for the first or selected value - status <- match.arg(status) - - ## match call for future reference - mc <- match.call() - - ## we need a name - if (missing(name)) { - stop('Ad Set name is required.') - } - - ## we need a campaign_group_id - if (missing(campaign_id)) { - stop('A campaign ad ID is required.') - } - - ## verify that we have targeting info - if (missing(targeting)) { - stop('A targeting spec is required.') - } - - ## build base params list - params <- list( - name = name, - optimization_goal = optimization_goal, - billing_event = billing_event, - campaign_id = campaign_id, - configured_status = match.arg(status)) - ## option for auto bidding - if (is_autobid) { - params$is_autobid <- TRUE - } else { - params$bid_amount <- bid_amount - } - - ## end_time for lifetime budget - if (!missing(lifetime_budget) && missing(end_time)) { - stop('End time of the ad set is required when using a lifetime budget.') - } - - ## we need a budget - if (missing(daily_budget) && missing(lifetime_budget)) { - stop('Either a lifetime_budget or a daily_budget must be set.') - } - if (!missing(daily_budget) && !missing(lifetime_budget)) { - stop('Only one of lifetime_budget or daily_budget should be set.') - } - if ((!missing(daily_budget) && !is.numeric(daily_budget)) || - !missing(lifetime_budget) && !is.numeric(lifetime_budget)) { - stop('Numeric value needed for the budget.') - } - if (missing(daily_budget)) { - params$lifetime_budget <- lifetime_budget - params$end_time <- end_time - } else { - params$daily_budget <- daily_budget - } - - ## promoted object based on parent campaign - campaign <- fbad_read_campaign(fbacc, campaign_id, - fields = 'objective') - if (campaign$objective %in% c('WEBSITE_CONVERSIONS', 'PAGE_LIKES', 'OFFER_CLAIMS', 'MOBILE_APP_INSTALLS', 'CANVAS_APP_INSTALLS', 'MOBILE_APP_ENGAGEMENT', 'CANVAS_APP_ENGAGEMENT') && missing(promoted_object)) { - stop(paste('A promoted object is needed when having the objective of', campaign$objective, 'in the parent ad campaign.')) - } - - ## start time if provided - if (!missing(start_time)) { - params$start_time <- start_time - } - - ## transform lists to JSON - params$targeting <- toJSON(targeting, auto_unbox = TRUE) - - ## get results - res <- fbad_request(fbacc, - path = paste0('act_', fbacc$account_id, '/adsets'), - method = "POST", - params = params) - - ## return campaign ID on success - fromJSONish(res)$id - -} +fbad_create_adset <- fbad_create_ad #' Read Ad Set details diff --git a/R/fb_campaign.R b/R/fb_campaign.R index 80222e0..80a70ea 100644 --- a/R/fb_campaign.R +++ b/R/fb_campaign.R @@ -1,56 +1,9 @@ -#' Created Ad Campaign -#' @inheritParams fbad_request -#' @param buying_type Facebook optimization algorithm to delivery, pricing, and limits -#' @param campaign_status initial status of the Ad Campaign -#' @param execution_options special execution settings passed to the API -#' @param name Ad Campaign name -#' @param objective the campaign's objective -#' @param spend_cap spend cap of the campaign +#' Create Ad Campaign +#' @inheritParams fbad_create_ad #' @return Ad Campaign id #' @export #' @references \url{https://developers.facebook.com/docs/marketing-api/reference/ad-campaign-group#Creating} -fbad_create_campaign <- function(fbacc, buying_type = c('AUCTION', 'FIXED_CPM', 'RESERVED'), - campaign_status = c('ACTIVE', 'PAUSED'), - execution_options = NULL, name, - objective = c( - 'BRAND_AWARENESS', 'CANVAS_APP_ENGAGEMENT', - 'CANVAS_APP_INSTALLS', 'CONVERSIONS', - 'EVENT_RESPONSES', 'EXTERNAL', 'LEAD_GENERATION', - 'LINK_CLICKS', 'LOCAL_AWARENESS', - 'MOBILE_APP_ENGAGEMENT', 'MOBILE_APP_INSTALLS', - 'OFFER_CLAIMS', 'PAGE_LIKES', 'POST_ENGAGEMENT', - 'PRODUCT_CATALOG_SALES', 'VIDEO_VIEWS'), - spend_cap = NULL) { - - fbacc <- fbad_check_fbacc() - if (missing(name)) - stop('A campaign name is required.') - - buying_type <- match.arg(buying_type) - - ## build params list - params <- list( - buying_type = buying_type, - objective = objective, - name = name, - execution_options = execution_options, - spend_cap = spend_cap, - objective = match.arg(objective), - campaign_status = match.arg(campaign_status)) - - ## drop NULL args - params <- as.list(unlist(params, recursive = FALSE)) - - ## get results - res <- fbad_request(fbacc, - path = paste0('act_', fbacc$account_id, '/campaigns'), - method = "POST", - params = params) - - ## return Ad Campaign ID on success - fromJSONish(res)$id - -} +fbad_create_campaign <- fbad_create_ad #' Read Ad Campaign details diff --git a/man/fbad_create_ad.Rd b/man/fbad_create_ad.Rd index f748c8f..81ec17d 100644 --- a/man/fbad_create_ad.Rd +++ b/man/fbad_create_ad.Rd @@ -2,29 +2,20 @@ % Please edit documentation in R/fb_ad.R \name{fbad_create_ad} \alias{fbad_create_ad} -\title{Create ad} +\title{Create Ad} \usage{ -fbad_create_ad(fbacc, name, adset_id, creative_id, status = c("ACTIVE", - "PAUSED"), ...) +fbad_create_ad(fbacc, ...) } \arguments{ \item{fbacc}{(optional) \code{FB_Ad_account} object, which defaults to the last returned object of \code{\link{fbad_init}}.} -\item{name}{Ad group name} - -\item{adset_id}{Ad Set id} - -\item{creative_id}{creative ID} - -\item{status}{initial status of the Ad group} - -\item{...}{further parameters passed to the Facebook API} +\item{...}{further parameters passed to the API, see below references} } \value{ ad id } \description{ -Create ad +Create Ad } \references{ \url{https://developers.facebook.com/docs/marketing-api/reference/adgroup#Creating} diff --git a/man/fbad_create_adset.Rd b/man/fbad_create_adset.Rd index c84716d..08d622d 100644 --- a/man/fbad_create_adset.Rd +++ b/man/fbad_create_adset.Rd @@ -4,47 +4,12 @@ \alias{fbad_create_adset} \title{Create Ad Set} \usage{ -fbad_create_adset(fbacc, name, optimization_goal = c("NONE", - "APP_INSTALLS", "CLICKS", "ENGAGED_USERS", "EXTERNAL", "EVENT_RESPONSES", - "IMPRESSIONS", "LINK_CLICKS", "OFFER_CLAIMS", "OFFSITE_CONVERSIONS", - "PAGE_ENGAGEMENT", "PAGE_LIKES", "POST_ENGAGEMENT", "REACH", - "SOCIAL_IMPRESSIONS", "VIDEO_VIEWS"), billing_event = c("APP_INSTALLS", - "CLICKS", "IMPRESSIONS", "LINK_CLICKS", "OFFER_CLAIMS", "PAGE_LIKES", - "POST_ENGAGEMENT", "VIDEO_VIEWS"), is_autobid = FALSE, bid_amount, - promoted_object, campaign_id, status = c("ACTIVE", "PAUSED", - "ARCHIVED", "DELETED"), daily_budget, lifetime_budget, end_time, - start_time, targeting, ...) +fbad_create_adset(fbacc, ...) } \arguments{ \item{fbacc}{(optional) \code{FB_Ad_account} object, which defaults to the last returned object of \code{\link{fbad_init}}.} -\item{name}{name of the Ad Set} - -\item{optimization_goal}{optimization goal} - -\item{billing_event}{the billing event} - -\item{is_autobid}{logical. If \code{TRUE}, autobid is set and you do not need to specify \code{bid_amount}} - -\item{bid_amount}{integer} - -\item{promoted_object}{see at \url{https://developers.facebook.com/docs/marketing-api/reference/ad-campaign/promoted-object}} - -\item{campaign_id}{parent Ad Campaign id} - -\item{status}{Ad Set status} - -\item{daily_budget}{using account currency} - -\item{lifetime_budget}{using account currency} - -\item{end_time}{UTC UNIX timestamp} - -\item{start_time}{UTC UNIX timestamp} - -\item{targeting}{list} - -\item{...}{further arguments passed to the API endpoint} +\item{...}{further parameters passed to the API, see below references} } \value{ Ad Set id diff --git a/man/fbad_create_campaign.Rd b/man/fbad_create_campaign.Rd index e97a776..2a2ed9a 100644 --- a/man/fbad_create_campaign.Rd +++ b/man/fbad_create_campaign.Rd @@ -2,37 +2,20 @@ % Please edit documentation in R/fb_campaign.R \name{fbad_create_campaign} \alias{fbad_create_campaign} -\title{Created Ad Campaign} +\title{Create Ad Campaign} \usage{ -fbad_create_campaign(fbacc, buying_type = c("AUCTION", "FIXED_CPM", - "RESERVED"), campaign_status = c("ACTIVE", "PAUSED"), - execution_options = NULL, name, objective = c("BRAND_AWARENESS", - "CANVAS_APP_ENGAGEMENT", "CANVAS_APP_INSTALLS", "CONVERSIONS", - "EVENT_RESPONSES", "EXTERNAL", "LEAD_GENERATION", "LINK_CLICKS", - "LOCAL_AWARENESS", "MOBILE_APP_ENGAGEMENT", "MOBILE_APP_INSTALLS", - "OFFER_CLAIMS", "PAGE_LIKES", "POST_ENGAGEMENT", "PRODUCT_CATALOG_SALES", - "VIDEO_VIEWS"), spend_cap = NULL) +fbad_create_campaign(fbacc, ...) } \arguments{ \item{fbacc}{(optional) \code{FB_Ad_account} object, which defaults to the last returned object of \code{\link{fbad_init}}.} -\item{buying_type}{Facebook optimization algorithm to delivery, pricing, and limits} - -\item{campaign_status}{initial status of the Ad Campaign} - -\item{execution_options}{special execution settings passed to the API} - -\item{name}{Ad Campaign name} - -\item{objective}{the campaign's objective} - -\item{spend_cap}{spend cap of the campaign} +\item{...}{further parameters passed to the API, see below references} } \value{ Ad Campaign id } \description{ -Created Ad Campaign +Create Ad Campaign } \references{ \url{https://developers.facebook.com/docs/marketing-api/reference/ad-campaign-group#Creating}