Google Ads Scripts 101

sentences 
= 
text
.split(
'. '
)
;

makeItRain()

// Assign code to the function name: 'makeItRain'.
function makeItRain(){
    // Code to make it rain goes here.
}

// Make it rain once ...
makeItRain();

// ... twice ...
makeItRain();

// ... three times!
makeItRain();

// This function "returns" the result of
//  adding the numbers two and three.
function addTwoAndThree() {
  return 2 + 3;
}

// Wherever this function is called, it will
//  be replaced with the returned value.
addTwoAndThree();     // 5
1 + addTwoAndThree(); // 6

Values

A value is a piece of data.

A value written directly into a script is said to be literal.

// a literal number three
3;

A literal value is only available to the code once, exactly where it is literally written. In order to be accessed repeatedly (and possibly manipulated), a value must be assigned to a variable.

Variables

A variable is a named reference to a value.

A variable is created with the keyword var, and can be assigned a value using the equals sign.

// Create variable 'age'.
var age;
// Assign 'age' a value of three.
age = 3;

This can be combined into a single line:

var age = 3;

An existing variable can be re-assigned, which changes its value from that point forward. Oftentimes variables are assigned new values multiple times.

var age = 1;
// Variable 'age' equals one.

age = 2;
// Now variable 'age' equals two.

age = 3;
// Now variable 'age' equals three.

After it is created, a variable can be referenced using the variable name.

var age = 3;
var yrsOld = age;
// Now both 'age' and 'yrsOld' equal 3.

tip

function whoAmI(){
    return "I don't know.";
}
whoAmI(); // "I don't know."

function theFunc( param1, param2 ){
    // Function code goes here,
    // which has access to the 
    // values of arg1 and arg2 
    // through the variable names 
    // param1 and param2.
}
theFunc( arg1, arg2 );

function whoAmI( name ){
    return "I'm " + name + "!";
}
whoAmI( "Jax" ); // "I'm Jax!"

var myName = "I don't know";
function myNameIs( name ){
    myName = name;
}
function whoAmI(){
    return "I'm " + myName + "!";
}
whoAmI(); // "I'm I don't know!"
myNameIs( "Jax" );
whoAmI(); // "I'm Jax!"

Global Functions

JavaScript has a set of built-in functions.  These are called global functions because they are available anywhere in any script.  Here are a few:

• parseInt()
• parseFloat()
• isFinite()
• isNaN()
• decodeURI()
• encodeURI()
• decodeURIComponent()
• encodeURIComponent()

Methods

There are also a variety of built-in functions that can only be called through variables, called methods.  A method is a function that is owned by and specific to a variable, and can only be accessed through that variables.  A method can be called by following the variable reference with a period, then the method like any other function call:

var name = "JAX";
name.toLowerCase(); // "jax"

Which methods are available on a particular variable is determined by the variable’s value type.  You’ll learn about various value types and their most useful methods in the next section.

Libraries

There are other global functions made available as methods of built-in global variables called libraries.  Here are libraries you may encounter and example methods:

• JSON (Reference)
  • JSON.parse()
  • JSON.stringify()
• Math (Reference)
  • Math.round()
  • Math.sqrt()

tip

var name; // undefined
// 'name' is blank by default.
	
name = null;
// Now 'name' is explicitly blank.

var jaxIsYoung = true;
var jaxIsOld   = false;

var age     = 3;
var pi      = 3.14159;
var leagues = 2e4; // 20,000

var name     = 'Jax';
var greeting = "Hi, I'm Jax!";

greeting = "Hello!";
greeting.toLowerCase(); // "hello!"
greeting.toUpperCase(); // "HELLO!"

greeting = 'hi Philadelphia!';
greeting.indexOf('hi'); // 0
	
greeting = 'hey Philadelphia!';
greeting.indexOf('hi'); // 5
	
greeting = 'hey San Diego!';
greeting.indexOf('hi'); // -1

greeting = "Hi";
	
greeting.toLowerCase(); // "HI"
// The above line returned "HI", but
//   the variable was not assigned
//   the returned value, so:
//   greeting = "Hi" (unchanged)
	
greeting = greeting.toUpperCase();
// This time we assigned the
//   returned value to the variable:
//   greeting = "HI"

