The Moron’s Guide to Setting Up Google AdWords API

I am not a programmer.

I am not some fancy backend server guy that typically tries to accomplish great technological feats.

But I’ve always been curious about the Google AdWords API. We have our developer token from a previous project. (I should say, this tutorial is  not about applying for your developer token. This story picks up after that rather involved process.)

As a person who is not familiar with the ways of programming I found there were some holes in the process that weren’t particularly clear to me as I trudged through getting things setup.

I thought I’d put together a post walking through the steps I took to get to the point I’m at today: producing pretty cool reports on a Web browser using PHP.

If someone who has more experience than me finds I’ve said something incorrect or misguided please feel free to let me know.

But this is primarily for us uninitiated,  non-programmers that want to venture into the world of the AdWords API.

I’m calling it “The Moron’s Guide to Setting Up Google AdWords API” not because I feel you are a moron but because that’s the level of ability I put myself at as I did this work.

I’m pretty sure that if I can do this you can do this.

Here we go:

First, you might find it helpful to know where I’m starting. I have never ever worked in an object oriented language. I’m pretty good at html and passable at css.

While I can look at templates in WordPress and struggle to move things around a little bit, that’s where my PHP understanding stops.

That said, I recently worked my way through an online class of PHP at Codecademy.

I originally began studying languages because Learn Python the Hard Way was recommended to me. I didn’t finish the whole thing. But I will say it is awesome! While Codecademy is funded and has fancy online interfaces, Learn Python the Hard Way was a better experience.

Unfortunately, I didn’t think I had an easy way of porting my Python work to the Web. I didn’t really want to configure a server.

PHP is just more available online. While I haven’t done it yet, I feel pretty confident I could take my reports I’ve created in the AdWords API in PHP and upload them to GoDaddy.

PHP, in general, is not as nice to work in as Python. Python feels more systematic. The error codes are much clearer. I hope to get back to Python again some day.

All this said, I think having a minor understanding of the programming language you are going to be working in is probably helpful.

While there are a lot of good example codes available, they are only examples. They are not going to do exactly what you ultimately want to achieve.

By no means am I some PHP expert.  But I can read it, for the most part, and vaguely understand what it’s achieving.

Learning a programming language is a cool achievement, any way. You will be proud of yourself for doing it.

I’m pretty proud I made it through all the quizzes at codcademy:

PHP   Codecademy

That’s where I entered the world of the AdWords API.

The door to your new adventure is here: AdWords API — Google Developers.

This is where you are going to spend the next 20 hours of your API life.  And you are probably going to be reading a lot of stories here:  AdWords API Forum – Google Groups.

While all the answers to your questions reside in those two places, my hope is that I can give you a little more insight into things that I struggled to find.

Going forward, this is all going to be about using PHP to interact with the API. That’s the only area I have looked into.

The more you read and watch the videos from AdWords API — Google Developers, the better experience you will have.

But here are two things I strongly recommend going forward:

  1. Get PHP running on your machine at home. Don’t try doing this on some server you don’t control.
  2. You need to be able to run PHP from the command line. You simply will not make this work without doing this initially.

I am running Windows 7 on a PC. I Downloaded XAMPP as my Apache server and PHP platform.

There are others of these types of programs around. But XAMPP worked great for me. It is easy to install and get running.

From here: googleads/googleads-php-lib · GitHub – the requirements say you need these things:

PHP

Build environment

What I can tell you is, all the PHP requirements are automatically running in XAMPP.

You can double check, if you want in the XAMPP admin panel:

XAMPP 1.8.3

If you have more questions about XAMPP just let me know.

As for Build environment

I couldn’t figure these things out. I didn’t look at them that closely.  I might have worked around them using XAMPP. But I can tell you that I’m happily working my way through all of this without either of those two things.

The next thing you are going to want to do is get your Client Libraries & Code Examples.

They come in many different flavors. But I’m using PHP.

You are going to want to get your “Distribution”:

Client Libraries   Code Examples   AdWords API — Google Developers

Fancy programmers can’t just “zip” things. They have to “tar” them.

When you click on your distribution you will be taken to another page. You want both the library(lib) and the examples:

