Facebook Ads
Yevhenii Chekanskyi
Bhooshan Mogal
Introduction
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.
Reference
Table of Contents
Checklist
- User stories documented
- User stories reviewed
- Design documented
- Design reviewed
- Feature merged
- Examples and guides
- Integration tests
- Documentation for feature
- Short video demonstrating the feature