name = 'Jackson';
// name.length = 7
	
name = 'Jax';
// name.length = 3
	
name = '';
// name.length = 0

// Regex to match start of a URL.
var matchUrl = /^https?:/;

// Regex to match start of a URL.
matchUrl = /^https?:\/\//;

// Now regex is case-insensitive
// since we added the 'i' flag.
matchUrl = /^https?:\/\//i;

myRegex = new RegExp( '^https?://', 'i' );

/^http:/.test("http://t.co"); // true
/^http:/.test("not a url"); // false

var m = /(.*)=(.)/g.exec("2+2=4");
// m = ["2+2=4", "2+2", "4"]

var birthday = new Date( 2013, 4, 4, 4, 3, 1 );
// May 4, 2013 @ 4:03:01

var birthday = new Date( 2013, 4, 4 );
// May 4, 2013

var xmas = new Date( 2016, 12, 25 );
// Jan 25, 2017 <- whoops, not xmas!

var now = new Date();

var now = new Date();
var xmas = new Date( 2016, 11, 25 );
var millisecondsAway = xmas - now;
var daysAway = 
  millisecondsAway / 1000 / 60 / 60 / 24

nicknames = [ 'Jax', 'Jah', 'Jay' ];

nicknames[0]; // 'Jax'
nicknames[1]; // 'Jah'
nicknames[2]; // 'Jay'

nicknames = []; // empty array
// No nicknames! Just call me 'Jackson'.

nicknames = [];
// Okay, you can call me 'Jax'.
nicknames.push( 'Jax' );
// nicknames = [ 'Jax' ];

// nicknames = [ 'Jax' ];
	
nicknames.push( 'Jackie' );
// nicknames = [ 'Jax', 'Jackie' ]
// I will not answer to 'Jackie'!
	
nicknames.pop(); // 'Jackie'
// nicknames = [ 'Jax' ]

nicknames = [ 'Jax' ];
// nicknames.length = 1;
nicknames.push( 'Jah' );
// nicknames.length = 2;

// nicknames = [ 'Jax', 'Jah' ]
var i, nickname;
for( i=0; i < nicknames.length; i++ ){
 nickname = nicknames[i];
 say( 'Some call me '+nickname+'.' );
}
// Some call me Jax.
// Some call me Jah.

var table = [
 [ 'A1', 'B1' ],
 [ 'A2', 'B2' ],
 [ 'A3', 'B3' ],
];
myArray[0];    // [ 'A1', 'B1' ]
myArray[0][0]; // 'A1'
myArray[2][1]; // 'B3'
myArray[2][2]; // undefined

var kid = {
  'age'       : 3,
  'name'      : 'Jackson',
  'nicknames' : [ 'Jax', 'Jah' ]
};

var kid = {'age':3,'name':'Jackson'};

kid['age'];  // 3
kid['name']; // 'Jackson'

kid.age;  // 3
kid.name; // 'Jackson'

kid.nicknames = [ 'Jax', 'Jah' ];

kid.nicknames = [ 'Jax', 'Jah' ];

// kid = {'age':3,'name':'Jackson'}
var key, value;
for( key in obj ){
 value = kid[key];
 // Code to deal with a
 //   key/value pair goes here.
 say( 'My' + key + ' is ' + val );

}
// My age is 3.
// My name is Jackson.

var kids = {
    'firstborn' : {
        'name' : 'Jackson',
        'age'  : 3
    },
    'middleChild' : {
        'name' : 'Jazmine',
        'age'  : -0.65
    },
    'theBaby' : {
        'name' : 'Isaiah',
        'age'  : undefined
    }
};
kids.firstborn.age; // 3
kids.theBaby.name;  // 'Isaiah'

var kids = [
    {
        'name' : 'Jackson',
        'age'  : 3
    },
    {
        'name' : 'Jazmine',
        'age'  : -0.65
    },
    {
        'name' : 'Isaiah',
        'age'  : undefined
    }
];

Operators

There are a number of operators in JavaScript, many of which reflect how they would be written in a mathematical expression.  However many can be used for types other than numbers.

Mathematical Operators

