You run an digital marketing agency. You’re thinking about building a custom Google Ads tool using the 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 Google Ads 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.
In this essay I'll share some things that I've seen sink custom Google Ads tool projects and then show you how to get started.
I've seen too many people's hopes crushed by avoidable mistakes when building custom Google Ads tools using the API. You must be aware of these issues or you'll waste time and money (possibly lots of both).
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. (In this essay I’m going to use the word app to describe your custom-built Google Ads tool.)
There are plenty of competent developers around. There are plenty of competent Google Ads specialists about. The subset of competent developers who know Google Ads 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 swamp 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.
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 Google Ads 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 Google Ads 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 Google Ads 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 Google Ads 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 Google Ads.
These kinds of communication errors between your app and Google Ads 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 Google Ads 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 Ads API that trip people up.
Google requires that you apply for an Google Ads 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.
You may have to prove that your app can connect to Google Ads 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 Google Ads 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 Google Ads 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 Google Ads and send changes to Google Ads. 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 Google Ads 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 Google Ads 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 Google Ads to pause the campaign. Google Ads 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 Google Ads 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 Google Ads out of the request -> response cycle.
When you click the “Pause campaign” button your app adds the instruction to Google Ads 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 Google Ads 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 Google Ads 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:
Google provides code libraries - pre written computer code in several computer languages: Java, .NET, PHP, PERL, Python and Ruby. Using these will make the initial development and future maintenance faster and cheaper. Your developer should have to work incredibly hard to convince you not to use one of these languages.
Many developers like to use the latest bleeding-edge hot language or framework. This is not always in your best interest. If you build you app on solid proven technology the quirks and errors have been ironed out; there is a bigger pool of people with appropriate skills and experience and the technology is likely to be supported for a few years.
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 Google Ads experts know very little. You may have audited an Google Ads 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 Google Ads 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 Google Ads 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 Google Ads 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
If there were no conversions during the last 7 days, send the no conversion email template to the client.
If there were conversions, send the regular conversion report. Format the report as a PDF and send it to the client’s primary email address. CC copies to the client’s other reporting email address.
If any of the email addresses bounce, send a bounce email warning to me.
Keep the user on the same screen. Show a confirmation message and disable the report button so the user can't send more than one report a week.
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.)
At this stage your biggest risks are:
You can eliminate the risk with a road mapping session where discuss what you plan to build.
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. You’ll know exactly what the next step is and what the project is likely to cost.
Road mapping costs $450 and takes 2-3 hours, usually split over two sessions on Skype/Hangouts/Zoom etc.
Want to book a road mapping session? Email me firstname.lastname@example.org.
Here's how you handle authorization for multiple users of your AdWords API tool.
You run an digital marketing agency. You’re thinking about building a custom Google Ads tool using the API. Here are some of the things that trip people up.
I bumped into an unexpected problem when I chose the Ad-Minister.app domain.
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.
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.
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.
Good news is that you don’t a programmer who is an expert at the AdWords API because the programming constructs that the API uses are well known. For instance, the API uses OAuth for authentication which is very common.