Getting Started with the AdSense Management API

Uploaded by GoogleDevelopers on 12.12.2012


We hope you haven't really been waiting too long, but
we've been having a couple of technical
issues here at the studio.
I think that this time everything is ready to go, so
welcome to our little presentation on the AdSense
Management API.
I'm Sergio.
I work in the London office on the AdSense APIs.
And I'm Jose, a colleague of Sergio's.
And we're going to talk about the agenda first.
There you go.
All right.
So first, Sergio is going to define some concepts,
important concepts to understand
the rest of the session.
Then he will be talking about OAuth2 and the wonders of
authentication and--
SERGIO GOMES: Always an exciting topic.
--and authorization.
Then I'll be talking about channels.
I'll expand the reporting section that we did last
event, and I'll talk about the new v1.2 features.
Then if we have questions on the Moderator page that you
can find on the--

SERGIO GOMES: On the event at the Google
Developer site, yes.
JOSE ALCERRECA: Then we'll talk about them.
Yeah, so if you have any questions during the
presentation, just don't hesitate to go to the Event
page, leave your question there, and then at the end of
the session, we'll be taking a look at it.
All right.
So as you mentioned, Jose, I have a couple of definitions
that I'd like to get started with.
And if you're an AdSense user, you probably know most of
these concepts already.
But with the AdSense Management API, you can
develop applications not only for yourself but for other
people as well.
So the typical example would be someone who develops an
Android or an iPhone application to
access AdSense data.
And they can use that application themselves for
their own AdSense account, but they can also develop this and
just make it available in the app stores and have people buy
the application or give it away for free and sign up into
their AdSense accounts and just be able to take a look at
the information there.
We're also going to be discussing how all of this
happens securely.
So, oh, actually keeping on this slide--
so in terms of basic concepts, there are four main concepts
that I want to introduce here.
The first one is Ad Units.
Ad units are essentially predefined slots where your
ads will appear.
You log into the AdSense website, and you can configure
everything there from colors, sizes, all sorts of options
that define exactly how you want the look and feel of the
ads to be on your website.
Then there's Ad Clients, which are a bit of a tricky concept
to explain, but they're essentially a relationship
between an AdSense product and your account.
So as an AdSense user, you might actually have access to
several products.
For example, AdSense for content and AdSense for
search, and for each of these products, you'll actually have
something called an Ad Client in your AdSense account.
Then there's Channels, which Jose will get into a lot more
detail during our presentation later on.
But they're essentially ways of organizing the information
so that it later shows up correctly in your reports, and
you can track things according to different ways of
organizing your data.
And finally, the Reports, which are
where you can generate--
rather, where you can get the data for your impressions, for
your account's performance, your earnings, all of that
stuff, which are extremely detailed and very configurable
as well in the Management API.
So what does the Management API run on?
As all of our newer APIs, it's what we call a
It uses REST as the, I guess, methodology.
The mechanics of the API are REST.
You make RESTful requests, which in the case of the
AdSense Management API, are read-only requests, so you use
GET mostly.

Actually, in the case of the AdSense Management API,
there's one custom verb, which is Generate, which is used for
reports, but most of them are standard HTTP
verbs that are used.
And the format in which the data is transmitted to the API
and from the API is JSON, which is an industry standard
format as well.
And it has the advantage of actually working with
programming language primitives, associative
arrays, and arrays in general, text strings, all sorts of
native data that you can directly load into your
It's not a hard thing to parse like XML is.
It's a lot easier to use.
And finally, the authentication and
authorization mechanism that we use across all of our APIs,
OAuth2, which I'm going to be talking in to a little bit
more detail later on.
So in terms of Ad Units, I've got a little slide here to
show you how they look.
Again, this is completely configurable.
You can change the colors, you can change the sizes, and this
will be filled in automatically with ads
relevant to the content on your page.

In terms of how you should be developing, we recommend that
you use the client libraries.
We've gone to considerable amount of effort in developing
them for multiple programming languages to make your whole
life a little bit easier.
It's a little bit like when you're connecting your
speakers, you don't want to use the raw cable.
You want to put a banana plug on the end of it to make your
life a little bit easier.
SERGIO GOMES: And in terms of support, we have got things
like Go, PHP, Java, Ruby, JavaScript, all sorts of
different programming languages.
But again, always remember, this is a RESTful JSON API.
You don't have to use the client libraries, but if you
do, they will make your life a whole lot easier with things
like OAuth and being able to just code things as is
expected in the specific programming language that
you're using rather than just having to compose your own raw
HTML requests and all that.
JOSE ALCERRECA: Yeah, especially for OAuth.
Yes, especially for OAuth.
All right.
So how does this OAuth thing work?
Now if you're a Google Developer, you've probably
used OAuth before.
I mean, it's what we use across all
of our APIs, I think.
There's still a couple of legacy APIs that use other
authentication mechanisms, but it's the one we're pushing
forward now.
It's an industry standard, and it's got a couple of
interesting features which allow for developers and users
to be different people and still keep everything secure.
So as sort of a high level overview, it starts by the
developer making a request against the API.
The user gets a prompt, which you can see here on the bottom
part of the screen.
And this prompt not only tells them what application is
trying to access their data, it also tells them exactly
what data they're trying to access.
And once the user approves it, the developer gets granted
access to the data, and this access comes
in the form of tokens.
There are two types of tokens.
There's the access token, which is the important one
that is actually used in the request, but it's a
short-lived token for security reasons.
It only lasts, if I'm not mistaken, 3,600 seconds or
something along those lines.
And then there's the refresh token, which is actually a
long-lived token.
It does not expire unless the user specifically revokes
access to your application, and you can use this at any
time to generate new access tokens as needed.
So I'm just going to give you a little overview of how to
get started on a project.
I'm not going to go into too much detail on how to perform
the whole OAuth set up, because that would take a life
event of its own, but I'm just going to give you a little
introduction here on how to get started.
So first you want to go to your APIs console.
If you're a Google Developer, you've probably
already used it.
If you're a new developer, this is the place where you
can set up-- give us your details, your credentials, so
that we can set up OAuth securely.
You'll see a page like this asking you to create your
first project, and when you do, you'll want to go into the
Services tab and make sure you enable the AdSense Management
API, which is what you'll be using with as well as any
other APIs that you'll be using on the same project.
After that, you'll need to go into the Access tab and create
a new OAuth2 client ID, and there's a bunch of different
options that you can set up here.
But the important thing--
again, we're not going to go into too much detail on those,
because that would take a whole lot of time that we
don't really have.
But the important thing to note is that at the end,
you'll get something like this, which gives you your
client ID and your client secret, which is what you'll
need to input into your client libraries configuration files,
or if you're not using a client library, into your own
OAuth methods to get the tokens back from us.
So over to you and custom channels and URL channels.
So channels are the tools that let you track data in order to
organize your reports.
So the first type is custom channels.
You can define custom channels on the AdSense web interface,
and you can use it to track different sizes, ad units,
colors, sections of your page, and you can then filter the
reports to get the data you may need.
But if you're actually tracking sections of your
site, you might want to use your [? old ?] channels.
These are also configured at the AdSense web interface
level, so all it takes is a domain or sub-domain, I think,
and a path.
So everything that comes below that path is tracked by this
URL channel, but you have to configure them beforehand.
That's it.