Releases · googleads googleads php lib · GitHub

Once you download that, if you don’t have a program that automatically opens it you are  going to need to get one. Just Google “How to open a gz file in Windows” and you’ll find a bunch of them. 7-Zip is popular one.

Under my htdocs folder in xampp I created a new folder called ‘adwords’ and moved the lib, build_lib and examples folders to it. Like this:

xamppgoogle(you can click on all these pictures to see a bigger version, btw)

OK. Now everything is in place.

If you open the readme file that comes with all the files you downloaded they say to get start go here:

googleads/googleads-php-lib · GitHub

If you scroll down that page a bit you will find a “Getting Started” area.

Step One: Register an OAuth 2 application.

Here, my friends, is where it all gets interesting.

This trips up a lot of people, from what I’ve seen on the discussion forums.

And the biggest issue, from what I’ve seen and experienced, is you must, must, must do this on the command line. The file you need to use simply will not work on a Web browser.

If you are new to this whole world this is a big black hole of mystery. They just say, “and do this in command line.”

That took me about 3 days to figure out.

Here’s the deal, you need to set this up in Windows to get it to work. This blog post solved my problem: Running PHP using Windows command line with XAMPP | Shi Chuan’s blog

The site seems to be down at the moment. But these are the steps:

If you have installed XAMPP, and want to use command line to run PHP on Windows, here is how you can do so.

1. Right click on the Computer icon on your Desktop and choose Properties option.
2. In the System window click on Advanced system settings in the left pane as highlighted below
3. In the System Properties window select Advanced tab and click on Environment Variables… button given at the bottom of the window as highlighted below
4. In the Environment Variables window you will notice two columns User variables for a Username and System variables.
5. Under System variables there is a Path variable, click edit
6. At the end of the line, add where you installed your xampp, for my case it is: ‘;C:\xampp\php’
7. Click OK.
Now you can start running Windows Command Line

system2

Now you are going to want to open ‘cmd’. Just open your Start button and do a search for cmd. Like this:

cmd

Personally, I’d recommend getting that all setup before you proceed to “Step One: Register an OAuth 2 application.”

But you may be some programming genius and have already figured that out. If so, I wish I was as smart as you.

They tell you to go here:

Using OAuth 2.0 · googleads/googleads-php-lib Wiki · GitHub

I have found that this process does indeed work. There are other solutions out there, primarily from Ewan Heming (who I’ve had the opportunity to work with and is awesome): Getting AdWords API Tokens from the OAuth Playground

But this works fine: Using OAuth 2.0 · googleads/googleads-php-lib Wiki · GitHub (as long as you have the whole command line thing setup).

You need to go visit Google Cloud Console (I always think of “Cloud City” when I’m “visiting” Cloud Console.)

Do everything on this page: Using OAuth 2.0 · googleads/googleads-php-lib Wiki · GitHub

Step 5 is a key here:

  1. Choose either Installed application or Web application depending on the style of your application
    • If you wish to use our sample code GetRefreshToken.php to generate a refresh token, then you have to choose Installed application.
    • If you choose Web application, you will also need to write your own web application that can complete the OAuth 2.0 flow.

If you are at my level of ability I would recommend using “GetRefreshToken.php” because writing your own web application sound terribly impossible to me.

But installed applications work fine on the web. I’m running my stuff online as an installed application.

Something they don’t mention is the “Consent Screen.” This need to be filled out. It’s right below “Credentials” on the left navigation:

Google Developers Console

I feel like things get a little vague in the documentation at this point.

After you get your credentials you are going to need to start working in the GetRefreshToken.php file.

I personally use Notepad++ which is a tip I got from “Learn Python the Hard Way.”

In all that stuff you downloaded above you will find it here:

/ examples / AdWords / Auth / GetRefreshToken.php

And in my XAMPP setup the full address is:

C:\xampp\htdocs\adwords\examples\AdWords\Auth\GetRefreshToken.php

You are going to eventually run that file in command line. But not before you fill out auth.ini.

In my xampp set up it is here:

C:\xampp\htdocs\adwords\lib\Google\Api\Ads\AdWords\auth.ini

