The Data Connector for Facebook Ads Insights (previous known as Facebook Ads Reporting) enables the import of data from your Facebook Advertising campaign results.

This topic includes:

Prerequisites

  • Basic knowledge of Treasure Data

  • Basic knowledge of Facebook Marketing API, in particular Ads Insights API.

Use TD Console

Create a new connection

Go to Treasure Data Connections and search and select Facebook Ads. The following dialog opens.


We support two Authentication Methods:

  • OAuth

  • Access Token

Using OAuth

Select an existing OAuth connection for Facebook or select the link under OAuth connection to create a new one.


Create a new OAuth connection

Log into your Facebook account in a popup window:


And grant access to the Treasure Data app.

You will be redirected back to Treasure Data Connections. Repeat the first step (Create a new connection) and choose your new OAuth connection.

Using an Access Token

See Obtain Facebook Token under Section 3 to create an access token.

Create a new transfer

After creating the connection, you are automatically taken to the Authentications tab. Look for the connection you created and select New Source.

The following dialog opens.

Edit the following details:

  • Ad Account ID

  • Data Level

  • Import Metadata for Related Objects

  • Import all Insights or Insights Fields

  • Breakdowns

  • Filtering

  • Action Attribution Windows

  • Start and End Date or Incremental

  • Reporting Period

Details on these parameters are as follows:


Ad Account ID

Add your Ad Account ID, which you can find as described here.

Data Level

The Ads object level. Available options are Campaign, Ad Set, and Ad.

Import Metadata for Related Objects

By default, Import metadata for related objects is unchecked and the connector imports only fundamental metadata fields: created_time, effective_status, status.

By checking it, you can specify related objects or individual metadata fields to import.

Related Edges

Select All Metadata Fields to import all related edges. You can select which edges to import by adding each edge in Fetch Metadata.

Metadata Fields

Metadata fields associated with the Ads objects. Selecting Individual Metadata Fields allows you to import only the fields you want. Select fields under Metadata Fields.

You can also access Ads object’s edges by using edge{field1, field2…}.

Insights Fields

Insight fields provide data about the performance of your campaign.

By default, Import all insights fields are checked.

You can uncheck Import all insights fields to select specific fields.


The Insights fields date_start and date_stop are added by default, if not explicitly set. Insight values might be empty depending on the state of Ads object. No errors are generated if the fields do not contain values.

Breakdowns

Breakdowns are used to capture Ads Insights responses that are grouped into different sets or cohorts. Supported breakdowns are:

  • age

  • gender

  • country

  • region

  • hourly_stats_aggregated_by_advertiser_time_zone


Filtering

Filters on the reported Insights data. Format: Field —> Operator —> Value, the action_type supports IN operator with comma separate values, i.e. post_like, like


Action Attribution Windows

Determines the attribution window for the actions. Supported values are:

  • 1d_view

  • 7d_view

  • 28d_view

  • 1d_click

  • 7d_click

  • 28d_click

Defaults values are: ([“1d_view”,“28d_click”]) if not explicitly set.

Incremental Import and Start Date

Specify if you want Incremental import and Start Date.

By enabling incremental, you can define the duration (in days) of each incremental load. The default is 1 day. If Start Date is not specified, then the default is set to past 30 days.

The data that is fetched includes data that is available up until midnight of the previous night.

Reporting Period

After you pick a reporting period by using Start Date and End Date, you may choose to get results for the whole period or get results for smaller time slices. If you select All Days, then you get one result set for the whole period. If you specify monthly, then you get one result set for each calendar month in the given period.

Or you can get one result set for each N-day period specified by selecting In Days. You can specify the number of days from 1 to 90.


After you complete specifying parameters, select Next. You then see a Preview of your data similar to the dialog below. Select Next. Select Preview while Importing Data if you cannot move beyond Preview.

Select the database and table where you want to transfer the data, as shown in the following dialog:


Specify the schedule of the data transfer using the dialog below and select Start Transfer.

You see the new data transfer in progress listed under the My Input Transfers tab and a corresponding job is listed in the Jobs section.

Now, you are ready to start analyzing your data!