As you may have guessed, these are used with numerical values.

tip

Expressions with multiple mathematical operators will be evaluated according to the standard mathematical order of operations. In case you don’t remember PEMDAS, here’s a refresher:  Expressions within parentheses are evaluated first, then exponents, then multiplication/division, then addition/subtraction; other than that expressions are evaluated left-to-right.

tip

pro tip

There is a special division operator called “modulo”: %.  It is like division, but instead of returning the exact division result it does integer division and returns the remainder. It is useful for determining whether a number is a factor of another number.

Concatenation Operators

The plus sign doubles as a concatenation operator for strings:

Example:

name = "Jax";
greeting = "Hi!"
greeting += " I'm " + name + ".";
// greeting = "Hi! I'm Jax."

If the concatenation operator is used between a string and another type, the non-string value will be coerced into a string.

Example:

age = 3;
greeting += " I'm " + age + " years old.";
// greeting = "Hi! I'm Jax. I'm 3 years old."

Comparison Operators

Comparison operators always return a boolean value, and are usually used in ‘if’ statements (if statements are covered in the next section).

Logical Operators

Like comparison operators, logical operators always return a boolean value.

jaxIsYoung = true;
jaxIsOld   = false;
jaxIsYoung && jaxIsOld;  // false
jaxIsYoung || jaxIsOld;  // true
jaxIsYoung && !jaxIsOld; // true

Generally these are used in if statements, which are covered in the following section called ‘Conditionals’.

Increment/Decrement Operators

These four are special because they actually modify the value of the variable.

Example:

age = 3;
age++;
// age = 4
age++;
// age = 5
age =+ 30;
// age = 35
age--;
// age = 34
age =- 31;
// age = 3

pro tip

All the above increment/decrement operators also return the variable’s prior value (its value before being incremented/decremented). There are also the += and -= operators, which behave the same as above but they return the variable’s new value.  Similarly, the ++ and -- can be placed before the variable reference to return the new value. The return values of these operators only matter if they are used within a greater expression; the return value is discarded if used as the entire statement, as in the examples above.

Conditionals

I’ll tell you a secret: conditional structures are the key to having a robust script.  Conditional structures enable multiple cases to be handled within a single script.

There are two primary types of conditional structures: if/else blocks and loops.

If/Else Blocks

An if block (or if statement) executes a block of code only if a given condition expression evaluates true.

if( jax.age < 5 ){
 jax.goTo( 'daycare' );
}

tip

The condition will pass for values other than the boolean value true, which are considered “truthy”: non-empty strings, non-zero numbers, and any date, regex, object, or array (even if the object or array is empty).

An else block can be added to the end of the if block in order to execute an alternate set of code in case the expression evaluates to be false.

jax.age = 10;
if( jax.age < 5 ){
 // This code will NOT execute.
 jax.goTo( 'daycare' );
} else {
 // This code WILL execute.
 jax.goTo( 'school' );
}

More numerous cases can be handled by chaining a series of if/else blocks together:

if( jax.age < 5 ){
 jax.goTo( 'daycare' );
} else if( jax.age < 18 ){
 jax.goTo( 'school' );
} else if( jax.age < 60 ){
 jax.goTo( 'work' );
} else {
 jax.retire();
} 

pro tip

If there are multiple possible values for a single variable that a script needs to check for, a switch statement can be simpler than a series of if statements.  Read about switch statements here.

Loops

A loop is used to run a specific set of code repeatedly until a specific condition is met.

The most common type is the for loop, which is usually used to loop through each item in an array or object.

Here is an example of looping through an array:

// nicknames = [ 'Jax', 'Jah' ];
var i, nickname;
for( i=0; i < nicknames.length; i++ ){
    // Code here will be run for
    //   each nickname.
    nickname = nicknames[i];
    say( 'Some call me '+nickname+'.' );
}
// Some call me Jax.
// Some call me Jah.

And an example of looping through an object:

// kid = {'age':3,'name':'Jackson'}
var attribute, value;
for( attribute in kid ){
    // Code here will be run for
    //   each attribute of 'kid'.
    value = kid[attribute];
    say( 'My' + key + ' is ' + val );

}
// My age is 3.
// My name is Jackson.

