Section 14.3. Creating a Campaign

14.3. Creating a Campaign

The HTML form that lets a user provide authentication information also lets the user provide campaign information. You can pick these values up easily in PHP:

     $name = $_POST['name'];     $dailyBudget = $_POST['dailyBudget'];     $languages = $_POST['languages'];     $countries = $_POST['countries'];

The only one of these values that is required is dailyBudget, which is specified in microunits of currency . Table 14-2 shows the default values used for optional campaign information.

Table 14-2. If you don't provide campaign information, here are the values Google will supply
Information	Default value
name	A name of the form Campaign #`N`, where `N` is an ordinal number
languages	All languages
countries	All locations

Microunits of Currency

Within the AdWords API, the daily budget for a campaign and the maximum CPC for an ad group (the most you are willing to pay when someone clicks on your ad) are specified in microunits, or micros, of currency. A micro is defined as one-millionth of the fundamental currency unit.

The specific currency used depends on the currency selection for the AdWords account involved. If the AdWords account uses U.S. dollars, then $1.00 is 1,000,000 micros. The least amount you can specify for the maximum CPC is $.05; expressed as micros this is 50,000 micros.

The maximum CPC you enter must be expressed in legitimate, billable units; in U.S. dollars, all CPC bids must be in round pennies. This means that the value for the maximum CPC must be a multiple of 10,000 micros (which equals 1 cent).

14.3.1. Campaign Settings

Once you've instantiated an object based on the CampaignService web service, using the code I showed you earlier:

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

and have sent it authentication information as I showed you:

     $campaignclient->setHeaders($header);

you can go about the business of configuring a new campaign.

Configuring the campaign involves these steps:

Create a new, empty campaign.
Construct XML-wrapped entries for the campaign parameters you want to set (dailyBudget is required).
Put the parameters together in one string.
Wrap the parameter string in XML.

First, create an empty campaign element:

     $campaign = "<campaign></campaign>";

Construct the campaign name and dailyBudget values:

     $campaignName = makeDocLit ("name", $name);     $dailyBudget = makeDocLit ("dailyBudget", $dailyBudget);

Construct the targeted language(s):

     $languages = "<languageTargeting>" . makeDocLit ("languages", $languages)        . "</languageTargeting>";

The languages are specified within <languageTargeting> tags, which contain one or more language codes wrapped within <languages> tags. You can find the language codes you can use at this address: http://www.google.com/apis/adwords/developer/adwords_api_languages.html.

Construct the geotargeting:

     $geotargets = "<geoTargeting>" . makeDocLit ("countries", $countries)        . "</geoTargeting>";

The countries, regions, and cities for geotargeting are specified within <geoTargeting> tags, which contain one or more country codes wrapped within <countries> tags. GeoTargeting tags can also contain metros, cities, and regions in addition to countries. You can find the country codes you can use at this address: http://www.google.com/apis/adwords/developer/adwords_api_countries.html.

Put together the campaign parameters:

     $campaignparams = "<campaign> $campaignName $dailyBudget $languages        $geotargets</campaign>";

Add an XML wrapper:

     $campaignparamsxml = "<addCampaign> $campaignparams </addCampaign>";

Web service operations take place within a namespace. The AdWords API web services all use the same namespace, https://adwords.google.com/api/adwords/v2. You don't have to specify this namespace, because it is the default, but you could if you wanted to:

     $campaignparamsxml = "<addCampaign        xmlns='https://adwords.google.com/api/adwords/v2'>        $campaignparams </addCampaign>";

Here's the complete code for generating the campaign in its XML wrapper (assuming the actual values were input by the user and omitting the namespace reference):

     $campaign = "<campaign></campaign>";     $campaignName = makeDocLit ("name", $name);     $dailyBudget = makeDocLit ("dailyBudget", $dailyBudget);     $languages = "<languageTargeting>" . makeDocLit ("languages", $languages)        . "</languageTargeting>";     $geotargets = "<geoTargeting>" . makeDocLit ("countries", $countries)        . "</geoTargeting>";     $campaignparams = "<campaign> $campaignName $dailyBudget $languages        $geotargets</campaign>";     $campaignparamsxml = "<addCampaign> $campaignparams </addCampaign>";

If you were to hand construct the XML that this code will generate using arbitrary actual values, the XML would look like this:

     <addcampaign>        <campaign>           <name>myCampaign</name>           <dailyBudget>2000000</dailyBudget>           <languageTargeting>              <languages>EN</languages>           </languageTargeting>           <geoTargeting>              <countries>US</countries>           </geoTargeting>        </campaign>     </addcampaign>

14.3.2. Adding the Campaign

So far, none of the campaign settings have been sent to Google. Sending these settings to Google is where "the rubber meets the road"; the campaign actually gets added only if the authentication headers check out and everything else was done right.

Now that the values for the campaign have been constructed, the campaign can be added using the web service client that was created earlier:

     $campaign = $campaignclient->call("addCampaign", $campaignparamsxml);     $campaign = $campaign['addCampaignReturn'];

If there are no SOAP errors, a campaign is successfully created; rather than just assume that things will go well, you need to handle errors and ensure that's what actually occurs.

14.3.3. Handling Errors

