tap-facebook - Meltano Version

This is a Meltano maintained fork of tap-facebook.

Check CHANGELOG-Meltano.md for the additional updates introduced in this project and the version of tap-facebook used.

tap-facebook

This is a Singer tap that produces JSON-formatted data following the Singer spec.

This tap:

• Pulls raw data from the Facebook Marketing API
• Extracts the following resources from Facebook for a one Ad account:
  • Ad Creatives
  • Ads
  • Ad Sets
  • Campaigns
  • Ads Insights
    • Breakdown by age and gender
    • Breakdown by country
    • Breakdown by placement and device
• Outputs the schema for each resource
• Incrementally pulls data based on the input state

Quick start

Install

We recommend using a virtualenv:

> virtualenv -p python3 venv
> source venv/bin/activate
> pip install tap-facebook

Create a Facebook Ads App

To use the Facebook Marketing API, you must create a Facebook Ads app. By creating a Facebook Ads app you will be able to use the Marketing API. Create an app

Facebook has three access levels for the Marketing API. You can use this Tap with all three levels. Learn more about these levels in Facebook documentation. https://developers.facebook.com/docs/marketing-api/access

Get an access token

The Tap will need to use an access token to make authenticated requests to the Marketing API.

Create the config file

The Facebook Tap will use an access token generated by the OAuth process.

Required Parameters:

• start_date - an initial date for the Tap to extract data
• account_id - The Facebook Ad account id use when extracting data
• access_token - Token generated by Facebook OAuth handshake

The following is an example of the required configuration

{"start_date":"",
"account_id":"",
"access_token":""}

Optional Parameters:

• end_date - The end date for Ads Insights (default: The date you run the tap)
• insights_buffer_days - How many days to start extracting Ads Insights before the start_date (default: 28)
• result_return_limit - How many results will be requested per call (default: 100)

The following is an example of a full configuration

{
  # Required Parameters
  "account_id":"XXXX",
  "access_token":"XXXX",

  "start_date":"2019-12-09T00:00:00Z",

  # Optional Parameters
  "end_date":"2019-12-19T00:00:00Z",
  "insights_buffer_days":0,
  "result_return_limit":50
}

Create a properties file

The properties file will indicate what streams and fields to replicate from the Facebook Marketing API. The Tap takes advantage of the Singer best practices for schema discovery and property selection.

[Optional] Create the initial state file

You can provide JSON file that contains a date for the streams to force the application to only fetch data newer than those dates. If you omit the file it will fetch all data for the selected streams.

{
 "bookmarks":
 {
  "ads": {"updated_time": "2019-12-09T02:07:11-07:00"},
  "adsets": {"updated_time": "2019-12-08T21:54:03-07:00"},
  "campaigns": {"updated_time": "2019-12-20T09:37:49-07:00"},
  "ads_insights": {"date_start": "2019-12-19T00:00:00+00:00"},
  "ads_insights_age_and_gender": {"date_start": "2019-12-19T00:00:00+00:00"},
  "ads_insights_country": {"date_start": "2019-12-19T00:00:00+00:00"},
  "ads_insights_platform_and_device": {"date_start": "2019-12-19T00:00:00+00:00"},
  "ads_insights_region": {"date_start": "2019-12-19T00:00:00+00:00"},
  "ads_insights_dma": {"date_start": "2019-12-19T00:00:00+00:00"}
 }
}

Run the Tap

tap-facebook -c config.json -p properties.json -s state.json

---

Copyright © 2018 Stitch