Use Command Line

Install TD Toolbelt

Install the newest TD Toolbelt.

Obtain Facebook Token

Facebook provides 3 types of tokens. We recommend using the never-expiring Page Access Token. You can also use User Token but it expires after 2 months even if it is extended. It is not batch-friendly.

The steps that describe how to get the never-expiring Page Access Token are here: https://www.rocketmarketinginc.com/blog/get-never-expiring-facebook-page-access-token/

Prepare Configuration and Preview Data

We don't need to run td connector:guess for the facebook_ads_reporting connector.

Prepare config.yml as follows:

in:
  type: "facebook_ads_reporting"
  ad_account_id: '[your ad account id]'
  access_token: "[your Facebook access token]"
  data_level: ad
  fields:
    - clicks
    - impressions
  metadata_import: all
  metadata_edge:
    - adrules_governed
    - copies
    - keywordstats
    - leads
    - targetingsentencelines
  filtering:
    - {field : "clicks", operator: "GREATER_THAN", value: 10}
   - {field : "impressions", operator: "GREATER_THAN", value: 200}
out:
  mode: append

For more details, see modes for out plugin.

You can see a preview of the data using the preview command.

$ td connector:preview config.yml
+-----------------+---------------------+---------------+----------------+------------------+----------------------+---------------+------------------------------------+------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------+---------------------------+-------------------------+------------------+-------------------------+-------------+--------------------+-------------------------+--------------------------------+--------------------+---------------------------+--------------+----------------+----------------------+-----------------------+---------------------+----------------------------------------+-------------------------+---------------------------------+-----------------------------+--------------------------------+----------------------------------------+----------------------------+-----------------------------------+------------+-------------------+------------------+-----------------+-----------------------------+------------+-----------------+----------+------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------+-------------------------------+-------------------------------------------+-------------------------------------------+--------------------------------------+---------------------------+------------------------------+---------------------------+---------------------------+--------------------------------------------------------+---------------------------+
| account_id:long | account_name:string | ad_id:long    | ad_name:string | campaign_id:long | campaign_name:string | adset_id:long | adset_name:string                  | objective:string | actions:json                                                                                                                                                                                         | total_actions:long | total_unique_actions:long | total_action_value:long | impressions:long | social_impressions:long | clicks:long | social_clicks:long | unique_impressions:long | unique_social_impressions:long | unique_clicks:long | unique_social_clicks:long | spend:double | frequency:long | deeplink_clicks:long | app_store_clicks:long | website_clicks:long | cost_per_inline_post_engagement:double | inline_link_clicks:long | cost_per_inline_link_click:long | inline_post_engagement:long | unique_inline_link_clicks:long | cost_per_unique_inline_link_click:long | inline_link_click_ctr:long | unique_inline_link_click_ctr:long | reach:long | social_reach:long | ctr:double       | unique_ctr:long | unique_link_clicks_ctr:long | cpc:double | cpm:double      | cpp:long | cost_per_total_action:string | cost_per_action_type:json                                                                                                                                                                                                                            | cost_per_unique_click:long | estimated_ad_recall_rate:long | estimated_ad_recall_rate_lower_bound:long | estimated_ad_recall_rate_upper_bound:long | cost_per_estimated_ad_recallers:long | canvas_avg_view_time:long | canvas_avg_view_percent:long | date_start:timestamp      | date_stop:timestamp       | hourly_stats_aggregated_by_advertiser_time_zone:string | time:timestamp            |
+-----------------+---------------------+---------------+----------------+------------------+----------------------+---------------+------------------------------------+------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------+---------------------------+-------------------------+------------------+-------------------------+-------------+--------------------+-------------------------+--------------------------------+--------------------+---------------------------+--------------+----------------+----------------------+-----------------------+---------------------+----------------------------------------+-------------------------+---------------------------------+-----------------------------+--------------------------------+----------------------------------------+----------------------------+-----------------------------------+------------+-------------------+------------------+-----------------+-----------------------------+------------+-----------------+----------+------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------+-------------------------------+-------------------------------------------+-------------------------------------------+--------------------------------------+---------------------------+------------------------------+---------------------------+---------------------------+--------------------------------------------------------+---------------------------+
| 2xxxxxxxx       | "Foo Bar"           | 6xxxxxxxxxxxx | "FooBar"       | 6xxxxxxxxxxxx    | "Campaign"           | 6xxxxxxxxxxxx | "Campaign  (Web Remarketing)"      | "VIDEO_VIEWS"    | "[{\"action_type\":\"video_view\",\"value\":5},{\"action_type\":\"page_engagement\",\"value\":5},{\"action_type\":\"post_engagement\",\"value\":5}]"                                                 | 5                  | 0                         | 0                       | 25               | 0                       | 0           | 0                  | 0                       | 0                              | 0                  | 0                         | 0.23         | 0              | 0                    | 0                     | 0                   | 0.0                                    | 0                       | 0                               | 0                           | 0                              | 0                                      | 0                          | 0                                 | 0          | 0                 | 0.0              | 0               | 0                           | 0.0        | 9.2             | 0        | "0.046"                      | "[{\"action_type\":\"video_view\",\"value\":0.046},{\"action_type\":\"page_engagement\",\"value\":0.046},{\"action_type\":\"post_engagement\",\"value\":0.046}]"                                                                                     | 0                          | 0                             | 0                                         | 0                                         | 0                                    | 0                         | 0                            | "2016-07-28 07:00:00 UTC" | "2016-07-28 07:00:00 UTC" | "19:00:00 - 19:59:59"                                  | "2016-07-29 02:00:00 UTC" |
| 2xxxxxxxx       | "Foo Bar"           | 6xxxxxxxxxxxx | "FooBar"       | 6xxxxxxxxxxxx    | "Campaign"           | 6xxxxxxxxxxxx | "Campaign  (Web Remarketing)"      | "VIDEO_VIEWS"    | "[{\"action_type\":\"video_play\",\"value\":1},{\"action_type\":\"video_view\",\"value\":15},{\"action_type\":\"page_engagement\",\"value\":15},{\"action_type\":\"post_engagement\",\"value\":15}]" | 15                 | 0                         | 0                       | 114              | 1                       | 1           | 0                  | 0                       | 0                              | 0                  | 0                         | 0.32         | 0              | 0                    | 0                     | 0                   | 0.0                                    | 0                       | 0                               | 0                           | 0                              | 0                                      | 0                          | 0                                 | 0          | 0                 | 0.87719298245614 | 0               | 0                           | 0.32       | 2.8070175438596 | 0        | "0.021333333333333"          | "[{\"action_type\":\"video_play\",\"value\":0.32},{\"action_type\":\"video_view\",\"value\":0.021333333333333},{\"action_type\":\"page_engagement\",\"value\":0.021333333333333},{\"action_type\":\"post_engagement\",\"value\":0.021333333333333}]" | 0                          | 0                             | 0                                         | 0                                         | 0                                    | 0                         | 0                            | "2016-07-28 07:00:00 UTC" | "2016-07-28 07:00:00 UTC" | "20:00:00 - 20:59:59"                                  | "2016-07-29 03:00:00 UTC" |
| 2xxxxxxxx       | "Foo Bar"           | 6xxxxxxxxxxxx | "FooBar"       | 6xxxxxxxxxxxx    | "Campaign"           | 6xxxxxxxxxxxx | "Campaign  (Web Remarketing)"      | "VIDEO_VIEWS"    | "[{\"action_type\":\"video_play\",\"value\":1},{\"action_type\":\"video_view\",\"value\":87},{\"action_type\":\"page_engagement\",\"value\":87},{\"action_type\":\"post_engagement\",\"value\":87}]" | 87                 | 0                         | 0                       | 452              | 9                       | 4           | 0                  | 0                       | 0                              | 0                  | 0                         | 1.95         | 0              | 0                    | 0                     | 0                   | 0.4875                                 | 0                       | 0                               | 4                           | 0                              | 0                                      | 0                          | 0                                 | 0          | 0                 | 0.88495575221239 | 0               | 0                           | 0.4875     | 4.3141592920354 | 0        | "0.022413793103448"          | "[{\"action_type\":\"video_play\",\"value\":1.95},{\"action_type\":\"video_view\",\"value\":0.022413793103448},{\"action_type\":\"page_engagement\",\"value\":0.022413793103448},{\"action_type\":\"post_engagement\",\"value\":0.022413793103448}]" | 0                          | 0                             | 0                                         | 0                                         | 0                                    | 0                         | 0                            | "2016-07-28 07:00:00 UTC" | "2016-07-28 07:00:00 UTC" | "21:00:00 - 21:59:59"                                  | "2016-07-29 04:00:00 UTC" |
| 2xxxxxxxx       | "Foo Bar"           | 6xxxxxxxxxxxx | "FooBar"       | 6xxxxxxxxxxxx    | "Campaign"           | 6xxxxxxxxxxxx | "Campaign  (Web Remarketing)"      | "VIDEO_VIEWS"    | "[{\"action_type\":\"video_view\",\"value\":3},{\"action_type\":\"page_engagement\",\"value\":3},{\"action_type\":\"post_engagement\",\"value\":3}]"                                                 | 3                  | 0                         | 0                       | 9                | 1                       | 0           | 0                  | 0                       | 0                              | 0                  | 0                         | 0.01         | 0              | 0                    | 0                     | 0                   | 0.0                                    | 0                       | 0                               | 0                           | 0                              | 0                                      | 0                          | 0                                 | 0          | 0                 | 0.0              | 0               | 0                           | 0.0        | 1.1111111111111 | 0        | "0.0033333333333333"         | "[{\"action_type\":\"video_view\",\"value\":0.0033333333333333},{\"action_type\":\"page_engagement\",\"value\":0.0033333333333333},{\"action_type\":\"post_engagement\",\"value\":0.0033333333333333}]"                                              | 0                          | 0                             | 0                                         | 0                                         | 0                                    | 0                         | 0                            | "2016-07-28 07:00:00 UTC" | "2016-07-28 07:00:00 UTC" | "22:00:00 - 22:59:59"                                  | "2016-07-29 05:00:00 UTC" |
| 2xxxxxxxx       | "Foo Bar"           | 6xxxxxxxxxxxx | "FooBar"       | 6xxxxxxxxxxxx    | "Campaign"           | 6xxxxxxxxxxxx | "Campaign  (Web Remarketing)"      | "VIDEO_VIEWS"    | "[{\"action_type\":\"video_view\",\"value\":40},{\"action_type\":\"page_engagement\",\"value\":40},{\"action_type\":\"post_engagement\",\"value\":40}]"                                              | 40                 | 0                         | 0                       | 230              | 8                       | 0           | 0                  | 0                       | 0                              | 0                  | 0                         | 1.16         | 0              | 0                    | 0                     | 0                   | 0.0                                    | 0                       | 0                               | 0                           | 0                              | 0                                      | 0                          | 0                                 | 0          | 0                 | 0.0              | 0               | 0                           | 0.0        | 5.0434782608696 | 0        | "0.029"                      | "[{\"action_type\":\"video_view\",\"value\":0.029},{\"action_type\":\"page_engagement\",\"value\":0.029},{\"action_type\":\"post_engagement\",\"value\":0.029}]"                                                                                     | 0                          | 0                             | 0                                         | 0                                         | 0                                    | 0                         | 0                            | "2016-07-28 07:00:00 UTC" | "2016-07-28 07:00:00 UTC" | "23:00:00 - 23:59:59"                                  | "2016-07-29 06:00:00 UTC" |                                                                               | 0                          | 0                             | 0                                         | 0                                         | 0                                    | 0                         | 0                            | "2016-07-29 07:00:00 UTC" | "2016-07-29 07:00:00 UTC" | "16:00:00 - 16:59:59"                                  | "2016-07-29 23:00:00 UTC" |
| 2xxxxxxxx       | "Foo Bar"           | 6xxxxxxxxxxxx | "FooBar"       | 6xxxxxxxxxxxx    | "Campaign"           | 6xxxxxxxxxxxx | "Campaign  (Web Remarketing)"      | "VIDEO_VIEWS"    | "[{\"action_type\":\"video_view\",\"value\":20},{\"action_type\":\"page_engagement\",\"value\":20},{\"action_type\":\"post_engagement\",\"value\":20}]"                                              | 20                 | 0                         | 0                       | 126              | 0                       | 1           | 0                  | 0                       | 0                              | 0                  | 0                         | 2.35         | 0              | 0                    | 0                     | 0                   | 2.35                                   | 0                       | 0                               | 1                           | 0                              | 0                                      | 0                          | 0                                 | 0          | 0                 | 0.79365079365079 | 0               | 0                           | 2.35       | 18.650793650794 | 0        | "0.1175"                     | "[{\"action_type\":\"video_view\",\"value\":0.1175},{\"action_type\":\"page_engagement\",\"value\":0.1175},{\"action_type\":\"post_engagement\",\"value\":0.1175}]"                                                                                  | 0                          | 0                             | 0                                         | 0                                         | 0                                    | 0                         | 0                            | "2016-07-29 07:00:00 UTC" | "2016-07-29 07:00:00 UTC" | "17:00:00 - 17:59:59"                                  | "2016-07-30 00:00:00 UTC" |
+-----------------+---------------------+---------------+----------------+------------------+----------------------+---------------+------------------------------------+------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------+---------------------------+-------------------------+------------------+-------------------------+-------------+--------------------+-------------------------+--------------------------------+--------------------+---------------------------+--------------+----------------+----------------------+-----------------------+---------------------+----------------------------------------+-------------------------+---------------------------------+-----------------------------+--------------------------------+----------------------------------------+----------------------------+-----------------------------------+------------+-------------------+------------------+-----------------+-----------------------------+------------+-----------------+----------+------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------+-------------------------------+-------------------------------------------+-------------------------------------------+--------------------------------------+---------------------------+------------------------------+---------------------------+---------------------------+--------------------------------------------------------+---------------------------+
15 rows 