In auth.ini you need to update this:

developerToken = “foundinadwords”
userAgent = “thenameyouregistered”

To find that, log into your MCC account (you have one of those, right? If not you need to solve that issue first) It’s under “Account Settings” then go to “AdWords API Center”.

You’ll find that information here:

AdWords Account Preferences

 

If you don’t see this make sure you have already signed up for the API access here: Signing up for the AdWords API – AdWords API — Google Developers.

It doesn’t just come with the account.

Your auth.ini file looks like this:

authini

 

Of the 3 areas that need to be filled out, the last area is what you are going to get from running the GetRefreshToken.php from the command line.

But the first two areas need to be filled out first before you run GetRefreshToken.php.

Does that make sense?

OK. Here’s where the magic starts to happen if you’ve gotten this far.

You are going to run GetRefreshToken.php from the command line.

If this is your first time running a command line script this is how you do it:

  1. Open up command line like I showed you above:
    Click on Start and in the search bar type: cmd
    You will see it there and click on it. It’s going to look something like this:
    cmd2
    The first problem you are going to have is that you aren’t in the right directory. You need to get to a place like: C:\xampp\htdocs\adwords\examples\AdWords\Auth\GetRefreshToken.php
    But you are some place like: C:\Users\Yourname>
    To get back to the start type: cd c:\
    Hopefully you will be here: C:\
    That’s perfect!
  2. You now need to make your way to this directory: C:\xampp\htdocs\adwords\examples\AdWords\Auth\
    Just type: cd xampp\htdocs\adwords\examples\AdWords\Auth\
    With any luck you will see on your screen:
    C:\xampp\htdocs\adwords\examples\AdWords\Auth\>
  3. If you’ve done everything up to this point you should be able to type: php GetRefreshToken.php
  4. You are going to see something that says:
    Log in to your AdWords account and open the following URL:https://accounts.google.com/o/oauth2/auth?response_type=code&client_id=233867888761
    839-p5dfdf67gdAFADFDADF82.apps.googleusercontent.com&redirect_uri=urn
    %3Aietf%3Awg%3Aoauth%3A2.0%3Aoob&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2
    Fadwords&access_type=offlineAfter approving the token enter the authorization code here:
  5. Take that url: https://accounts.google.com/o/oauth2/auth?response_type=code&client_id=233867888761
    839-p5dfdf67gdfgfg5peq47dafdu82.apps.googleusercontent.com&redirect_uri=urn
    %3Aietf%3Awg%3Aoauth%3A2.0%3Aoob&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2
    and paste it in your browser.
    Incidentally, that can be a challenge in itself. I right click on the command screen window, click “select all” and then press ‘Enter’.
    I then copy and past all of that into notepad and get the url from all of that content.
  6. When you log in you will get an authorization code. Copy that out of your browser, go to your command line window and then right click in there and click “paste.”  You should have gotten that code from windows that look like this:
    68747470733a2f2f6c68332e676f6f676c6575736572636f6e74656e742e636f6d2f2d4a5439384f6f623534726f2f5547424b544465436a6b492f414141414141414141484d2f6f5537443044316e4a63302f733731362f626c6f67312e706e67
  7. You are going to then take that code (the refresh token) that is produced in the command line and paste it back into your auth.ini file:
    C:\xampp\htdocs\adwords\lib\Google\Api\Ads\AdWords\auth.ini
    It’s the last lines of that file:
    ; If you already have a refresh token, enter it below. Otherwise run
    ; GetRefreshToken.php.
    refresh_token = “adsfasfdasfadfadfjjdfjadkj”

    Just put it in between those quotes.

If you’ve done that you are golden.

That process took me a bunch of hours. And really was the reason for me writing this post. Hopefully it will have helped you.

I did run into another hurdle along the way, however.

I couldn’t get the examples to run in a Web browser. I thought maybe there was an additional step I needed to take or possibly my token wasn’t setup to work on a Web browser.

That’s not the case at all.

For some reason, that I still haven’t figured out, the example scripts have a line that reads:

// Don’t run the example if the file is being included.
if (__FILE__ != realpath($_SERVER['PHP_SELF'])) {
return;
}

