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

https://developers.facebook.com/docs/marketing-api/insights

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