Execute Load Job

Submit the load job. It may take a couple of hours depending on the size of the data.

Facebook connector provides time column automatically. You don’t have to specify the --time-column option.

$ td connector:issue load.yml --database td_sample_db --table td_sample_table


Scheduled Execution

You can schedule a periodic Data Connector execution for incremental Facebook Ads Insights data using our high availability scheduler. By using this feature, you no longer need a cron daemon on your local data center.

For the first scheduled import, the Data Connector for Facebook Ads Insights imports all of your ad data.

On the second and subsequent run of the scheduled import, only data that is newer than the last load is imported.

Create the Schedule

A new schedule can be created using the td connector:create command. The following are required:

  • name of the schedule

  • cron-style schedule

  • database and table where their data will be stored

  • Data Connector configuration file

$ td connector:create \
    daily_import \
    "10 0 * * *" \
    td_sample_db \
    td_sample_table \
    config.yml

The `cron` parameter also accepts three special options: `@hourly`, `@daily` and `@monthly`.

By default, schedule is setup in UTC timezone. You can set the schedule in a timezone using -t or --timezone option. `--timezone` option only supports extended timezone formats like 'Asia/Tokyo', 'America/Los_Angeles' etc. Timezone abbreviations like PST, CST are *not* supported and may lead to unexpected schedules.

