Take your AdWords Scripts to the Next Level – Part 2

Welcome back to Part 2 of our AdScriptor series (find the first blog entry here). This blog entry will teach you some tips & tricks to efficiently manage your AdWords Scripts within AdScriptor.

Let’s start with a simple script that returns the keywords with the most clicks for a given time range:

 

/**
 * Gets the Keywords with the most clicks between start_date and end_date.
 */
function main() {
  // the 10 keywords that were clicked the most.
  var best_keywords = getMostClickedKeywords("20160101", "20160131", 10);
  for (var i = 0; i < best_keywords.length; ++i) {
    Logger.log("%s. %s : %s", (i + 1), best_keywords[i].name, best_keywords[i].clicks);
  }
}

/** 
 * Gets the Keywords with the most clicks between start_date and end_date.
 * 
 * @param {string} begin_date the start date for which clicks should be checked
 * @param {string} end_date the end date for which clicks should be checked
 * @param {number} [top_n=10] the number of keywords that should be returned
 * @returns {array} returns an array of the best keywords
 */
function getMostClickedKeywords(begin_date, end_date, top_n) {
  if(!top_n)
    top_n = 10;
  var it = AdWordsApp.keywords().forDateRange(begin_date, end_date).orderBy("Clicks DESC").get();
 
  var result = [];
  while (it.hasNext() && (top_n--) > 0) {
    var keyword = it.next();
    result.push({
      name: keyword.getText(),
      clicks: keyword.getStatsFor(begin_date, end_date).getClicks()
    });
  }
 
  return result;
}

 

 

Handling Large Projects

No one likes large scripts with several hundreds or thousands of lines – they are hard to read and maintain. With AdScriptor you have the possibility to split your script into multiple smaller files. In our small example below, we do not really need more than one file, but we will do it here to show how it works.

Let’s create a new script in AdScriptor and split it into two pieces. For this we have to copy this function into main.js:

/**
* Gets the Keywords with the most clicks between start_date and end_date.
*/
function main() {
  // the 10 keywords that were clicked the most.
  var best_keywords = getMostClickedKeywords("20160101", "20160131", 10);
  for (var i = 0; i < best_keywords.length; ++i) {
    Logger.log("%s. %s : %s", (i + 1), best_keywords[i].name, best_keywords[i].clicks);
  }
}

adscript1

For the second function we create a second file (Menu: Script > New File). Name it report.js and paste the following content into it:

/** 
 * Gets the Keywords with the most clicks between start_date and end_date.
 * 
 * @param   {string} begin_date the start date for which clicks should be checked
 * @param   {string} end_date   the end date for which clicks should be checked
 * @param   {number} [top_n=10]      the number of keywords that should be returned
 * @returns {foobar} returns an array of the best keywords
 */
function getMostClickedKeywords(begin_date, end_date, top_n) {
  if(!top_n)
    top_n = 10;
  var it = AdWordsApp.keywords().forDateRange(begin_date, end_date).orderBy("Clicks DESC").get();
  
  var result = [];
  while (it.hasNext() && (top_n--) > 0) {
    var keyword = it.next();
    result.push({
      name: keyword.getText(),
      clicks: keyword.getStatsFor(begin_date, end_date).getClicks()
    });
  }
  
  return result;
}

 

This will look like this in AdScriptor:

adscriptor2

AdScriptor automatically combines both files when you run the Script from Google AdWords.

Auto-Completion and Error Detection

You can always trigger auto-completion by pressing Ctrl+Space on your Keyboard or by right-clicking the editor and selecting “Autocomplete”.

Autocompletion also works across files:

adscriptor3

But AdScriptor can do much more than this for you. If you happen to have a syntax error in your code, AdScriptor will mark it for you on the left side:

adscriptor4

Also in very long scripts you may overlook some errors – just press Alt + E on your keyboard and AdScriptor will guide you through all suggestions and errors in this file – so no more surprises when you start the script – you can see most errors already while coding!

adscriptor5 adscriptor6

Refractoring

Did you ever create a variable and later thought you should rename it to better fit the context? And did you go through the complete file and manually replaced all occurences of that variable by hand?

No need to do this with AdScriptor – simply target the variable you want to rename and right-click and select “Rename” (or Ctrl-Shift-E on your Keyboard) and enter a new name for your variable. After you press Rename AdScriptor will replaces all occurrences of this variable in the current file. But watch out – AdScriptor can’t replace references to this variable in other files.

adscriptor7

Advanced Documentation

If you want to document your Functions, you can use JSDoc comments above your functions and variables, e.g.:

1

@param starts a parameter definition, followed by the type in brackets, followed by the variable name. If the parameter is optional, surround the name with braces []. You can also specify a default value like you can see in the screenshot above.

AdScriptor will add this comments to it’s autocompletion, however it will not validate its contents, e.g. check if the types you specified exist.

However using JSDoc’s will give you a much more detailed auto-completion:

2

If you want to read more about JSDoc Comments and how to use them, please refer to http://usejsdoc.org/.

Automatic Code Layout

Making the right indenting for every code block can get quite annoying after some time.

AdScriptor helps you with this by providing a mechanism to automatically format your code.

Simply press Ctrl-B (or right-click and select Beautify) and the file you are currently in gets automatically formatted to look pretty.

Where was This Function Defined Again?

Did you ever ask yourself this question while working on a large script? No more scrolling through your script files to find the function you are looking for! Just right-click the function you want to find and select “Show Definition” and AdScriptor will jump to the selected function or variable (alternatively press Alt-. on your Keyboard)

Variating Scripts for Different Accounts

If you want to run a Script in multiple accounts, you typically don’t change a lot. Mostly only some parameters you give it, e.g. a spreadsheet URL. With AdScriptor you can use the same script for multiple accounts without needing to change the script itself.

Let’s say we would want to write our “Top 10 Keywords” into a different spreadsheet for each of our accounts.

To do that, we simply add the needed variables before the Embedding Code AdScriptor gave us in each account, e.g.:

3

After that we can simply refer to “SPREADSHEET_URL” in our script:

4

Now you can change the SPREADSHEET_URL for each account, without having to change a single line in AdScriptor.

Other Shortcuts

AdScriptor also supports most tools you would expect from a normal text editor – you can search with Ctrl-F and search-replace with Ctrl-R, both will work with regular expressions if you want.

If you aren’t sure which key -combination you need to use, you can always press Ctrl-Atl-H to show all Keybindings AdScriptor has (or select Editor -> Keyboard Shortcuts in the Menu).

Saving your Work

AdScriptor will periodically save your Script to make sure you don’t lose any progress. You can also save your work by pressing Ctrl-S (or right click-save) in the editor.

That’s it for this time, stay tuned for more help and advice on AdScriptor, and also check out our other posts & tools!

ABOUT THE AUTHOR


Sven Fisch

Sven Fisch is part of crealytics' innovation hub.
He is passionate about (meta) programming and creating powerful tools that make people's lifes easier.