AdWords Scripts 101Chapter two

AdWords Scripts Code: Beginner

PPC Essentials

Congratulations on completing Chapter One! Now you know what scripts are and how they’ll help you, but we do admit, that scripts code still looks pretty scary.

The next three chapters are dedicated to breaking down and explaining all that code. First up, we’ll learn the basics for editing AdWords scripts in this section. Next, take your lesson a step further with our JavaScript tutorial. If you’re a pro, check out our advanced section for script experts.

Even if you can’t understand JavaScript, making the jump to reading AdWords Scripts is simply a matter of familiarizing yourself with a few patterns. Scroll down and get started!

Structure

AdWords Scripts generally follow this layout:

License

Any script you find online should begin with comment indicating the license and copyright. For AdWords scripts, these are virtually always free MIT or Apache licenses, which allow you to change and use the script for any (including commercial) purpose as long as you keep the copyright/license in tact when you use the script and do not try to sell the script itself.

Metadata

The license is followed by a comment block with information about the script, including the script author, version, and a description of what it does. Sometimes the description will also include usage instructions, or a link to more detailed documentation.

Settings

The first actual code in the script will be a set of variables named all uppercase letters. These are the configuration settings for the script. There may be many or just one.

A comment above each setting describes of how it affects script functionality (and instructions for determining or obtaining the proper value, if it’s not straightforward). If there is no comment for a setting, chances are, it’s not something you should mess with!

Required settings are generally listed first and have placeholder values such as: “INSERT_SPREADSHEET_URL_HERE“. Optional settings are either blank or have default values.

In many cases, the defaults for optional settings are optimal values for the script. Before dramatically changes any of the defaults, you should test smaller changes incrementally, and observe the impact on script functionality and execution speed.

The Rest of the Code

Everything that follows is the actual script—the code that does what’s described in the description, according to the configured settings. Note, this code can be very long, but most scripts are designed so you’re not required to touch (or even look at) any of it.

Editing for Basic Customization

Many example scripts will work without much tweaking, but may need to be configured with your own information (i.e. an account id, a Google spreadsheet URL, etc). Configuration settings are the variables named with all-caps, listed after the metadata comment at the top of the script.

The script instructions (either online documentation or in the comments at the top of the script) often indicate which settings you have to update, but it’s a good idea to look at the comment above each variable to make sure none are marked as required.

Even if none are required, you may want to tweak some settings to better suit your needs.

Updating Settings

When updating the settings, take care to only change the value. (Note, if the value is surrounded by quotes, those quotes simply delimit the value, and are not part of the value itself.)

Be careful not to:

  • Delete quotes surrounding the value
  • Delete any semicolons or commas
  • Accidentally type any stray characters in the code
  • Change the variable name

This is code, so a single missing or unexpected character can break the script. So it may look like improper use of punctuation, but don’t fix it! 🙂

If there is a default or placeholder value, double-click on the value, and only the part that is safe to edit will be selected.

Adding Your Own Comments

Feel free to leave notes for yourself/others by adding a code comment.

Particularly for optional settings, it’s a good idea to leave a comment with the date, your email, and an explanation of why you changed the setting. It might seem unnecessary, but trust us, later you (or someone else) will be really glad you did.