List All Schedules

You can see the list of all current schedule entries with the command td connector:list.

$ td connector:list
+--------------+------------+----------+-------+--------------+-----------------+----------------------------+
| Name         | Cron       | Timezone | Delay | Database     | Table           | Config                     |
+--------------+------------+----------+-------+--------------+-----------------+----------------------------+
| daily_import | 10 0 * * * | UTC      | 0     | td_sample_db | td_sample_table | {"in"=>{"type"=>"fac", ... |
+--------------+------------+----------+-------+--------------+-----------------+----------------------------+

Show Schedule Settings And History

td connector:show shows the execution settings of a schedule entry.

% td connector:show daily_import
Name     : daily_import
Cron     : 10 0 * * *
Timezone : UTC
Delay    : 0
Database : td_sample_db
Table    : td_sample_table
Config
---
in:
  type: "facebook_ads_reporting"
  ad_account_id: '[your ad account id]'
  access_token: "[your Facebook access token]"
  data_level: ad
  fields:
    - clicks
    - impressions
  metadata_import: all
  metadata_edge:
    - adrules_governed
    - copies
    - keywordstats
    - leads
    - targetingsentencelines
  filtering:
    - {field : "clicks", operator: "GREATER_THAN", value: 10}
    - {field : "impressions", operator: "GREATER_THAN", value: 200}
out:
  mode: append

td connector:history shows the execution history of a schedule entry. To investigate the results of each individual run, use td job <jobid>.

% td connector:history daily_import
+--------+---------+---------+--------------+-----------------+----------+---------------------------+----------+
| JobID  | Status  | Records | Database     | Table           | Priority | Started                   | Duration |
+--------+---------+---------+--------------+-----------------+----------+---------------------------+----------+
| 578066 | success | 10000   | td_sample_db | td_sample_table | 0        | 2015-04-18 00:10:05 +0000 | 160      |
| 577968 | success | 10000   | td_sample_db | td_sample_table | 0        | 2015-04-17 00:10:07 +0000 | 161      |
| 577914 | success | 10000   | td_sample_db | td_sample_table | 0        | 2015-04-16 00:10:03 +0000 | 152      |
| 577872 | success | 10000   | td_sample_db | td_sample_table | 0        | 2015-04-15 00:10:04 +0000 | 163      |
| 577810 | success | 10000   | td_sample_db | td_sample_table | 0        | 2015-04-14 00:10:04 +0000 | 164      |
| 577766 | success | 10000   | td_sample_db | td_sample_table | 0        | 2015-04-13 00:10:04 +0000 | 155      |
| 577710 | success | 10000   | td_sample_db | td_sample_table | 0        | 2015-04-12 00:10:05 +0000 | 156      |
| 577610 | success | 10000   | td_sample_db | td_sample_table | 0        | 2015-04-11 00:10:04 +0000 | 157      |
+--------+---------+---------+--------------+-----------------+----------+---------------------------+----------+
8 rows in set

Delete Schedule

td connector:delete removes the schedule.

$ td connector:delete daily_import

Configuration

See the following table for more details on available modes.

Option name

Description

Type

Required?

Default value

ad_account_id

Ad account ID of access_token

string

yes

access_token

Access Token. We recommend using the non-expiring token (see the next section)

string

yes

app_secret

If set, appsecret_proof parameter is used to access API

string

optional

metadata_import

Import related edges or individual metadata fields? Available options are all and individual

string

optional

individual

metadata_edge

Related edges to import. Only effective when metadata_import is all, see related edges.

array

optional

metadata_fields

What metadata fields you want to obtain for a given object. Review available fields.

array

optional

created_time, status, effective_status

fields

What fields you want to obtain for insights. Review available fields.

array

optional

breakdowns

See breakdowns for details.

string

optional

filtering

See filter for details.

array

optional

action_attribution_windows

Determines the attribution window for the actions. For example, 28d_click Means the API returns all actions that happened 28 days after someone clicked on the ad.

array

optional

retry_limit

Trying maximum retry times

integer

optional

5

retry_initial_wait_sec

Wait seconds for exponential backoff initial value

integer

optional

10

last_fetched_at

Only imports data since this date, it is 30 days from today if not specified, ie. (today - 30 days). Recommended formats: %m/%d/%Y or %Y-%m-%dT%H:%M:%S.%L%Z

string

optional

incremental

true for generate “config_diff” with embulk run -c config.diff

bool

optional

true

duration

# of days from start date to pull in insights data. See Appendix B for more details.

integer

optional

1

time_increment

If it is an integer, it is the number of days from 1 to 90. After you pick a reporting period by using last_fetched_at and last_fetched_until, you might choose to have the results for the whole period, or have results for smaller time slices. If “all_days” is used, it means one result set for the whole period. If “monthly” is used, you get one result set for each calendar month in the given period. Or you can have one result set for each N-day period specified by this parameter. See Appendix B for more details.

string

optional

1

last_fetched_until

Only imports data until this date, today if not specified. Recommended formats: see last_fetched_at. See Appendix C for more details.

string

optional

add_time_column

If true, “time” column is added automatically, based on date_stop value of insights, otherwise, “time” column is added by upload_time

bool

optional

true

data_level

Obtain data level. Facebook insights level: Campaign –> Adset –> Ad. Available options are “campaign”, “adset”, “ad”, or “ad_creative”.

string

optional

“ad”

api_version

Use Facebook API version. Default is v3.2. If specified version is older than v3.1 (deprecated), plugin uses “v3.2”

string

optional

“v3.2”

limit_per_page

Number of records per page, reduce this value when you encounter error message “Please reduce the amount of data you’re asking for, then retry your request”

integer

optional

100000


Supported Related Edges

Campaign

- ad_studies
- adrules_governed
- ads
- adsets
- copies

AdSet

- activities
- ad_studies
- adrules_governed
- ads
- copies
- targetingsentencelines

Ad

- adrules_governed
- copies
- keywordstats
- leads
- targetingsentencelines


Appendix

Modes for out plugin

You can specify file import mode in out section of seed.yml.

append (default)

This is the default mode and records are appended to the target table.

in:
  ...
out:
  mode: append

replace (In td 0.11.10 and later)

This mode replaces data in the target table. Any manual schema changes made to the target table remain intact with this mode.

in:
  ...
out:
  mode: replace

Duration and time_increment

When to use duration?

  • The duration has effect only when incremental = true

  • The duration is used to compute time range for your request, based on last_fetched_at, for example, if last_fetched_at = 02/01/2017 and duration = 2, you’re requesting for a time range of: 02/01/2017 → 02/02/2017

Directly translated to Facebook request parameters:

.time_range({"since":"2017-02-01","until":"2017-02-02"})
  • There is no breakdown behavior when you use this parameter. It returns insight values for the whole time range.

  • Note: When no last_fetched_at is specified, it is 30 days from today, ie. (today – 30 days)

When to use time_increment?

  • time_increment is used when you want to break down insights data by a number of days. The results are easiest to recognize without incremental mode and duration.

Example:

incremental: false
last_fetched_at: 03/01/2017
last_fetched_until: 03/31/2017
time_increment: 1

Using the preceding configuration, you can import the entire month of March 2017 in one run, and still have it break down daily.

duration and time_increment differences

  • duration is used for incremental mode

  • time_increment is an official Facebook parameter

  • Important note: If both duration and time_increment are available (which is default), duration will have higher priority than time_increment when its value is less than time_increment. With that being said, you can’t have breakdown data per 2 days (time_increment = 2) when duration = 1, result will be 1-day data. In the other hand, you can perfectly break down data daily (time_increment = 1) for a 2-day duration (duration = 2).

When to use last_fetched_until?

  • last_fetched_until is optional, and its only usage is to limit imported data to an end date.

Example: you have a job to import March 2017, and it’s scheduled to run repeatedly to get daily data. Therefore, you could use the following configuration to achieve it:

incremental: true
duration: 1
last_fetched_at: 03/01/2017
last_fetched_until: 03/31/2017

Note: As you can see, you can simulate time_increment effect by using duration and run the job repeatedly, but it will cost you more requests (Request Rate Limit will occur faster).

  • If your scheduled job (eventually) exceeds configured last_fetched_until, an empty result is returned.

Data Connector schema change in the July 10 2018 release

Due to recent changes of Facebook API, Data Connector has updated.

Before the change: Some fields were added but the output schema was missing some columns because the value was empty.

After the change: Some new columns are added but might not contain values. The output schema will be combined from the input configuration and mandatory fields.

The mandatory fields and implicitly added columns are:

  • Metadata fields

    • created_time

    • effective_status

    • status

  • Insights Fields

    • date_start

    • date_stop

Invalid `fields` that might have been skipped in previous updates will now result in errors after update. See the `Fields` section of following links for complete references for Insights Fields and Metadata fields:


  • No labels