Another person on the forums had this problem and found that if you comment out that line the script will work. So I just did this:

// Don’t run the example if the file is being included.
//if (__FILE__ != realpath($_SERVER['PHP_SELF'])) {
// return;
//}

Suddenly my stuff magically appeared in a browser when I loaded it like this:

http://localhost/adwords/reports/searchquerysagerock.php

If you notice, I have taken to moving my scripts to a folder like this:

http://localhost/adwords/reports/

You will find that the reports won’t run at the level. The init.php file needs to be updated. When you are working in the example files, you will find it in a place like this:
C:\Users\Sage\Downloads\adwords-examples-and-lib-5.5.1\adwords-examples-and-lib-5.5.1\examples\AdWords\v201406\init.php

You’ll want to look at these line:

$depth = ‘/../../../';
define(‘SRC_PATH’, dirname(__FILE__) . $depth . ‘lib/’);
define(‘LIB_PATH’, ‘Google/Api/Ads/AdWords/Lib’);
define(‘UTIL_PATH’, ‘Google/Api/Ads/Common/Util’);
define(‘ADWORDS_UTIL_PATH’, ‘Google/Api/Ads/AdWords/Util’);

The thing I need to change was: $depth = ‘/../../../';

I just moved init.php to this folder: C:\xampp\htdocs\adwords\init.php

and updated the line to this:

$depth = ‘/';

That structure should work fine for me going forward.

I think that’s enough for this post. I have a few other little things I’ve discovered on my journey. But they may not be useful to everyone.

This process that I’ve laid out here is pretty much mandatory to go from nothing to getting a working setup of AdWords API.

Best of luck and have fun!

Sage

P.S.

If you are working with reports, which is my interest, you will find a cool list of available reports, date ranges you can sort and that kind of thing here:

https://adwords.google.com/api/adwords/reportdownload/v201406/reportDefinition.xsd

These are the date ranges you can run:

TODAY”
“YESTERDAY”
“LAST_7_DAYS”
“LAST_WEEK”
“LAST_BUSINESS_WEEK”
“THIS_MONTH”
“LAST_MONTH”
“ALL_TIME”
“CUSTOM_DATE”
“LAST_14_DAYS”
“LAST_30_DAYS”
“THIS_WEEK_SUN_TODAY”
“THIS_WEEK_MON_TODAY” 
(That list is always hard to find, for some reason.)
S.

The TOOLS Show: We Talk Facebook

Recently, Wordstream put up an article on their blog called “13 Ways to Beat the Facebook Algorithm,” full of interesting graphs (ok, it’s really just one) and semi-interesting tips about what the latest Facebook algorithm is doing to your newsfeed. {side note: I never thought I would ever be writing the algorithm–and spelling it right–as much as I am this week!}

Organic Reach on Facebook

As seen in the graph below, the average organic reach (as in, not paid for) of content published by branded pages on Facebook is now about half of what it was in October 2013. For brands with less that 500k Likes, in October 2013, about 12% of the people who Liked your page would see your posts. By February 2014, that number is down to 6%. This means you’re lucky if 6% of the people that have clicked “Like” on your Facebook page, and want to see your content, are seeing it on their newsfeeds.

 

Organic reach for brands on Facebook is half of what it once was.

The evolution of organic reach for brands on Facebook

 

To increase that reach, this particular blog post recommends  things like “Share Great Content,” “Use Facebook Ads,” use other social media outlets, and listen to your fans. While these are all good, common sense suggestions, they were even before any of the recent changes. And we’re not sure that paying for exposure on Facebook is “beating” the algorithm; it sounds more like joining it.

So what is a brand to do about a problem like Facebook? As noted in the graph, the bigger brands in particular are getting very little in the way of organic exposure, which might lead them (and you) to believe that maybe it’s time to jump the Facebook ship.

BUT… Greg brings up the very salient point that if you abandon the Facebook, thinking that nobody is seeing your content anyway, how will that look to a new contact who visits your page directly, probably from a link on your website or other social media outlet? A page with no posts for the last year does not inspire confidence to a potential customer.

Personal Engagement

