You run an AdWords agency. You’re thinking about building an AdWords tool using the AdWords API.
- You might want it to make your agency more efficient. You’ve outgrown your duct-taped together collection of scripts, spreadsheets and rules. You want to spend less time on drudge work and more time on strategic value-add tasks. Maybe you want to grow without hiring.
- You might want a second income stream. Selling an AdWords tool takes a lot of stress off relying on client work. Even more so if you charge a regular monthly subscription. It’s one of the few ways we have of growing our businesses that isn’t directly tied to our time.
Context: In this essay I’m going to use the word app to describe your custom-built AdWords tool.
Unless you’re lucky enough to have a tame developer in the office, you’re going to have to find someone to build your app.
There are plenty of competent developers around. There are plenty of competent AdWords specialists about. The subset of competent developers who know AdWords is much smaller.
It's even smaller after you've filtered it down to people who -
You might be tempted to recruit a developer from a freelancing marketplace. Sites like upwork, fiverr etc make it look possible to hire a highly-skilled freelancer from a low-cost-of-living country for a handful of beans.
In practice, freelance marketplaces are markets for lemons.
Let me explain.
It is true that a competent developer might start her solo career on a freelancer site. Being a good developer doesn't automatically make you good at finding clients and these sites offer developers the promise of well-heeled clients from high-cost-of-living countries.
The client can't tell the difference between a competent developer and an idiot at the time of hiring. The risk of failure gets priced in to what the client will pay. That drives rates down.
Any developer who is capable of meeting your technical specs and communicating professionally eventually realises that they're working for peanuts.
So they leave, and the average skill level goes down.
That leads to a worse experience for the clients who in turn lower what they’re prepared to pay or stop hiring on these sites.
So the site ends up full of inexperienced buyers hoping to get their project built for $27, and a bunch of desperate developers who promise the world, deliver junk and have the communication skills of a turnip.
(Freelancer marketplace sites being a market for lemons inspired by tweets by @patio11.)
You don’t want your app to be built by someone you end up hating. Reasons for this will be clear later.
The next biggest risk, after hiring, is that your developer won't understand exactly what you want before they start work. It is not a given that your developer can read minds.
The assumption zone is where your assumptions about the project are different to the developer's assumptions about the project.
It can take several weeks of programming before your app is sufficiently complete to know that there is a problem.
You rightly won’t want to pay for wasted effort or re-work, and your developer rightly won’t want to work for free.
The rest of this essay is a list of things that I've bumped into over the years that trip people up when building AdWords tools using the AdWords API. The list is in no particular order.
Context: I’m writing from the point of view of building web apps. Much of this essay is also relevant if your app is installed software or a mobile phone app.
A web app is a program that runs in your web browser (Chrome, Safari, Firefox etc) instead of being downloaded and run from your computer.
The regular AdWords interface at www.adwords.google.com is a web app. AdWords Editor is installed software.
Your app will need to be hosted somewhere. Shared hosting or a cheapish reseller hosting account probably won’t work. You’ll want to check this with your developer.
An app for internal use won’t need much in the way of hosting - a $10/month Amazon Web Services EC2 instance might be enough.
If you’re building an app for the world to use it’ll need hosting hefty enough to handle the traffic, processing and storage requirements.
Your app should use the secure HTTPS protocol rather than the insecure HTTP protocol. You’ll need a SSL certificate for this.
These range in price from free from Let’s Encrypt to a couple of hundred dollars a year.
Installing and updating the certificate is a painful manual process at some hosting providers. At other providers it's a one-click install with automatic renewal.
You need to back up:
An automated system is best. It should back up periodically and delete older backups. For example, you might want to back up once a day and keep the daily backups for 30 days.
Backing up is only half the process. You also need a way of verifying that the backups worked and know how to restore from backup.
I don’t have to tell you that AdWords generates a lot of data. I bumped into a problem where an app I built stored daily performance reports from a few hundred campaigns. It worked fine at first but eventually the database got so big that the backup program couldn't finish.
Think about what AdWords data your app has to store and for how long it must be kept.
Some developers write automated tests to check that the code they wrote - your app. They’ll refer to these tests as unit tests and integration tests. The difference is irrelevant for your purposes.
Automated tests do the same job as having a human click every button or link in your app to make sure it's working as expected. The difference is that testing programatically takes only seconds.
Having a comprehensive test suite makes it much faster and safer to update or alter the app later. But, writing these tests takes time (aka money).
Reducing the number of tests is a common compromise if the budget is tight or if you're building a limited first version.
This compromise isn't always right for AdWords apps because the computer code your app uses to interact with Google has to be updated frequently. More on this later.
Automated testing doesn’t usually include checking that external services are working. You should make an exception and have your developer write tests to ensure that you’re getting good data from Google, and that changes you make via your app work.
Your app will wrangle commercially sensitive data. That data must be safe from unauthorised access or modification.
The best way to ensure security at a reasonable price is to use a web app development framework.
A framework - Laravel or Ruby on Rails are popular - is a set of pre-written computer code for handling features that most web apps need.
If your developer uses a framework you won't have to pay to reinvent wheels like checking a form for valid input or making sure only an authorised user can pause a campaign.
A good framework includes computer code to lower the risk of a security breach. Using a framework is infinitely more secure than hoping your chosen developer is both an expert in AdWords and a top-notch security professional.
Your developer will need credentials like usernames and passwords while developing. You should ask your developer to give you a list of places where credentials are stored, and instructions on how to change them.
You should revoke the developer’s credentials once they no longer need them. You’re not doing this to be malicious or because you’re distrust them, but because it’s the right thing to do.
Your app will need a way for people to register, log in, log out and reset their passwords.
Again, a framework will do most of the heavy lifting, but don't assume that your developer knows that they are to build it.
If you’re building an app for the public, you’ll need to make sure that each user can only access their data, not other user’s.
This may also be applicable if your agency assigns clients to individual staff members.
I don’t have to spell out how uncomfortable things could get if you paused a campaign or dropped the daily budget by half in your app but something went wrong and those changes weren’t made in AdWords.
These kinds of communication errors between your app and AdWords do happen. We’ll talk more about why in the rates limit section later.
You’ll need to think about how you want to your app to respond when something goes wrong. You might choose to have the app retry a few times, or to display a message on screen, or to send an email etc.
If your app is open to the public, or you do remarketing you’ll probably need to follow local data protection requirements.
At the very least you’ll need a privacy page because you can’t get an OAuth token without one. You need an OAuth token to let Google know that it’s OK to let your app connect to your AdWords account. (More on this later.)
If you're building an internal app for your agency you could get away with a fumbling first time. If you're building an app for the public it must offer a great first experience.
You have a pretty good idea of what your app will look like once it’s got your campaigns, ad groups, keywords etc in it. But, what does it look like empty?
The first run flow will usually be different from the way the app is used every day. What happens after your user hits the register button?
I’ll show you how to communicate your expectations to your developer a little later. But, first, here is a list of things that are not common knowledge about the Google AdWords API that trip people up.
Google requires that you apply for an AdWords API developer token before you can use their API. You should apply as early as possible because not getting approval is a deal breaker.
Apply for your token from your main manager account (aka MCC). That'll give your app access to the manager and client accounts under it without having to authorise each account.
More information on the application and approval process here.
You may have to prove that your app can connect to AdWords and process data before you get final approval. You should allow some contingency time and budget for your developer to write code to demonstrate this.
Anecdotally it’s easier to get approval for basic access than it is for standard access. (See section on rate limits for the difference between basic and standard access.)
There are some things that you can do in your AdWords account that you can’t do using the API. Make sure that the API supports your intended use.
Ignore this if you’re building an app for internal use only.
If you’re building an app that your clients or the public can use you need to meet the required minimum functionality requirements.
These requirements specify what your app has to be able to do. For instance, if your app does keyword research it also has to allow your users build campaigns, manage them and get reports.
You’ll find the requirements here.
That's geek speak for "You have to update your app or it won't work". At the time of writing every API version lasts approximately nine months.
It's impossible to say how long these updates take because that depends on what your app does, and if Google has made significant changes to the parts of AdWords your app interacts with.
This is where a good relationship with your developer and a robust test suite come in. Your developer can make the necessary changes, run the tests and be confident that everything works.
Read more about the sunset and deprecation schedule here.
Google offers two levels of API access - basic and standard.
Basic access has hard limits on the number of times your app can get reports and data from AdWords and send changes to AdWords. In practice, these limits are high enough for many apps.
If you need to access the API more often you can apply for standard access which has no limits.
More information on rate limits here.
On-the-fly rate limits apply to all apps, whether they have basic or standard access.
Google prevents people overwhelming the API by limiting the frequency at which your app can make requests - get data or send changes.
Dealing with Google's on-the-fly rate limits is more complicated than it is with many of the other APIs your developer might know.
This is because:
If your app hits the limit the request gets rejected. You might have hit the pause campaign button in your app, but that campaign won't be paused in your AdWords account. Instead the API returns a rate exceeded error.
Dealing with this should be simple. The rate exceeded error message includes how many seconds you should wait before retrying. Your app should catch the error, extract the wait time, wait that many seconds and try again.
In practice it’s not. There appears to be no guarantee that waiting the required time will result in a successful operation. The AdWords API developer forum is filled with unhappiness and clumsy workarounds.
Perhaps your app has a button to pause a campaign.
When you click the button your app sends an instruction to AdWords to pause the campaign. AdWords responds with "The campaign was paused". Your app changes the text on the button from “Pause campaign” to “Enable campaign”.
Your developer will know this process as the request -> response cycle.
The app will feel laggy if it takes more than a second or two for something to happen after you click the button.
You are unlikely to get sub-second responses from the AdWords API all the time. It might take a couple of minutes if your request hits a rate limit and has to retry.
You can keep your app feeling snappy by taking communication with AdWords out of the request -> response cycle.
When you click the “Pause campaign” button your app adds the instruction to AdWords to a job queue and then changes the button to “Enable campaign”. It feels quick and responsive.
The job is handled in the background, invisible to the user. It doesn't matter if it takes 5 seconds or 5 minutes.
Of course you need a way of detecting if something went wrong and telling the user about it. See the section on error handling above.
A human, a rule, automated bidding or a script can make changes to your AdWords account. If your app doesn’t have a way of becoming aware of these changes you could end up making decisions on stale out of sync data in your app.
The best way of doing this depends on what data your app needs and what it does. I’m always happy to speak geek with fellow AdWords people so hit me up if you’d like to talk about this.
Unless you have deep experience you should leave the choice of technology to your developer, subject to a few caveats:
Frameworks like Laravel (PHP language) or Ruby on Rails (Ruby language) are safe bets if your app is web-based.
Ignore this if you’re building an app for internal use only.
Some people who profess to be AdWords experts know very little. You may have audited an AdWords account that looked like a gorilla managed it. You ain’t seen nothing yet.
You haven’t scraped the dregs off the bottom of the incompetence barrel till you’ve run a public AdWords app.
You’ll need to think about the cost of:
The bus factor is a measurement of the risk resulting from information and capabilities not being shared among team members, from the phrase "in case they get hit by a bus".
If you’ve hired a lone developer you’ve got a bus factor of one. Hiring a development shop might reduce this risk.
You should do the following to mitigate this risk no matter who you hire.
Store the code on Github.
If the computer code that makes up your app exists only on your developer’s laptop you’re vulnerable.
You can get rid of this vulnerability by having your developer use Github to store the computer code. Most developers will be familiar with it.
You should set up an account on Github and set up a repository for your app in your account. You then invite your developer to collaborate so they have the access they need.
If you don't know how to do this you should have your developer walk you through the process.
When I'm developing apps I push my work to Github at the end of the day. That way my client can continue developing the app if I get hit by that bus.
Own your OAuth credentials.
Your OAuth credentials allow users of your app to tell Google it’s OK for you app to access their AdWords account. You should set these up in your account even if you have your developer guide you through the process.
Own your developer token.
If you apply for this via your main AdWords manager account you’ll have taken care of this.
Grab a pencil and paper. Draw every screen you think your app will need. These are called wireframes.
Don't get bogged down in details like colours, gradients, fonts etc. Keep this low-fidelity but include every link and button, and examples of the data you’ll want to show.
If your app has a screen that shows low CTR keywords and you want to show the parent ad group and campaign you should include that on your sketch. This will tell your developer that they need to get the ad group and campaign name when they get the keyword.
These wireframes will help you fly over the assumption zone.
After you've drawn the wireframes you should describe what each button and link does.
Links are pretty easy because they’re normally used for moving around the app. Something like “Click the Dashboard link and see the Dashboard view” is enough.
Buttons are a more complicated because you need to be explicit about what happens when they’re clicked.
For instance you might have a "Generate report" button. Your description could read:
When the user clicks the "Generate report" button
This detail is gold to a developer and it will save you money. The quote (estimate) to build your app is going to be much higher if your developer has to pad their price to cover a bunch of uncertainties.
It’s cheaper and easier to stop a user sending more than one report a week when it’s built into the system from the beginning. Even simple requirements can cost lots more if they have to be bolted on later.
There is another reason for wire framing: Google may want to see designs before they approve your developer token. It’s been my experience that wireframes plus a detailed description of what the app will do is often enough to get approval for basic access.
Aside: If you don’t want to use a pencil and paper, use Balsamiq to draw your wireframes.
Want to talk about some aspect of the API or this essay? Email me (email@example.com) for a no-cost, no-obligation chat. I’m always happy to talk AdWords and code.
We’ll start with a road mapping session. This takes 2-3 hours, usually over two sessions Skype/Hangouts/Zoom etc.
The road mapping session is an investment in risk reduction.
At this stage the biggest risks that your AdWords API app development project faces are:
At the end of the road mapping session you’ll be confident that your app is technically possible and complies with Google’s requirements. You’ll have a solid set of wireframes and requirements with which to brief your developer. (Me or someone else). You’ll know exactly what the next step is.
If you'd like, I will give you a fixed price offer to build your AdWords API app after the road mapping session. You won't have to worry about nasty surprise costs or arguments about what was included and what is extra. Otherwise, you're welcome to use any developer you like.
Lets start with a no-cost, no-obligation chat. Email me (firstname.lastname@example.org) and we'll arrange to meet online.
Centaurs - human+computer teams will outperform and replace AdWords agencies that rely on human power alone. Here are four ways to enhance your AdWords powers with automation.
Here's how you handle authorization for multiple users of your AdWords API tool.
You’re thinking of building a custom keyword research tool using the AdWords API. Read on to see where to start and what to watch out for.
The AdWords interface is awful. You can fix this in your AdWords tool. Here are a handful of principles to guide you as you design your custom AdWords API based tool.
Will your custom AdWords tool monitor AdWords performance? It's surprisingly difficult to work out when your monitoring system should warn your users. Read on for guidelines on alerts and notifications.