// Copyright 2015, Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License.
/** * @name Ad Performance Report * * @overview The Ad Performance Report generates a Google Spreadsheet that * contains ad performance stats like Impressions, Cost, Click Through Rate, * etc. as several distribution charts for an advertiser account. See * https://developers.google.com/adwords/scripts/docs/solutions/ad-performance * for more details. * * @author AdWords Scripts Team [adwords-scripts@googlegroups.com] * * @version 1.0 * * @changelog * - version 1.0 * - Released initial version. */
// Comma-separated list of recipients. Comment out to not send any emails. var RECIPIENT_EMAIL = 'email@example.com'; // URL of the default spreadsheet template. This should be a copy of // https://goo.gl/21FW5i var SPREADSHEET_URL = 'INSERT_SPREADSHEET_URL_HERE';
/** * This script computes an Ad performance report * and outputs it to a Google spreadsheet. */ function main() { Logger.log('Using template spreadsheet - %s.', SPREADSHEET_URL); var spreadsheet = copySpreadsheet(SPREADSHEET_URL); Logger.log('Generated new reporting spreadsheet %s based on the template ' + 'spreadsheet. The reporting data will be populated here.', spreadsheet.getUrl()); var headlineSheet = spreadsheet.getSheetByName('Headline'); headlineSheet.getRange(1, 2, 1, 1).setValue('Date'); headlineSheet.getRange(1, 3, 1, 1).setValue(new Date()); var finalUrlSheet = spreadsheet.getSheetByName('Final Url'); finalUrlSheet.getRange(1, 2, 1, 1).setValue('Date'); finalUrlSheet.getRange(1, 3, 1, 1).setValue(new Date()); spreadsheet.getRangeByName('account_id_headline').setValue( AdWordsApp.currentAccount().getCustomerId()); spreadsheet.getRangeByName('account_id_final_url').setValue( AdWordsApp.currentAccount().getCustomerId()); outputSegmentation(headlineSheet, 'Headline', function(ad) { return ad.getHeadline(); }); outputSegmentation(finalUrlSheet, 'Final Url', function(ad) { return ad.urls().getFinalUrl(); }); Logger.log('Ad performance report available at\n' + spreadsheet.getUrl()); if (RECIPIENT_EMAIL) { MailApp.sendEmail(RECIPIENT_EMAIL, 'Ad Performance Report is ready', spreadsheet.getUrl()); } } /** * Retrieves the spreadsheet identified by the URL. * @param {string} spreadsheetUrl The URL of the spreadsheet. * @return {SpreadSheet} The spreadsheet. */ function copySpreadsheet(spreadsheetUrl) { return SpreadsheetApp.openByUrl(spreadsheetUrl).copy( 'Ad Performance Report ' + new Date()); } /** * Generates statistical data for this segment. * @param {Sheet} sheet Sheet to write to. * @param {string} segmentName The Name of this segment for the header row. * @param {function(AdWordsApp.Ad): string} segmentFunc Function that returns * a string used to segment the results by. */ function outputSegmentation(sheet, segmentName, segmentFunc) { // Output header row. var rows = []; var header = [ segmentName, 'Num Ads', 'Impressions', 'Clicks', 'CTR (%)', 'Cost' ]; rows.push(header); var segmentMap = {}; // Compute data. var adSelector = AdWordsApp.ads() .forDateRange('LAST_WEEK') .withCondition('Impressions > 0'); var adIterator = adSelector.get(); while (adIterator.hasNext()) { var ad = adIterator.next(); var stats = ad.getStatsFor('LAST_WEEK'); var segment = segmentFunc(ad); if (!segmentMap[segment]) { segmentMap[segment] = { numAds: 0, totalImpressions: 0, totalClicks: 0, totalCost: 0.0 }; } var data = segmentMap[segment]; data.numAds++; data.totalImpressions += stats.getImpressions(); data.totalClicks += stats.getClicks(); data.totalCost += stats.getCost(); } // Write data to our rows. for (var key in segmentMap) { if (segmentMap.hasOwnProperty(key)) { var ctr = 0; if (segmentMap[key].numAds > 0) { ctr = (segmentMap[key].totalClicks / segmentMap[key].totalImpressions) * 100; } var row = [ key, segmentMap[key].numAds, segmentMap[key].totalImpressions, segmentMap[key].totalClicks, ctr.toFixed(2), segmentMap[key].totalCost]; rows.push(row); } } sheet.getRange(3, 2, rows.length, 6).setValues(rows); }

What's Next For You?

The sections above have given you everything you need in order to understand the very basics of an AdWords script—how it looks and what you need to edit. Move on to our “Which AdWords Script Do I Need” section to find the best script for you.

If you’d like to gain a deeper understanding of JavaScript, go to the next lesson!