This document covers the steps required to create or associate AdSense publisher accounts with a host in the AdSense Host API v4.x. Account association is required for revenue sharing, reporting and all other functionality in the AdSense Host API, and as such every host must implement this flow.
Overview
Account creation and association is handled by the AdSense website, but it is the host's responsibility to redirect the users there, as well as to store an identifier once the process completes.
Signup takes place in 4 steps:
- The host requests a new association session, by calling associationsessions.start.
- The host redirects the user to the URL provided in the returned association session, where the user completes the steps in the AdSense website.
- The user is redirected back to the host's website, together with a token.
- The host verifies the token, by calling associationsessions.verify. If the association was successful, the response includes the publisher's account ID, which the host should store locally for use in any API calls involving this publisher.
Step 1: Starting an association session
To redirect a publisher to the signup page, you (the host) must first request a new association session. This is done by calling associationsessions.start. Here's what the response looks like:
{ 'id': '00000000-0000-0000-0000-000000000000', 'redirectUrl': '<redirect URL>', 'websiteUrl': 'www.example.com', 'productCodes': ['AFC'], 'kind': 'adsensehost#associationSession' }
The fields to note in this response are redirectUrl
and id
, the unique identifier for the session. You'll need to store the id
locally, so that you can later identify the specific user during callback.
redirectUrl
is where you'll need to redirect your user in the next step.
Step 2: Redirecting to the AdSense website
Account creation, or association for existing accounts, takes place in the AdSense website, in a dedicated API signup page.
For this step, all you need to do is redirect the user to the redirectUrl
you received in the previous step, and Google will take care of the rest!
Step 3: Getting the callback
After the user has filled in all the information and completed the signup process on the AdSense website, they will be sent back to the predefined callback URL tied to your host account.
For security reasons, the association details aren't sent directly in the callback. Instead, the callback request will include a single HTTP parameter named token
. This parameter will always be set, whether or not the association was a success.
GET http://your.callback.url/path?token=<associationtoken>
Make sure you register and log all callbacks to avoid sending your users through the signup flow multiple times.
Step 4: Verifying the token
To get the association session details, including whether or not the association was successful, you'll need to call associationsessions.verify with the token you received in the previous step.
If there was an error or the user chose to reject the association, you'll get a response similar to the following:
{ 'id': '00000000-0000-0000-0000-000000000000', 'status': 'REJECTED', 'kind': 'adsensehost#associationSession' }
id
allows you to identify the user this association session belongs to, by comparing to the association ID you stored earlier in step 1.
status
indicates whether the session was a success. It will list ACCEPTED
if that's the case, REJECTED
if the user chose to reject the association, or ERROR
if there was some form of error during the sign-up process on the AdSense website.
If the association was accepted you'll also get an additional field:
{ 'id': '00000000-0000-0000-0000-000000000000', 'status': 'ACCEPTED', 'accountId': 'pub-0000000000000000', 'kind': 'adsensehost#associationSession' }
The accountId
field contains the user's AdSense account ID, which you will need to store locally so that you can make any API calls relating to this user.
All done!
Once you've stored the account ID, you have all the information you need to manage the user. You can now use it to make API calls specific to them, such as checking their AdSense account status with accounts.get or managing their ad units with the accounts.adunits collection.