If the fault property of the web service client object is not null, then there is a SOAP error. A message generated by the web service will be displayed, and the process of adding objects to AdWords can't continue. Here's the code to check for an error:

     if($campaignclient->fault) {        showErrors($campaignclient);        echo '<a href="authenticate.php">Try again</a>';     }     ...

The showErrors( ) function, part of the hd_lib, is called:

     function showErrors($client) {        echo "FAULT:  {$client->fault}<br>\n";        echo "Code: {$client->faultcode}<br>\n";        echo "String: {$client->faultstring}<br>\n";        echo "Detail: {$client->faultdetail}<br>\n";     }

As mentioned before, you'll need to include this library to take advantage of showErrors( ):

     require_once('hd_lib.inc');

If there is a problem, this code will generate a display like that shown in Figure 14-2.

Figure 14-2. Error-handling leaves something to be desired, but it's better than nothing and helps to give the developer a clue about the cause of problems

This error handling will help developers by giving them a clue about the cause of a problem when their code isn't correctly creating objects. However, it is not the kind of thing you'd want an end user to see. In an end-user application, great care should be taken to validate user input, and error messages should be encapsulated to be more user-friendly.

14.3.4. Getting the Campaign ID

If there are no faults, then the campaign has been created and added to the AdWords account, and a campaign ID is generated. The campaign ID is the crucial value you need to programmatically move down the chain of AdWords objects. Essentially, obtaining a valid campaign ID is the point of all the code up to this point.

This information can be displayed and saved via PHP session tracking for use in other modules:

     ...     else{        $campaignId =  $campaign['id'];        echo "Your new campaign has been created! <br>\n";        echo "The id of the new campaign is " . $campaign['id'] .           " and the name is " .        $campaign['name'] . ".<br>\n<br>\n";        session_register('campaignId');

The code can also dynamically generate an HTML form for the user to input the name of an AdGroup to create and its maximum CPC.

Example 14-2 shows the complete code for creating authentication headers, connecting to the campaign service WSDL file, creating a campaign, checking for errors, and (upon success) displaying the campaign ID, and a form for ad group information.

Example 14-2. Creating the campaign and getting input for AdGroup creation (campaign.php)

 <?php session_start(  ) ?> <!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>Campaign Creation</title> </head> <body> <?php require_once('NuSOAP/nusoap.php'); require_once('hd_lib.inc'); echo "<h1>Campaign Creation</h1>"; $email = $_POST['email']; $password = $_POST['password']; $useragent = $_POST['useragent']; $token = $_POST['token']; $name = $_POST['name']; $dailyBudget = $_POST['dailyBudget']; $languages = $_POST['languages']; $countries = $_POST['countries'];   // 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);   // First create the campaign $campaign = "<campaign></campaign>"; $campaignName = makeDocLit ("name", $name); $dailyBudget = makeDocLit ("dailyBudget", $dailyBudget); $languages = "<languageTargeting>" . makeDocLit ("languages", $languages)    . "</languageTargeting>"; $geotargets = "<geoTargeting>" . makeDocLit ("countries", $countries)    . "</geoTargeting>"; $campaignparams = "<campaign> $campaignName $dailyBudget $languages    $geotargets</campaign>"; $campaignparamsxml = "<addCampaign> $campaignparams </addCampaign>";   // Add the campaign $campaign = $campaignclient->call("addCampaign", $campaignparamsxml); $campaign = $campaign['addCampaignReturn'];   // Handle any SOAP errors if($campaignclient->fault) {    showErrors($campaignclient);    echo '<a href="authenticate.php">Try again</a>'; } else{    $campaignId =  $campaign['id'];    echo "Your new campaign has been created! <br>\n";    echo "The id of the new campaign is " . $campaign['id'] .       " and the name is " .    $campaign['name'] . ".<br>\n<br>\n";    session_register('campaignId');    echo '<form action="adgroup.php" method="POST">    <table cellspacing=15>    <tr><td>    Enter the name for your new AdGroup:    </td><td>    <input type="text" name="name" value="AdGroup 1">    </td></tr><tr><td>    Enter your Max CPC for the AdGroup (micro-currency units):    </td><td>    <input type="text" name="maxcpc">    </td></tr><tr><tr><td></td><td>    <input type="submit" name"Continue" value="Create AdGroup">    </td></tr>    </table>    </form>'; } ?> </body> </html>

Figure 14-3 shows the ID for the newly created campaign and the form that is dynamically generated in PHP for the user to name an AdGroup within the campaign and provide a maximum CPC for that campaign.

Figure 14-3. Once the new campaign has been created, you can use its ID to create an AdGroup within it

Example 14-3 shows the XML wrapper function and the error-handling function, both in a library file (both functions are used by the code in the example).

Example 14-3. Handling errors and adding XML wrappers (hd_lib.inc library file)

 <?php function makeDocLit($xml, $var) {    return '<' . $xml . '>' . $var . '</' . $xml . '>'; } function showErrors($client) {    echo "FAULT:  {$client->fault}<br>\n";    echo "Code: {$client->faultcode}<br>\n";    echo "String: {$client->faultstring}<br>\n";    echo "Detail: {$client->faultdetail}<br>\n"; } ?>