A script for getting granular AdWords account anomaly alerts

Many exciting AdWords scripts have been shared on this site over the past couple of years, from scripts that enable hourly dayparting to ones that update bids based on the weather using machine learning and Google’s Prediction API.

I’ve had fun writing some complex scripts like these myself (mine handle bid management and connect inventory with AdWords), but it’s usually my more mundane scripts that get the most response, because let’s face it, more of us are interested in automating the basics and getting those right before we can even afford to spend brain cycles on the more cutting-edge stuff that gets engineers excited.

Case in point: Last month, I shared a script for handling the basic account management task of updating budgets every day to ensure the full allotted amount is spent every month. That script got a great response, so I thought I’d share another automation for one of the more routine tasks all account managers do: detecting anomalies within an account.

Before I share my solution, let’s review some of the alternatives that are already widely available and why I think those needed to be improved upon.

Google’s Anomaly Detector script

Google has an excellent Anomaly Detector script, which we at Optmyzr (my company) have upgraded with a few extra capabilities, like aggregating the data into a single spreadsheet.

The one piece of feedback I most often get about this script is that it doesn’t identify what part of an account is responsible for the anomaly. Not only would it be nice to know when an account is not performing at the expected level, it’d also be good to know if there were any particular outliers that were causing the change in performance.

Google’s Account Anomaly Detector AdWords Script. Screen shot courtesy of Google.com

Another shortcoming of the script is that it analyzes account-level data, and if some parts of the account do better and others do worse, they may cancel each other out and the account may look like it’s doing fine. But then we’d miss the opportunity to fix poorly performing elements, which, together with the well-performing elements, could have taken the account from average performance to stellar performance.

AdWords’ Top Movers report

Another solution for finding anomalies is Google’s Top Movers report under the Dimensions tab in AdWords. A big limitation of this solution is that it doesn’t send alerts, so unless account managers check it frequently, account issues could easily fall through the cracks.

Additionally, it also only evaluates campaign- and ad group-level changes, so if we’re looking to understand what is happening at the keyword level, we need something better.

An AdWords script for granular anomaly detection

Now that you understand what I was trying to improve upon, let me share how I went about building my script.

I wrote an AdWords script several years ago to generate a spreadsheet that compares performance of various account elements across different date ranges. That script became a lot less useful when Google introduced more flexible date range comparisons in their interface. I kept my script available on our site, even though I didn’t think it would be all that useful anymore.

When talking to some customers recently, it dawned on me that this old script already does most of the work needed to be able to alert account managers when parts of their account are changing dramatically. It already grabs data for two date ranges and writes it all to a Google Sheet. All that I needed to change was to add a way to generate an email alert if any of the changes exceed a user-defined threshold.

I wanted to make this script as useful as possible for as many advertisers and use cases as possible, so figuring out what settings to add was my next item of work.

Selecting date ranges to compare

I wanted users of the script to be able to have the flexibility to compare the date ranges they find relevant. For example, some might want to compare yesterday’s performance to the day before, whereas others might prefer to look at yesterday compared to the same day last week.

Users who want to evaluate changes in conversion data might even want to compare data from a few days ago, giving AdWords enough time to import data from Google Analytics (which can take several days for larger accounts).

Others might think it’s more relevant to compare the data for a few days, rather than a single day.

So here are the settings in the script that allow for very flexible date range selection through four variables:

• How many days ago the current lookback window starts:

  currentPeriodStartsNDaysAgo = 6;

• How many days ago the current lookback window ends:

  currentPeriodEndsNDaysAgo = 1;

• How many days ago the date range to compare to starts:

  previousPeriodStartsNDaysAgo = 13;

• How many days ago the date range to compare to ends:

  previousPeriodEndsNDaysAgo = 8;

In the above example, I am comparing the data for the previous five days with those same weekdays from last week: comparing six days ago through yesterday with 13 days ago through one week ago yesterday.

Selecting thresholds for alerting

Being able to choose the granularity of when to get alerts is another important element of creating a script that is useful. I wrote a couple months ago about alerts getting ignored because there are too many and important ones getting drowned out. So there are four levels of settings I included to help narrow down when alerts should be triggered.

1. Changes that are big percentage-wise and in absolute numbers

A challenge with alerts that I specifically experienced with Google’s Anomaly Detector is that the threshold is based on the percentage change. Requesting alerts for any deviations of more than 10 percent means you’ll get an alert if the performance goes from five clicks to four clicks (a 20-percent decline), but is that really a meaningful insight? The absolute value of the change should also be part of the threshold.

Here’s the setting that tells the script to only send alerts when the absolute value of the numbers is big enough.

• minAlertImpressions = 20;

The setting above says that there should be at least 20 impressions in either of the date ranges that are compared. A keyword that goes from 15 impressions to two impressions would not trigger any alert, whereas a keyword going from 15 to 20 could trigger one.

2. Alerts for increases, decreases or both

Some people only want to hear about decreases in performance, whereas others want to be alerted for any significant change. The script I wrote lets users set different thresholds for improvements and declines in performance.

Here’s an example where we say that we want an alert when impressions increase by 10 percent or decrease by 20 percent:

• minDecreaseForImpressionAlert = -0.2;

• minIncreaseForImpressionAlert = 0.1;

Set either value to “0” to get NO alerts. If you want to get alerts for even very small changes, you can put in something like “0.0001,” which is 0.01%.

3. Alerts for certain metrics

We may only want alerts for certain metrics, so this script lets you specify which metrics should not trigger any alert.

Continuing with the example from above, set either value to “0” to get NO alerts. If you want to get alerts for even very small changes, you can put in something like “0.0001,” which is 0.01%. So with this setting you’d get no alerts for any changes in impressions:

• minDecreaseForImpressionAlert = 0;

• minIncreaseForImpressionAlert = 0;

4. Alerts for different account elements

Finally, I wanted a setting to let users specify if they want to get alerts when the account performance changes, or also when lower levels of hierarchy like campaigns, or ad groups, or even elements like ads or keywords change.

The following five variables control this. Just set the value to “1” to include it or “0” to exclude it:

• includeAccountLevel = 0;

• includeCampaignLevel = 0;

• includeAdGroupLevel = 1;

• includeKeywordLevel = 0;

• includeAdLevel = 0;

The script

Here’s the script that you can copy and paste into AdWords. You’ll probably want to schedule this to run once per day, after 3:00 a.m., so that stats through yesterday should be complete in AdWords.

When updating your settings, also be sure to enter your email address and Google account so that you’ll have access to the spreadsheet the script generates and get an email alert when there are anomalies.

Conclusion

Having great alerts helps us spend our limited time on things that help improve account performance, rather than looking for issues. And when we spend more time optimizing accounts, we will hopefully get fewer alerts about problems, so I hope this script helps people start this virtuous cycle of using AdWords Scripts to recoup some precious time.