The other type of loop is the while loop, which is used when the number of times the loop code needs to execute is unknown (as opposed to for loops, which run code a specific number of times).

function canLiveAtHome( person ){
 if( person.age < 18 
  || person.job == "student"
  || person.paysRent ){
   return true;
 } else {
   return false;
 }
}
	
var kid = new Person( "Jax" );
	
while( canLiveAtHome( kid ) ){
    // As long as canLiveAtHome() 
    //   returns true, then ...
  kid.feed();
  kid.clothe();
  kid.love();
}

// Once canLiveAtHome() returns
//   false, then ...
kid.kickOut();
kid.love();

Conclusion

Until you are a bit more practiced at reading JavaScript, you will not remember all the concepts and syntax above.  That’s okay!  Even experienced developers have not memorized all of the names, parameters, and exact return formats of the many built-in functions.

Documentation on all of this is always a few keystrokes away in a wealth of online resources.  Simply search “javascript” and the syntax keyword or function/method name and you will find plenty of reference articles.

tip

You can also find lots of specific examples and answers to all sorts of issues in forums like Stack Overflow.

tip

You can enable additional app objects for advanced integrations:

• Analytics
• BigQuery (for Google Analytics 360 customers)
• Calendar
• FusionTables
• Prediction
• ShoppingContent
• Tasks
• YouTube & YouTubeAnalytics

// ads Selector
var adsSelector = 
  AdWordsApp.ads();

var adsSelector = 
  AdWordsApp.ads();
adsSelector =
  adsSelector.withCondition("Clicks < 2");
adsSelector = 
  adsSelector.forDateRange("TODAY");

adsSelector = AdWordsApp.ads()
 .withCondition("Clicks < 2")
 .forDateRange("TODAY");

var adsSelector = 
  AdWordsApp.ads();
var adsIterator = 
  adsSelector.get();
while( adsIterator.hasNext() ){
 var ad = adsIterator.next();
 // do stuff with `ad`
}

var ad = adsIterator.next();
ad.pause();

// Create an Ad Group Builder
var campaign = 
  campaignIterator.next();
var adGroupBuilder = 
  campaign.newAdGroupBuilder();

// Create an Ad Group
var adGroup = 
  adGroupBuilder
    .build()
    .getResult();

pro tip

What’s Next?

Make sense?  If you’re ready to get testin’, proceed to the next chapter and find the best script for you!

Going Further

This overview should be a strong starting point to help you get cracking with some pre-built scripts!  If you’re interested in doing heavy customization or writing your own scripts, you’ll need to learn more about the nuances of Javascript and get closely acquainted with Google’s Google Ads Scripts documentation.

If you’re looking to integrate with other Google services, be sure to acquaint yourself with the various quotas before designing your scripts.

Okay, so now you know all about the anatomy of a script and how it works. But how does this apply to you? Check out our top script list to help you find the perfect Google Ads script to practice based on the account problems you’d like to solve! Are you a beginner, expert, or somewhere in between? We have an Google Ads script for you.

• Link Checker (Level: Easy)
  • This easy-to-use script scans through our final URLs to find any that are pointing to non-existent (404) pages. You don’t want to be spending money driving users to dead pages, right? We believe that this script should be applied to EVERY account that you manage.
  • Link Checker – Manager Account (Level: Easy)
    • This extends the single account Link Checker script to run for multiple accounts under a manager account.

• Account Summary (Level: Easy)
  • Tired of loading each of your clients accounts every morning to check yesterday’s performance? Use this script to have your daily account performance pulled into a GSheet AND emailed to you. You can also make this a client-facing report for those clients who like daily performance updates.

• Bid to Position (Level: Easy)
  • For those without advanced PPC tools such as Acquisio or Marin, this tool can adjust your keyword bids to help position your ads in the ad position that works best for you. Remember, #1 ad position isn’t always the best position for every client/industry.
• Negative Keyword Conflicts (Level: Easy) 
  • Proactively negating inefficient terms can be an important part of account management. As an account grows and keyword lists expand, it is important to ensure that you are not blocking keywords from matching relevant search queries, affecting your account efficiency. This script will check whether the negative keywords in an account block any target keywords and deliver the finding in a spreadsheet via email. Note: A similar feature is now available within the Google Ads platform. However, the Seer team continues to find value in this script as the emailed spreadsheet layout of its findings lends itself to easy review & implementation. 