This leads to the question of “What about personal pages?” — Are the stats any better? While we don’t have the numbers to show you, Sage and Greg did take a gander at Sage’s personal Facebook feed, to check out what was going on.

The theory (at least according to FB) is that you want to see stuff and people who are already engaging with, so they try to show you essentially more of the same {the philosophical problems with that line of thinking will have to wait for another day}. In Sage’s feed, for example, are mostly people (not brands!) who he reads, talks to, or comments on. Posts from his wife and people he’s recently been researching and working with seem pretty obvious. Another personal post, complete with video, is from a friend and colleague about her business, but she is using her personal page to do it. Maybe she has hit on something here!

Personal sharing usually shows up much better than branded/page sharing/content, which is one way to go if you’re trying to get onto more newsfeeds–and probably even will get you in front of more (relevant) eyeballs.

The only branded posts that show up in Sage’s feed are Sponsored posts; not even the pages he admins are showing up! Two more clues.

What is a Brand to Do?

Instead of using someone else’s real estate to build your house, it’s always better to build on your own property. In other words, use social media to drive people to YOUR website, offer them something cool, and collect their email addresses. Then you can engage with them directly, in their inbox. Then you’re having a more personal conversation, which is more effective anyway.

Unless you’re going to devote some money to marketing on Facebook, it may not be worth the effort, unless you’ve got a community base that has a reason to be highly engaged. For example, if your child’s school is regularly updating about what’s going on at the school, and people are checking it out, looking for the pictures of their kids, talking and sharing, then those posts are highly likely to be making it into your feed. This is a captive audience, and the school is getting a 30% organic reach because they have compelling, relevant content.

Moral: Without money or a passionate audience, it’s more difficult to engage with fans on Facebook.

Why are We Sticking Around?

In case you think the news is all bleak, Sage gives us the good news about Facebook. He has been experimenting with Website Conversions on Facebook, Twitter, and Adwords; and has found the most success with FB. Basically, he is getting more conversions (people doing something on the Sagerock website) from Facebook than any other outlet.

How do you do that? In Facebook’s “Advertise with Us,” you can choose Website Conversion as your Objective. You pick the page you want to send people to, and what you want them to do there (sign up, watch a video, whatever). Then you can get a “Facebook Conversion Pixel” which is a bit of code that you add into the header code of just the page you are looking at. This can be a little complicated if you’re using a CMS, but there is a  Wordpress plugin you can use if you have a WP site.

When you do things like this, Facebook then becomes really interesting, according to Sage. Then you have information to measure, and you can start breaking down your audience and playing around with who to show your stuff to, based on all kinds of demographics (for more info about FB Audiences stuff, check out this post/show). And so far, the only conversions are coming from Facebook, which shows us that there is some value there still. Yes, you may have to spend a little money to make it work, but it’s probably worth a few bucks to get some hot new leads in the pipeline, ready for what you have to offer!

Key Takeaways

  •  Don’t ask people to buy on Facebook; it doesn’t work
  • Just focus on driving people to YOUR website and getting them on your mailing list
  • Then you can develop a relationship with them; truly engage and find out what their pain points are
  • With a minimum of time and money investment, you can target a huge audience of relevant people

Need more help with Facebook? Be sure to check out our new Facebook Marketing tips series!

The Tools Show: SEO Ranking Factors for 2014 – September 11, 2014

(If you’d rather just listen, check out the podcast here)

Searchmetrics released their annual report about the top Google ranking factors for 2014 recently. And while there is coverage about the report (like this article from Search Engine Land),  Sage decided to go straight to the source. He covers the highlights of the report, explaining and commenting along the way. Ready? I’ll try to do it justice.

The report itself is almost 100 pages of pretty in-depth information about what they found to be the key factors that affected Google search results rankings. It’s a nicely-designed piece, with easy-to-read graphs and charts and good explanations (maybe too good in some cases; Sage gets a little impatient). Definitely worth looking at the full report if you’re into that kind of stuff. (Unlike the latest Transformers movie, according to Sage; apparently the preview is better than the actual movie.)