This can be as complex as you want, but let's start by using
some examples, some very simple examples.
The first one you can see there.
It's just a simple report that, given a date range and
month estimation and earnings as metric, it just gives us a
table of months and earnings.
The second example has two metrics, so we are combining
earnings and page views, but as you can see on the
[? row's ?] property, it's just a new column.
The problem comes when you combine dimensions.
As you can see here, we're combining country code with
month, so for each country on the database or I guess for
each country that accessed the--
SERGIO GOMES: For each country for which you have some
impressions, yes.
--you get a month.
So it's basically the number of months times
the number of countries.
So this can generate a really big report, so you might want
to limit your number of dimensions to two or three
depending on the dimension used.
SERGIO GOMES: There's usually not much of a use case for any
more than that.
JOSE ALCERRECA: So you can think of the dimensions as the
data represented on the x-axis.
You can see there the current list of dimensions.
We have some for dates, some for ad units, channels--
this is an important one--
and some other advanced dimensions that you
may or may not need.

Same thing with metrics.
It's like the y-axis of the function that we are
representing, and some important metrics are clicks,
earnings or page views.
So you can combine as you wish the metrics and dimensions,
but you can also solve them by--
SERGIO GOMES: Well, not entirely as you wish.
We do have a few limitations but--
JOSE ALCERRECA: Yeah, there are some
incompatibilities, but--
SERGIO GOMES: You'll get a warning if that's the case.
So, yeah, I was saying you can sort them by dimensional
metric, and also you can filter them.
This is very powerful actually.
You can filter by country, by channel, by size,
whatever you want.
And also you can combine filters, so you can
use and's and or's.
SERGIO GOMES: Yes, we have--
sorry-- we have a whole documentation page on that,
but essentially you can put a filter on
anything that is a dimension.

JOSE ALCERRECA: So, if you want to try the reporting
engine that we have, go to the API explorer.
Don't try to code everything directly.
This is a very handy tool that we use all the time, actually.
You can use it to define the dates, the metrics,
dimensions, sorts, basically all the
fields that you'll need.
So the new v1.2 features.
There are a couple of new features.
The first one is ad styles.
It's just a [INAUDIBLE], a list--
well, a Get [? and ?] list resource.
So it's just to list on and get your ad styles, and your
colors, your fonts, your [? corners ?], all that you
have saved previously on the AdSense web interface.
And also the same thing with saved reports.
Instead of configuring at code level your reports, you can
create them on the AdSense web interface, save them there,
and you will generate them using an ID.
I see there's some kind of a problem.
It's OK.
JOSE ALCERRECA: So here, you have the saved reports manager
on the AdSense web interface.
So if you first list the saved reports, you get the ID from
there, and you only have to use this ID to
generate the reports.
And you get exactly the same report as in the common
generate method for reports.
SERGIO GOMES: This is useful if users already have their
reports set up and they don't have to reconfigure everything
but just access the reports they already have.
You as an application developer can develop an
application that lists all of their existing saved reports,
so they can just hit the button and get the same data
through your application that they
would via the web interface.
JOSE ALCERRECA: So that's it.
SERGIO GOMES: So, shall we take a look at our list of
questions then?
Let's see.

We don't have questions.
We have an entry and--
JOSE ALCERRECA: --it seems like spam.
SERGIO GOMES: Well, that's what you get when you have
open forums on the internet.
All right.
JOSE ALCERRECA: So I think that's all.
Well, yeah, don't forget to check out our blog, which is
googleadsdevelop, our G+ page,
and also the main support tool that we use is the forum.
So if you have any questions, if you have any technical
questions on how to use the API, if you have any issues
with OAuth, if you have any questions at all, just come to
us on the forum, and we'll be taking a look at your question
and answering it and hopefully getting you started developing
your application as quickly as possible.
JOSE ALCERRECA: Thank you very much.
SERGIO GOMES: All right.