• Advanced Google Ads Budget (Level: Easy)
  • Budgets got you stressed? This script has your back! There are three areas that this script will lighten your load: enforcing account budgets, maintaining monthly budgets, and applying small budgets to tests. Why stress when you can utilize automation to make your budgets more flexible?
• Disapproved Ads Alerts (Level: Easy)
  • This super easy-to-implement script is pretty self-explanatory. Implement this to know the moment your ad has been snagged on a disapproval.
• Pause Campaigns When Site is Down (Level: Intermediate)
  • Nothing is worse than paying for a click, only for it to drive to a dreaded 404 page. How could that be? You QA‘d this link before the campaign went live! Well, as your client’s business evolves they may have back-end changes made to their site or a site could go down overnight while you sleep, dreaming of your treasured CVR. This script will detect when your site is out of commission and automatically pause your campaigns to save you from wasting your budget.
• Search Query (Level: Intermediate)
  • This mid-level script helps to not only automate the process of pulling and analyzing SQRs, it also can help to implement new keywords and ads based on thresholds that you set. You can use this script to create some nifty tricks for automatically creating ad groups for those certain search queries that are absolutely killing it for your conversion rates and CPA’s!

• Keyword Performance (Level: Intermediate)
  • Do you have keywords that have bad quality score? That’s a silly question, of course you do! This script will help automate the process of finding those keywords that are sucking your budget dry due to poor quality score.

• Sale Countdown (Level: Intermediate)
  • Humans love things when their a sense of scarcity. Skip waiting for your ads to pass through ad approval and use this script to update your countdown values without the need of sending your ad back through the approval process.

• Account Anomaly (Level: Intermediate)
  • Decide to launch a non-modified broad match keyword to gain more insights about how your customers are searching? As PPC’ers, we know how valuable (and dangerous) this strategy can be. Use this script to have alerts sent to you by email if your account is performing significantly different than it usually is.

• Auction Insights (Level: Advanced)
  • This non-traditional script helps to visualize auction insights data over time to help you understand what has been going on in your industry. Use this to see which competitors have come and gone over time and if you’re really handy, you can use this to spy on your competitors spend and see when they typically exhaust their budgets.

• Bid by Weather (Level: Advanced)
  • Do you notice an uptick in account performance when its raining or snowy? How about when it’s sunny? If so, use this script to automatically adjust your bids when users are in areas with your preset weather conditions. I mean, who buys umbrellas when it’s NOT raining?

• Multi Bidder (Level: Advanced)
  • This difficult to set up (but super powerful) script gives you the ability to make keyword bid adjustments based of of multiple variables. You can even use this script to set specific keywords to first page or top of page cpc’s, if you’re comfortable in trusting Google for those values.

• Ad Customizer (Level: Advanced)
  • How would you like to be able to dynamically insert your stock numbers in your ad copy? By showing users how many of a product you have left, you can help nudge them to complete their purchase. Using this script, plus some cloud hosted inventory data, you can have your ad text to be updated to include values reflecting your current stock of a product. Can you believe there are still people who say dynamic insertion is a bad thing? Shame on them.

• Dayparting Automation (Level: Advanced)
  • Not only is it a boring and monotonous task pulling and analyzing dayparting data, it’s complicated to upload and you’re bound to miss a time period which can throw off your entire account’s performance. This script from Brainlab via Search Engine Land uses fancy data smoothing to eliminate anomalies, it creates heatmaps, and it shows your data across a basic line graph. Then it uses your data to make up to 24 bid adjustments daily (4 times more than Google Ads permits through their interfaces). This one is tricky to get going, but it can really help out those clients/companies who have performance that varies across each hour.

Chapter 6: Implementing Google Ads Scripts

Got an Google Ads Script in mind? Great! Our next lesson plan will walk you through the process of implementing your script. Watch this video, or read below for the step-by-step instructions.