The first thing that needs to be said about this report/study is that Correlation Does Not Equal Causation. If you don’t remember this logical fallacy from school, basically it means that the people doing the study aren’t Google, so they can’t say for sure that the things they observed as being factors are truly the cause of their high ranking. These factors just happen to be seemingly related to the high rankings of the sites they evaluated.  But most of them make sense relative to other data and information that Google itself has released.

So Searchmetrics analyzed 10,000 “informational search terms” and websites and graphed the Correlations of the top 30 and the averages of the top 10 sites. Here are our top takeaways from the report:

1. The big focus–no real surprise–is that Content  Really is King:

“High quality, relevant content is increasingly the focus of search. This type of content ranks better on average, and is identifiable by properties such as a higher word-count and semantically comprehensive wording, as well as often being enriched by other media, such as images or video.”

What does that mean? It means that you needs to have lots of good quality content to rank well, and that Google is getting better at “semantic search,” which is giving results that aren’t based just on the actual key words, but also the relevant topic someone is searching for. So instead of loading up on keywords, to try and game the system, just have well-written, long-form information about the relevant topic on your pages. (Or, as Greg puts it, “write a Bible on every page.” LOL) This is the behavior that Google is rewarding.

In the detailed section on content, they report that content over 975 words seems to increase ranking, and that sites with over 130 internal links (obviously for larger sites) rank above average.

One negatively-correlated item was the inclusion of on-page ads, especially “above the fold.” These were rare on highly-ranked sites, which is no surprise considering that Google has been pretty open about their lack of love for sites with lots of ads. So you’ll have to decide if that ad revenue is worth Google’s price.

2.  The role of Technology is important but is evolving.

“It seems that the presence of certain onpage technical factors is a basic requirement for a ranking
on the first pages of SERPs.”

Integrated website architecture, more than just plain “SEO” factors, seems to be the goal toward which Google is striving. This should be no big surprise, based on what we’ve already covered, that efforts to use keyword “strategies” are being eclipsed by holistic building of websites around content and helping readers find that content, using onpage tech like meta descriptions, H tags, and internal links.

This boils down to making sure that when you have great content, you are making it easy for people to scan and read–the observed increase in H2 tags I’m taking to heart as a writer to mean that people find subtitles within those long content pieces to be important (which I could already tell you).

And that you have to give folks a reason to click on your link! With so many websites anymore, choosing a “good one” from a Google SERP {Search Engine Results Page} can be time-consuming and frustrating, we all know. But the inclusion of good meta tags and descriptions helps point a searcher to your high-quality content, and the inclusion of your relevant keywords here are going to make more of an impact than a loaded URL.

Other tech-related factors include a fast load time, which the report clocks at 0.99 seconds, but Greg points out is really a relative term, based on your competitors. Yes, we get impatient for large brands especially, but inside a niche, as long as you’re faster than the next handmade, organic cheese bread maker, you should be fine.

3. Social is a bonus: use it wisely but don’t focus exclusively on it.

“Social signals definitely play a role in direct traffic, brand awareness, and the overall online performance of a domain.”

The bottom line for social is that it seems to be used mainly as a signal that new content is regularly being added to a site, and that people are talking about the brand and sharing content. So here we are, back at the importance of content.

No shock that Facebook is the leader in this arena, followed by Google, Twitter, and Pinterest. So keep sharing all those goodies with your followers!

Social media’s true value is in helping develop your brand. By filling out and developing your brand experience, you will increase your value with customers and potential customers, which has a positive effect on your key ranking factors. This is a tidy little positive feedback loop, helping you gain traction in social and search.

The Bottom Line: “Do Good Things”

Become a source of useful and relevant information to your target audience and you will be rewarded.

Content creation can’t “serve two masters” — You won’t win by focusing content on SEO without making it high-quality and relevant.

Greg likens good content creation to a job: if you’re just getting paid by the hour, even if you’re good at your work, it will be ok, but it can’t compare to what you will produce if the subject is something you’re passionate about.

“Content for content’s sake is done.”

My take: People want to hear from and about people. Being a person online is always better than being a “company” (bland, personality-less, boring “content”).

What did you take away from all this? Let us know in the comments!

How Search Affects Your Business Today