Facebook Ads Insights API provides users a single consistent way to extract ads metrics from Facebook.
Use case
Users in their Data Pipeline can retrieve metrics for specified campaign, add set or ad id using Insights API.
User Stories
As a data pipeline user, I would like to be able to pull metrics for specified campaign, add set or add id, transform it and load it into my analytics data warehouse, so that I can use it for analytics
As a data pipeline user, I would like to be able to specify breakdowns, so I can group metrics by specified parameters
As a data pipeline user, I would like to be able to specify fields to pull, so I can selectively retrieve required metrics
As a data pipeline user, I would like to be able to specify filters, so I can selectively retrieve required metrics
As a data pipeline user, I would like to be able to specify date range[s], so I can pull metrics only for specified time span[s]
As a data pipeline user, I would like CDAP's Facebook Ads Insights plugins to handle API limits, by exposing required properties, so that I do not have to worry about them
Plugin Type
Batch Source
Batch Sink
Real-time Source
Real-time Sink
Action
Post-Run Action
Aggregate
Join
Spark Model
Spark Compute
Configurables
This section defines properties that are configurable for this plugin.
User Facing Name
Type
Description
Constraints
Access token
string
Access token
Object Type
select
One of Campaign, Add set, Ad or Account
Campaign ID
string
Campaign ID
Displayed only if appropriate "Object Type" selected
Ad Set ID
string
Ad Set ID
Displayed only if appropriate "Object Type" selected
Ad ID
string
Ad ID
Displayed only if appropriate "Object Type" selected
Account ID
string
Account ID
Displayed only if appropriate "Object Type" selected
Level
select
Level of request
Fields
multi-select
List of fields to pull
Breakdown
select
List of breakdowns
Additional Breakdown
select
List of additional breakdowns
Can be ignored if primary breakdown does not support additional breakdown
Filtering
function-dropdown-with-alias
List of per-field filters
Time Range
select
Relative time range
Sorting
select
Field to sort results
Sorting Direction
radio-group
Sorting direction - ascending or descending
For “Filter” and “Time Ranges” string formats see facebook doc, “filtering” and “time_ranges” parameters respectively.
Design / Implementation Tips
Plugin will be implemented using official facebook-java-business-sdk, authentication will be performed using app secret and access token. Output schema must be automatically generated from selected fields and breakdowns.
Output schema completely based on Fields items. Fields that holds action or list of actions is a nullable action record or nullable array of records respectively; other fields are nullable strings.