Section 14.2. Creating the Campaign Web Service Client

14.2. Creating the Campaign Web Service Client

In order to use one of the Google AdWords API web services, you need to:

Use the WSDL file for the service to create a new SOAP client object
Set the authentication headers for the SOAP service

The authentication headers require the same information for all of the AdWords API web services, so once you've generated this information, you can use it in repeated calls to the AdWords API web services.

The information required for the authentication headers is shown in Table 14-1.

Table 14-1. Authentication headers required for making a request
XML wrapper	Value required
`<email>`...`</email>`	Email address associated with AdWords account.
`<password>`...`</password>`	Password associated with AdWords account.
`<useragent>`...`</useragent>`	This is an arbitrary string you can use as you like. It bears no relationship to the UserAgent you may have seen associated with web browsers.
`<token>`...`</token>`	AdWords API developer key.

You must pass the actual values for each field required for authentication wrapped in the XML shown in Table 14-1. The values themselves go between the XML tags, for example, <email>me@me.com</email>.

In a real program in the real world you probably won't let users enter the header authentication information; it will be programmatically generated. But in this situation, I've set things up so that the user enters authentication information, as well as the information to create a campaign, as shown in Figure 14-1.

Example 14-1 shows authenticate.php, which contains the HTML for the form depicted in Figure 14-1; the form allows a user to input authentication and campaign information.

Figure 14-1. The authentication informationthe first four items requestedare used for all the different services

Example 14-1. HTML form for entry of authentication and campaign information (authenticate.php)

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <title>Roll Your Own AdWords Campaign</title> </head> <body> <h1>Enter Authentication and Campaign Information</h1> <form action="campaign.php" method="POST"> <table cellspacing=15> <tr><td> Enter your AdWords email: </td><td> <input type="text" name="email" value="you@email.com"> </td></tr><tr><td> Enter your AdWords password: </td><td> <input type="password" name="password"> </td></tr><tr><td> Enter User Agent (anything you like): </td><td> <input type="text" name="useragent" value="API Demo"> </td></tr><tr><td> Enter your developer token </td><td> <input type="text" name="token"> </td></tr><tr><td> Enter a name for your AdWords campaign: </td><td> <input type="text" name="name"> </td></tr><tr><td> Enter a daily budget for your campaign (micro-currency units): </td><td> <input type="text" name="dailyBudget"> </td></tr> <tr><td> Country for targeting: </td><td> <input type="text" name="countries" value="US"> </td></tr> <tr><td> Language to target </td><td> <input type="text" name="languages" value="en"> </td></tr><tr><td></td><td> <input type="submit" name"Continue" value="Continue"> </td></tr> </table> </form> </body> </html>

The HTML form shown in Example 14-1 uses the form POST rather than GET so that the AdWords email address, password, and developer key don't appear as part of the browser address field when the next page (campaign.php) is opened.

14.2.1. The General Pattern

Within the AdWords API web services, there's a fairly generic set of steps to follow. This pattern works the same way at all levels of the hierarchy of AdWords objects. You need a client object based on a particular AdWords API web service.

Each time you invoke a new client object, you need to authenticate it. You need to wrap your parameters in XML, and you need to use the identification of the containing object (unless you are at the top of the object hierarchy, as with a campaign).

Here are the steps:

Create a client object.
Authenticate.
Obtain parameters, including the identification for the containing object.
Wrap the parameters in XML.
Use the client object to add the wrapped parameters and create a specified entity within AdWords.

14.2.2. Creating the Authentication Headers

You need authentication information (email, password, user agent, and developer token) to create the authentication headers.

The email, password, user agent, and token are passed to campaign.php using HTTP POST, so these can be read in PHP easily:

     $email = $_POST['email'];     $password = $_POST['password'];     $useragent = $_POST['useragent'];     $token = $_POST['token'];

Next, these values need to be wrapped in the appropriate XML element tags. To simplify this a bit, here's a utility function that accepts plain text representing the contents of an element and creates an element with that content (using the supplied element name):

     function makeDocLit($xml, $var) {         return '<' . $xml . '>' . $var . '</' . $xml . '>';     }

The function is in the library file and needs to be included in each PHP module that uses it, like this:

     require_once('hd_lib.inc');

This code then wraps the authentication headers in the appropriate XML:

     $email = makeDocLit ("email", $email);     $password = makeDocLit ("password", $password);     $useragent = makeDocLit ("useragent", $useragent);     $token = makeDocLit ("token", $token);

The header consists of the four XML-wrapped values concatenated:

     $header = $email . $password . $useragent . $token;

The PHP string concatenation operator is represented by a period (.).

This header will be used to authenticate each of the AdWords API web services used. To make it available in other PHP modules in the application besides the current one, it's easy to use PHP's session-tracking facility. To implement session tracking, put a directive in the file before any HTML has been generated:

     <?php session_start(  ) ?>

With that directive in place at the beginning of the file, it's easy to save a variable so it can be used across a multipage application:

     session_register('header');

PHP normally uses cookies to track sessions. If PHP finds it can't use cookies on a specific computerperhaps because the user has turned them off in their browserPHP adds session identification strings to the URLs that it generates.

14.2.3. Connecting to the WSDL File and Creating a Client Object

Creating a client object for one of the Google AdWords API web services gives you programmatic access to the members of that web service, meaning its properties and methods. So the next step is to use the URL for the WSDL file to create a client object based on the web service:

     $campaignwsdl = "https://adwords.google.com/api/adwords/v2/CampaignService?wsdl";     $campaignclient = new soapclient($campaignwsdl, 'wsdl');

14.2.4. Setting the Authentication Headers for the Clients

Once the web service has been instantiated in your code, Google needs to know that your program has a legitimate right to use the web service to create (and set) AdWords objects. To accomplish this, set the authentication header that was created in code:

     $campaignclient->setHeaders($header);

-> is PHP's object membership operator, so this line of code calls the setHeaders( ) method of the web service client object. Other SOAP toolkits provide different mechanisms for setting the authentication headers.

Here's what the script looks like so far (leaving the HTML out of it):

     ...     <?php     require_once('NuSOAP/nusoap.php');     require_once('hd_lib.inc');     ...     $email = $_POST['email'];     $password = $_POST['password'];     $useragent = $_POST['useragent'];     $token = $_POST['token'];     ...           // Set up the authentication headers     $email = makeDocLit ("email", $email);     $password = makeDocLit ("password", $password);     $useragent = makeDocLit ("useragent", $useragent);     $token = makeDocLit ("token", $token);     $header = $email . $password . $useragent . $token;     session_register('header');           // Connect to the WSDL file for the CampaignService     $campaignwsdl = "https://adwords.google.com/api/adwords/v2/CampaignService?wsdl";     $campaignclient = new soapclient($campaignwsdl, 'wsdl');           // Set the headers for the client     $campaignclient->setHeaders($header);