This article will help you use the Google Sheets AdStage Add-on, specifically for Facebook Real-time data. By design, below is a collection of parameters that you can add to functions.

For information about the installation of the add-on and sample templates go here

Getting Started

To start off you'll need two formulas. 

1. Create a formula to call in your Account ID's, also known as Entity ID's. Place this formula next to the space you want your performance data. A best practice is far off to the right, potentially cell 02. 

=accounts("last week", {"name", "entity_id", "spend"},{"networks","facebook"})

This formula will gather a list of your entity ID's which your next formula will target.

Note: the date range and spend are needed in the formula to gather your Entity ID's, but won't provide much value for you, as your main performance data table will be built from your next formula.

2. Create your main formula. Typically this formula is started in the main view of a sheet, somewhere around cell A2. 

To ensure your data is pulled from the Facebook endpoint you need to add {"provider", "facebook"}, {"targets", P2}

This addition tells the formula to pull from the facebook endpoint, {"provider", "facebook"}, and target/use the account in cell P2, {"targets", P2}. 

P2 should reference where your Entity ID is for the account you'd like to target. If you set up you first formula in 02, the Entity ID would be found in P2.

=accounts("last week", {"name", "spend"}, {"provider", "facebook"}, {"targets", P2})   
=campaigns("this month", {"name", "spend"}, {"provider", "facebook"}, {"targets", P2})  
=adGroups("this year", {"name", "spend"}, {"provider", "facebook"}, {"targets", P2})  
=ads("2015-07-04..2015-07-05", {"name", "spend"}, {"provider", "facebook"}, {"targets", P2})  

The Basics

Start with an entity level

Start with what entity level you want to target. Use the " = " and then state the entity level. Options are accounts, campaigns, adgroups, and ads.

=accounts("last week", {"name", "spend"}, {"provider", "facebook"}, {"targets", P2})   
=campaigns("this month", {"name", "spend"}, {"provider", "facebook"}, {"targets", P2}) 

Insert parameters to your function

Timeframes

The functions allow both relative ranges (phrases like "last 30 days") and specific date ranges. When specifying specific date ranges you can use a cell range of dates (ex:D1:E1) or a date range string of format: "2016-02-28..2016-03-03"

Specify columns

Functions must be supplied the column names to fetch data for. You can make this a list (ex: {"name", "spend"}) or a range of cells - usually your header row (ex: A1:H1)

Note: You can find a list of available column names/KPI's here.

*Use additional Options

Additional options are added to the end of any of the supported custom functions in a list. You may just tack them on as additional arguments, wrap in a list, or even use a range of cells for configuration as the final parameter (ex: =accounts("this week", {"spend" "name"}, J7:K12))

Available Options

"limit". Set how many rows to return. Safe max is 1000 due to limits with custom functions timing out. If you do not specify, a limit we default to 25 rows. Example:
=accounts("this week", A1:H1, {"limit", 100}, {"provider", "facebook"}, {"targets", P2})

"timeframes".  Filter down to certain timeframes, such as "today", "this_month", "last_year". Example:
=campaigns("this week", A1:H1, {"statuses", "all_with_deleted"}, {"provider", "facebook"}, {"targets", P2})

timeframes:

  • Today: this 1 day
  • Yesterday: last 1 day
  • Last 3 days: last 3 days
  • Last 3 days, including today: this 3 days
  • This month: this month
  • This month and last month: this 2 months
  • Last month: last month
  • Last month and the month before it: last 2 months
  • This year: this year
  • This year and last year: this 2 years
  • Last year: last year
  • Year to date: this year, up to end of yesterday
  • Year to now: this year, including today’s data (last sync)
  • Month/week to date/note

notes about timeframes:
THIS vs. LAST
If you want to include today, use THIS x days/weeks/months/years. If you don’t want to include today use LAST x days/weeks/months/years.

"...to date" vs. "...to now" If you want to look include the last full day of data use, "...to date". If you want to include today's data (last import sync) use, "...to now". 

"relative_to". When using relative timeframes like "this month", specifies what day you're asking for (defaults to today). Example to pull data for June 2016 specifically without building a date range:
=campaigns("this month", {"spend", "date", "campaign name"}, {"relative_to", "2016-06-18"}, {"provider", "facebook"}, {"targets", P2}) 

"aggregate_by". Get back data broken down by day, week, or month instead of totals. Use the special column name "Date". Example:
=campaigns("this week", {"spend", "date", "campaign name"}, {"aggregate by", "day"}, {"provider", "facebook"}, {"targets", P2})

"group_by". Get back data aggregated by a common column - currently only "network" is reliably supported, but status or currency_code could be used as well. Example:
=campaigns("this week", {"spend", "date", "campaign name"}, {"group by", "network"}, {"provider", "facebook"}, {"targets", P2})

"filters". Filters to apply to your data, such as campaign name matching (ex: "campaign name ~ Brand" for campaign names containing brand) and spend filtering (ex: "spend > 0"). Combine multiple filters with a semicolon: ";" Example:
=campaigns("this week", A1:H1, {"filters", "spend > 0; campaign name ~ Brand"}, {"provider", "facebook"}, {"targets" P2})

Valid filters are:

  • >  (greater than)
  • < (less than)
  • ~ (text match)
  • !~ (text does not match)
  • = (text or number is exactly)

Looking for cross-network parameters?  Check out our other FAQ, Click the button below!

Did this answer your question?