In this post series, we will show you how to use a completely free tool stack that will take your AdWords scripting efforts to the next level. The first part of this blog post will give you a good overview and take you through the first steps, whereas the next parts will explain each tool in more details, with examples.
- Versioning: I made some changes to my script – but now I would love to get back to a previous version of a script – where can I get it?
- Editing: What was the name of that AdWords API function again? How many parameters does it take? Why is Google’s autocomplete so unreliable? How can I structure large scripts in smaller chunks?
- Rollouts: How can I execute the same script in multiple AdWords accounts without having to copy the script repeatedly? Also, I do not want to copy it to all accounts over again as soon as I change it.
…but we fixed it!
The following illustration explains how the improved scripting process with AdScriptor works:
By dividing the responsibilities, the three problems mentioned above can be tackled one by one:
- Versioning: Instead of saving only the latest version of the script in AdWords itself, we move the source code to GitHub, a popular web based Git repository hosting service. Don’t get confused. Think of it like a time machine that saves all the changes you do to your scripts and that lets you restore any version you would like. Git can do a lot more than that – but let’s keep it simple for now.
- Editing: The AdScriptor is a web interface based editor and supports you with syntax highlighting and autocompletion: the editor will propose how to finish your calls to the AdWords API – you don’t have to look up from the documentation to see what these functions are called anymore. AdScriptor allows you to span a single script over multiple files to help you to structure bigger projects. And last but not least, it integrates seamlessly with GitHub –making it as easy as 1-2-3 to use a versioning system without any hassles.
- Rollouts: AdWords will load Scripts dynamically from GitHub and execute these. This way, the same script can be executed in hundreds of AdWords accounts without having to copy or to reveal the script code. And better still – if you change a script, you do not even have to update all accounts with a copy of the new version.
Getting there – Step by step
Don’t worry. The whole process looks more difficult and frightening than it actually is.
A word on privacy and data security: the scripts you write will be technically saved as GISTs on GitHub. As such, other people could potentially view your code, but not change it. GISTs come in two flavours: secret and public. Even when you use the secret one, other people could view your script if you share the URL with them. And if you create a public one, everyone can discover the script or search for parts of your code at GitHub – even if you haven’t shared the script’s URL.
Please make sure you do not violate your company’s data security policies!
Step 1: Get a GitHub account
If you aren’t already: sign up at http://www.github.com/join. You can start with a personal plan for free. You do not need to setup an organization.
After confirming your email address, go to https://github.com/settings/tokens and press ‘Generate new token’. You will later feed the AdScriptor editor with the generated token so that it has permissions to access your GitHub repository to create and modify your AdWords Scripts.
Select the scopes gist and user and give the token any name you’d like to and press ‘Generate token’:
The next screen will show you the token. It looks like a mysterious string consisting of numbers and digits. You will need it later, so save it in a secure place like a password manager and log out of GitHub for now.
Step 2: Download and use AdScriptor
AdScriptor is a browser-based editor that integrates nicely with GitHub and brings you more comfort when editing AdWords scripts. You can download it from https://github.com/crealytics/adscriptor.
Unzip the file to a local folder on your machine or copy it to a webserver. If you chose to open the index.html from your local machine, make sure you use Firefox. If you copy it to a webserver, you can also use other browsers like Chrome or Microsoft Edge to open it.
After the browser has launched, AdScriptor will ask you for the GitHub Token you created in Step 1. Paste it in there and press OK.
You are now connected to your GitHub account. You should be able to see your GitHub account name on the right hand side in the menu. You can create a new AdWords Script by selecting “Repository > New Script”. Assign it a name, e.g. MyFirstScript_v1. Do not check the Public option. To edit, double click on it in the Scripts section.
There are 4 main sections apart from the menu in AdScriptor.
1 – The Scripts section shows you all scripts in your GitHub repository. You can add or delete Scripts by using the Repository menu.
2 – A single script may span over multiple files to help you to structure bigger projects. Click to edit a specific file. Using the Script menu, you can add or delete files associated with a script.
3 – The editor area. This is where you actually write the code. You can change colours by using the Theme menu. Apart from syntax highlighting, the single most useful function can be called by pressing CTRL + Space. Autocompletion, finally!
4 – The log. You will find messages about AdScriptor activities here.
Now you can start writing your code in the editor. Remember, you will always need a function called main(). This will be the entry function called by AdWords.
AdScriptor saves your changes automatically from time to time. Nonetheless – always save your script (CTRL-S) at the end of your session to make sure you don’t lose the latest changes.
Step 3: Create Embedding Scripts in your AdWords account
After you have finished editing, you need to copy the AdWords Embedding Code that AdScriptor will provide for you. Just call the menu Script > Get AdWords Code.
Now go to the AdWords web interface, create a new AdWords Script and paste the AdWords Embedding Code in there. Let’s call this the AdWords Embedding Script, as it is responsible for getting the latest version of your code from GitHub and execute it in your AdWords account.
Press Preview. You will be asked to authorize the script. After doing so, hit Preview again – your script should now execute – and give you a logger output.
If you want to execute your script in several AdWords accounts, just create an AdWords Embedding Script in each account – pasting the same AdWords Embedding Code from AdScriptor in there.
There you go – every change you make to your code in the AdScriptor will be executed in each account, without having to adapt any of them.
Congratulations! You just took the first step towards a more powerful AdWords Scripting environment. In the next parts of this tutorial, we will show you how to return to older versions of your scripts and how to effectively conduct a simple, but very powerful release management. Of course, we’ll also cover AdScriptor in a little more depth and provide you with some more real life best practices.
Let us know how you get along with the new tool stack – we’re happy to take your comments and suggestions.
AdScriptor and it’s components are all licensed under the MIT License, which basically means you can do anything you want with it as long as you distribute the LICENSE.md file with it.