AdWords Scripts For Every Level: Part 1, Learning How To Read Scripts

AdWords Scripts are incredibly powerful tools for paid search, but since many of us don’t come from coding backgrounds they can also be intimidating. This is the first in a three-part series covering tips for beginner, intermediate and advanced-level Scripts users.

Inspiration for this article came from a presentation I saw given by AdWords Community Contributor, Jon Gritton, at the AdWords Community Summit in Mountain View this fall. Gritton’s deck can be seen in full here.

Yes, there are lots of pre-baked scripts out there to copy and paste into your account. But, even with these ready-made scripts, a little customization can go a long way. It just requires some basic understanding of what each piece of a script does. In this first installment, we’re going to cover the very basics. Once you understand the pieces that make up a script and what they do, you’ll be well on your way to making them work for you.

First, we’ll look at each piece in detail, then put it all together below.

Breaking It Down

Scripts are pieces of standard JavaScript code that automate tedious processes you should no longer be doing manually. Here are the key parts of an AdWords script.

Functions: 

This gets the script party started. A function is a chunk of code that performs a task or procedure and can be used over and over. It’s what kicks off an action in a script, so you’ll always need one. You’ll see the term “function” followed by the name of the function with parentheses “()” at the end. Often you’ll see a script start with:

function main() {code to execute}

Some other examples of functions in AdWords scripts:

function addAdGroup() {code to execute}
function setCampaignBudget() {code to execute}
function pauseKeywordInAdGroup() {code to execute}

The function names Google uses are helpully self-explanatory. The parentheses that follow can be empty or contain parameters separated by commas. The code you want executed is wrapped by curly brackets “{}” at beginning and end.

Variables:

After the function you’ll typically see something like “var keywords”. Expressed as “var”, Variables are containers that store data values. You can name your variables anything you want such as “keywords” or “KW”, for example. Just remember to keep your naming conventions consistent or you’ll confuse yourself and others.

Variables then correspond to specific objects and entities in the system you’re querying — in this case AdWords.

Objects:

Objects are foundational in JavaScript. An Object is a collection of Entities (think Campaigns and Ad Groups). In AdWords scripts there are four Google Objects: AdWordsApp, SpreadsheetApp, MccApp, UrlFetchApp.

When you’re getting started, you’ll likely only be using AdWordsApp. You can think of it as telling your script to look in the Object called AdWords for a set of data.

(MccApp objects are for scripts that run across an entire MCC. SpreadsheetApp objects connect with Google sheets for reporting. UrlFetchApp is more advanced and allows scripts to communicate with other services and applications.)

Once you establish your Object, you select the Entity within it that you want to query.

Entities:

(Synonyms: Elements, Properties.) The AdWordsApp Object is made up of Adwords Entities such as Account, Campaigns, Ad Groups and Keywords, but also Ad params, Labels, Ad schedules, Budgets and some Targeting. The full list of AdWords entities is here.

Variables, Objects and Entities get put together like this:

var keywords = AdWordsApp.keywords()

Here you’ve named your Variable “keywords”.  This variable corresponds to the Entity in the AdWords Object that is also called “keywords”. Putting the period between the Object and Entity joins them together.

Selectors:

You’ve got your Keywords entity chosen, but you probably want to only look at a particular set of keywords in your account. Selectors do the filtering and sorting for you. Think of a selector as the runner that goes off and fetches only the data that meet your criteria.

Most selectors have these methods for filtering and sorting: withCondition(), withIds(), forDateRange(), orderBy(), withLimit().

You can use multiple selectors to refine the data you want to look at. Typically each selector is on a separate line to make the code it easier to read. Each selector is preceded by a period (.).Tip: When you use more than one withCondition selectors they are treated together as “And” rather than “Or” conditions. Both must conditions must be met.

Methods:

Methods are the verbal commands in scripts for tasks and functions. “Get”, “Set” and “Add” are examples of methods you’ll commonly see in AdWords scripts.

An Entity can become a method when an action or function is involved. The full list of AdWordsApp methods is here.

Iterators:

“Next!”, that’s what iterators are communicating in AdWords scripts. They make sure the script keeps moving along by returning the next item in a sequence. Like ticket takers at an amusement park shuffling one person after another through the Ferris wheel line, iterators do that with keywords or whatever entity you’re script is designed to fetch.

The hasNext() iterator sets up a loop that will iterate as long as it returns true. Each element/object within the loop is obtained by calling next().

Iterators come after the Selectors.

Putting It All Together

When you put all pieces of a Script together you have a something that looks like the one below, which is the starter script Google provides in its introduction to scripts.

I’ve broken down each part with a description of its job.

A Few More Basics

Case matters. AdWords scripts is case sensitive. The convention is to use camelCaps as in getStatsFor, forDateRange or hasNext.

Scripts can be run up to once an hour.

Always aim for the shortest path to your destination when writing scripts. Google has made this easier to do in many ways. Want to get all the ads in your campaigns? There’s a entity for that! Rather than having to filter by Campaign then Ad Group then Ad, you can just use this handy entity:

var ads = AdWordsApp.ads();

You can then add Selectors to call a specific set of ads with your Script.

Never run a script without Previewing it first. We’ll go into troubleshooting more in the next installment.

Resources

There are lots of good resources out there, including many articles here are on Search Engine Land. Here’s a list to get started.

• Google Developers AdWords Scripts portal
• SMX East presentation by Steve Hammer, Russell Savage, Frederick Vallaeys
• Russell Savage’s FreeAdWordsScripts.com
• Marcela De Vivo’s post Streamlining PPC Optimizations for Quick and Easy Conversions
• Follow these folks on Twitter, too: Steve Hammer, Frederick Vallaeys,Russell Savage, Marcela De Vivo

If you have others, please leave them in the comments.

Update: Check out installments 2, 3 and 4 of this series from the links below.

AdWords Scripts For Every Level: Part 2, Intermediate Tips For Editing & Troubleshooting

AdWords Scripts For Every Level: Part 3, Advanced Tips For Unleashing The Power Of Scripts

AdWords Scripts For Every Level: Part 4, A Real World Use Case (Free Script Included)