1. Once you have either created or selected a pre-made script that fits your account needs, the next step is to implement.  Google Ads Scripts can be implemented in the “Bulk Operations” options which can be located in the lower half of the left-hand column in the Google Ads UI at both the MCC-level and account-level.

2. When you click-through the “Bulk Operations” link, you’ll be brought to the Bulk Operations menu screen where you’ll need to select the “Create and Manage Scripts” Link.

3. Once clicked through, the “Create and Manage Scripts” will bring you to a screen that allows you to manage new and existing scripts, and see run-time logs for any past or presently active scripts. Since we’re implementing a new script, you’ll want to click the “+Script” button to create a new script: 

4. You’ll then be directed to the scripts editor page, which will allow you to copy, paste, and manipulate scripts directly within the AdWords UI. This screen will also allow you to preview scripts to test them for functionality before saving and completely implementing. Please note that in order to fully preview and save a script, you must click the “Authorize Now” button which gives the script permission to run automatically on your behalf. Once on this screen you’ll want to follow these steps:
   • Choose a name for your script
   • Paste or hard code your script into the body of the editor
   • Edit script configuration settings as needed.
   • Authorize the script to run within your account on your behalf
   • Preview your script to test for errors/functionality
   • Save script once you’re happy with its performance
   • Close script editor (or choose run script now if you’d like)

5. Once your script has been previewed and saved, you should create a script run schedule where you can select the frequency in which you would like your script to run. Options include: one time, hourly, daily, weekly, or monthly run schedules. You can also layer in hour of day that you would like your script to run on a recurring basis.

Chapter 7: Google Ads Scripts Tips

Getting the hang of it? Here are our top 9 free tips for all levels—beginners to professionals—to keep in mind as you begin working with Google Ads Scripts.

1. Google Ads scripts can sometimes take a long time to run—think a half hour to an hour! It’s possible your script could time out and updates won’t be complete. Always confirm that your script ran by checking progress in the log section.
2. Don’t just set and forget. While it’s nice to sit back and let scripts do some of the work, you’ll still want to keep an eye on your account and ensure it’s making the changes you recommended.
3. Scripts cannot be undone. Backup your account by downloading the account from editor before you implement the script so you can reupload the account without the script if necessary.
4. Implement scripts at the MCC-level (My Client Center—utilized to manage and edit scripts across multiple accounts at scale) to protect code from clients and maintain control (credit to @siliconvallaeys). If you have more than 50 accounts in your MCC, you can use the MCC Manager template that Google released.
5. View common script examples by clicking the “Show Examples” button while you’re editing. Copy the example and edit from there!
6. Keep your naming process consistent throughout the script to avoid confusion.
7. Leave comments directly within the script to help track changes and add context. It makes things easy when working with a team or making any changes to a script.
8. Always check the comments/feedback section for any potential bugs/fixes if you decide to use a script posted online.
9. Reference Google’s developers community forum for help if you’re running into any script problems.

Chapter 8: Troubleshooting Google Ads Scripts

We have all been there; you implement a script, preview it just to make sure everything is working properly then you hit that “ERROR” in the middle of your preview process. Naturally, this means the script will not work and you need a solution. But where do you turn? Below we will cover a few common errors that we at Seer have come across during the implementation process and how to fix them.

1. Specify the date range. If the date range is input incorrectly, the script will stop running.
2. Specify the campaign. Ensure you are pulling the correct data into your report
3. Using destination URL instead of final URL. Older versions of scripts that call for destination URLs are no longer supported; change all instances to final URL
4. Missing semicolons. These are sometimes mistaken with periods; ensure all semicolons are noted to allow the script to know where the expression ends.
5. The code is case sensitive. You may receive an error notification that you are attempting to use an undeclared variable.

Chapter 9: Additional Google Ads Scripts Resources

What’s Next?

Now that you know what AdWords Scripts are, what they look like, what script is right for you, and how to implement scripts, go on…try implementing one on your own! Start making your AdWords life easier allowing for you to focus on your overall strategy. While you’re at it, check out some of our favorite scripts libraries: Free AdWords Scripts.com, Google AdWords Scripts Solutions, and Google AdWords Code Snippets.

Seer Scripts Team

If you have any further questions related to scripts, feel free to contact our Seer Scripts Team. We would love to hear from you!