AdSense API from Scratch Part 2 - Creating and Associating Accounts

This is the second post in the “AdSense API from Scratch” series, where we take a look at how to develop a full AdSense API implementation, using best practices, in PHP 5.

In Part 1, we looked at how to get started with development, and made our first createAccount call. This time we’ll look at how we can improve on the code we wrote, as well as how to handle account associations.


Error Handling in createAccount

The error handling we have is pretty unfriendly so far:

try {
  // API request code omitted for clarity.
} catch (SoapFault $e) {
  print_r($e);
  exit(1);
}

This may work for development and debugging, but we can’t expect a user to be presented with a PHP object dump. We not only need to tell the user that an error happened, but also why, in understandable language.

The AdSense API works with error codes, which represent the different kinds of errors. First, let’s make sure that what we’re getting back is an AdSenseApiException and not another type of error (such as a network error):

try {
  // API request code omitted for clarity.
} catch (SoapFault $e) {
  if (isset($e->detail) && isset($e->detail->AdSenseApiExceptionFault) &&
      isset($e->detail->AdSenseApiExceptionFault->AdSenseApiException)) {
    // Handle AdSense API exception.
  }
}

Now that we know this is an AdSense API exception, we can look at its fields to analyse the error. The code field is the one we’re interested in to distinguish between the different types of error:

try {
  // API request code omitted for clarity.
} catch (SoapFault $e) {
  if (isset($e->detail) && isset($e->detail->AdSenseApiExceptionFault) &&
      isset($e->detail->AdSenseApiExceptionFault->AdSenseApiException)) {
    $inner = $e->detail->AdSenseApiExceptionFault->AdSenseApiException;
    switch ($inner->code) {
      case 303:
        print "This login email is already being used by another user.\n";
        break;
      case 321:
        print "The login email you provided was not valid.\n";
        break;
    }
  }
}

In this example, we’re showing only two types of errors; however, the createAccount method does return more, though, so be sure to include all cases pertinent to your implementation.

And how about other, unexpected API exceptions? Thankfully, you don’t need to handle all of them individually, as the AdSense API is kind enough to provide a user-readable error message on what the problem is. Look no further than the message field, as illustrated in the default clause below:

try {
  // API request code omitted for clarity.
} catch (SoapFault $e) {
  if (isset($e->detail) && isset($e->detail->AdSenseApiExceptionFault) &&
      isset($e->detail->AdSenseApiExceptionFault->AdSenseApiException)) {
    $inner = $e->detail->AdSenseApiExceptionFault->AdSenseApiException;
    switch ($inner->code) {
      case 303:
        print "This login email is already being used by another user.\n";
        break;
      case 321:
        print "The login email you provided was not valid.\n";
        break;
      default:
        print "An error occurred while creating AdSense account:\n ";
        print $inner->message;
        print "\n";
    }
  }
}

This message even comes in the language of your choice, according to what you configured in the display_locale header.

You can find the full sample for the createAccount method here.


Account Association

Association is very similar to creation, with the difference that instead of creating a new AdSense account, you’re simply linking to an existing AdSense account belonging to your user. The request takes different parameters, namely the phone number and postal code hints:

try {
  $result = $accountService->associateAccount(array(
      'loginEmail' => 'INSERT_LOGIN_EMAIL_HERE',
      'postalCode' => 'INSERT_POSTAL_CODE_HINT_HERE',
      'phone' => 'INSERT_PHONE_HINT_HERE',
      'developerUrl' => 'code.google.com'));
} catch (SoapFault $e) {
  // Error handling goes here.
}

Don’t forget to take a look at the errors that associateAccount can return, as they are different than the ones for createAccount. The full sample for this method, including error handling, is available here.


Next steps

Next week, we’ll be taking a look at ad code generation to complete our basic implementation.

Again, if you have any questions or comments, be sure to let us know in the forum!


 - Sérgio Gomes, AdSense API Team