Preparing src for release 5.8.0

ChangeLog.md

@@ -1,3 +1,16 @@
+### 5.8.0
+
+AdWords:
+  - Improved targetAll comments in the AddAdGroups.php examples.
+  - Added code examples for upgraded URLs.
+
+DFP:
+  - Added support for v201502.
+  - Removed support for v201311, v201308, and v201306.
+  - Removed examples for v201403.
+  - Updated ForecastService examples.
+  - Removed support for ClientLogin with the removal of v201311 and earlier.
+
 ### 5.7.1
 
 AdWords:

examples/AdWords/v201406/AdvancedOperations/AddTextAdWithUpgradedUrls.php

@@ -63,7 +63,7 @@ function AddTextAdWithUpgradedUrlsExample(AdWordsUser $user, $adGroupId) {
     // specify one at customer, campaign, ad group, ad, criterion or
     // feed item levels.
     $textAd->trackingUrlTemplate =
-        'http://tracker.example.com/?cid={_season}&promocode={_promocode}' .
+        'http://tracker.example.com/?season={_season}&promocode={_promocode}' .
         '&u={lpurl}';
 
     // Since your tracking url has two custom parameters, provide their

examples/AdWords/v201406/BasicOperations/AddAdGroups.php

@@ -61,15 +61,17 @@ function AddAdGroupsExample(AdWordsUser $user, $campaignId) {
     // Set additional settings (optional).
     $adGroup->status = 'ENABLED';
 
-    // Targetting restriction settings - these setting only affect serving
+    // Targeting restriction settings - these settings only affect serving
     // for the Display Network.
     $targetingSetting = new TargetingSetting();
     // Restricting to serve ads that match your ad group placements.
+    // This is equivalent to choosing "Target and bid" in the UI.
     $targetingSetting->details[] =
-        new TargetingSettingDetail('PLACEMENT', TRUE);
-    // Using your ad group verticals only for bidding.
+        new TargetingSettingDetail('PLACEMENT', FALSE);
+    // Using your ad group verticals only for bidding. This is equivalent
+    // to choosing "Bid only" in the UI.
     $targetingSetting->details[] =
-        new TargetingSettingDetail('VERTICAL', FALSE);
+        new TargetingSettingDetail('VERTICAL', TRUE);
     $adGroup->settings[] = $targetingSetting;
 
     // Create operation.

examples/AdWords/v201409/AdvancedOperations/AddAdCustomizer.php

@@ -304,7 +304,7 @@ function CreateAdsWithCustomizations(AdWordsUser $user, $adGroupIds) {
   $textAd->headline = 'Luxury Cruise to {=CustomizerFeed.Name}';
   $textAd->description1 = 'Only {=CustomizerFeed.Price}';
   $textAd->description2 = 'Offer ends in {=countdown(CustomizerFeed.Date)}!';
-  $textAd->url = 'http://www.example.com';
+  $textAd->finalUrls = array('http://www.example.com');
   $textAd->displayUrl = 'www.example.com';
 
   // We add the same ad to both ad groups. When they serve, they will show

examples/AdWords/v201409/AdvancedOperations/AddClickToDownloadAd.php

@@ -50,8 +50,8 @@ function AddClickToDownloadAd(AdWordsUser $user, $adGroupId) {
 
   $clickToDownloadAppAd->name = 'Ad for demo game';
   $clickToDownloadAppAd->templateId = 353;
-  $clickToDownloadAppAd->url =
-      'http://play.google.com/store/apps/details?id=com.example.demogame';
+  $clickToDownloadAppAd->finalUrls = array(
+      'http://play.google.com/store/apps/details?id=com.example.demogame');
   $clickToDownloadAppAd->displayUrl = 'play.google.com';
 
   // Create the template elements for the ad. You can refer to
@@ -109,7 +109,7 @@ function AddClickToDownloadAd(AdWordsUser $user, $adGroupId) {
 
   foreach ($result->value as $adGroupAd) {
     printf('New click-to-download ad with ID = %d and URL = "%s" ' .
-        "was created.\n", $adGroupAd->ad->id, $adGroupAd->ad->url);
+        "was created.\n", $adGroupAd->ad->id, $adGroupAd->ad->finalUrls[0]);
   }
 }
 

examples/AdWords/v201409/AdvancedOperations/AddTextAdWithUpgradedUrls.php

@@ -1,8 +1,6 @@
 <?php
 /**
  * This example adds text ads to an ad group that uses upgraded URLs.
- * This example will only work if your account is a test account or is
- * whitelisted for this feature.
  *
  * To get ad groups, run GetAdGroups.php.
  *
@@ -63,7 +61,7 @@ function AddTextAdWithUpgradedUrlsExample(AdWordsUser $user, $adGroupId) {
     // specify one at customer, campaign, ad group, ad, criterion or
     // feed item levels.
     $textAd->trackingUrlTemplate =
-        'http://tracker.example.com/?cid={_season}&promocode={_promocode}' .
+        'http://tracker.example.com/?season={_season}&promocode={_promocode}' .
         '&u={lpurl}';
 
     // Since your tracking url has two custom parameters, provide their

examples/AdWords/v201409/BasicOperations/AddAdGroups.php

@@ -61,15 +61,17 @@ function AddAdGroupsExample(AdWordsUser $user, $campaignId) {
     // Set additional settings (optional).
     $adGroup->status = 'ENABLED';
 
-    // Targetting restriction settings - these setting only affect serving
+    // Targeting restriction settings - these settings only affect serving
     // for the Display Network.
     $targetingSetting = new TargetingSetting();
     // Restricting to serve ads that match your ad group placements.
+    // This is equivalent to choosing "Target and bid" in the UI.
     $targetingSetting->details[] =
-        new TargetingSettingDetail('PLACEMENT', TRUE);
-    // Using your ad group verticals only for bidding.
+        new TargetingSettingDetail('PLACEMENT', FALSE);
+    // Using your ad group verticals only for bidding. This is equivalent
+    // to choosing "Bid only" in the UI.
     $targetingSetting->details[] =
-        new TargetingSettingDetail('VERTICAL', FALSE);
+        new TargetingSettingDetail('VERTICAL', TRUE);
     $adGroup->settings[] = $targetingSetting;
 
     // Create operation.

examples/AdWords/v201409/BasicOperations/AddKeywords.php

@@ -60,14 +60,15 @@ function AddKeywordsExample(AdWordsUser $user, $adGroupId) {
 
     // Set additional settings (optional).
     $adGroupCriterion->userStatus = 'PAUSED';
-    $adGroupCriterion->destinationUrl = 'http://www.example.com/mars';
+    $adGroupCriterion->finalUrls = array('http://www.example.com/mars');
 
     // Set bids (optional).
     $bid = new CpcBid();
     $bid->bid =  new Money(500000);
     $biddingStrategyConfiguration = new BiddingStrategyConfiguration();
     $biddingStrategyConfiguration->bids[] = $bid;
-    $adGroupCriterion->biddingStrategyConfiguration = $biddingStrategyConfiguration;
+    $adGroupCriterion->biddingStrategyConfiguration =
+        $biddingStrategyConfiguration;
 
     $adGroupCriteria[] = $adGroupCriterion;
 

examples/AdWords/v201409/BasicOperations/AddTextAds.php

@@ -55,7 +55,7 @@ function AddTextAdsExample(AdWordsUser $user, $adGroupId) {
     $textAd->description1 = 'Visit the Red Planet in style.';
     $textAd->description2 = 'Low-gravity fun for everyone!';
     $textAd->displayUrl = 'www.example.com';
-    $textAd->url = 'http://www.example.com';
+    $textAd->finalUrls = array('http://www.example.com');
 
     // Create ad group ad.
     $adGroupAd = new AdGroupAd();

examples/AdWords/v201409/BasicOperations/UpdateKeyword.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * This example updates the destination URL of a keyword. To get keywords, run
+ * This example updates the final URL of a keyword. To get keywords, run
  * GetKeywords.php.
  *
  * Tags: AdGroupCriterionService.mutate
@@ -54,8 +54,8 @@ function UpdateKeywordExample(AdWordsUser $user, $adGroupId, $criterionId) {
   // instead of Keyword to avoid having to set keyword-specific fields.
   $adGroupCriterion->criterion = new Criterion($criterionId);
 
-  // Update destination URL.
-  $adGroupCriterion->destinationUrl = 'http://www.example.com/new';
+  // Update final URL.
+  $adGroupCriterion->finalUrls = array('http://www.example.com/new');
 
   // Create operation.
   $operation = new AdGroupCriterionOperation();

examples/AdWords/v201409/CampaignManagement/ValidateTextAd.php

@@ -54,7 +54,7 @@ function ValidateTextAdExample(AdWordsUser $user, $adGroupId) {
   $textAd->description1 = 'Description Line 1';
   $textAd->description2 = 'Description Line 2';
   $textAd->displayUrl = 'www.example.com';
-  $textAd->url = 'http://www.example.com';
+  $textAd->finalUrls = array('http://www.example.com');
 
   // Create ad group ad.
   $adGroupAd = new AdGroupAd();

examples/AdWords/v201409/ErrorHandling/HandlePolicyViolationError.php

@@ -56,7 +56,7 @@ function HandlePolicyViolationErrorExample(AdWordsUser $user, $adGroupId) {
   $textAd->description1 = 'Visit the Red Planet in style.';
   $textAd->description2 = 'Low-gravity fun for everyone!';
   $textAd->displayUrl = 'www.example.com';
-  $textAd->url = 'http://www.example.com/';
+  $textAd->finalUrls = array('http://www.example.com/');
 
   // Create ad group ad.
   $adGroupAd = new AdGroupAd();

examples/AdWords/v201409/Migration/UpgradeAdUrl.php

@@ -0,0 +1,102 @@
+<?php
+/**
+ * This code example upgrades an ad to use upgraded URLs.
+ *
+ * Tags: AdGroupAdService.get, AdGroupAdService.mutate
+ * Restriction: adwords-only
+ *
+ * Copyright 2015, Google Inc. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @package    GoogleApiAdsAdWords
+ * @subpackage v201409
+ * @category   WebServices
+ * @copyright  2015, Google Inc. All Rights Reserved.
+ * @license    http://www.apache.org/licenses/LICENSE-2.0 Apache License,
+ *             Version 2.0
+ * @author     Danial Klimkin
+ */
+
+// Include the initialization file
+require_once dirname(dirname(__FILE__)) . '/init.php';
+
+// Enter parameters required by the code example.
+$adGroupId = 'INSERT_AD_GROUP_ID_HERE';
+$adId = 'INSERT_AD_ID_HERE';
+
+/**
+ * Runs the example.
+ * @param AdWordsUser $user the user to run the example with
+ * @param string $adGroupId the ID of the ad group of the ad to upgrade
+ * @param string $adId the ID of the ad to upgrade
+ */
+function UpgradeAdUrlExample(AdWordsUser $user, $adGroupId, $adId) {
+  // Get the service, which loads the required classes.
+  $adGroupAdService = $user->GetService('AdGroupAdService', ADWORDS_VERSION);
+
+  $adGroupAd = NULL;
+
+  // Retrieving the ad first.
+  $selector = new Selector();
+  $selector->fields = array('Id', 'Url');
+  $selector->ordering[] = new OrderBy('Headline', 'ASCENDING');
+
+  // Restrict the fetch to only the selected ad group ID and ad ID.
+  $selector->predicates[] =
+      new Predicate('AdGroupId', 'EQUALS', array($adGroupId));
+  $selector->predicates[] = new Predicate('Id', 'EQUALS', array($adId));
+
+  $page = $adGroupAdService->get($selector);
+
+  if (isset($page->entries)) {
+    $adGroupAd = $page->entries[0];
+    printf("About to upgrade ad ID %d with URL '%s'.\n",
+        $adGroupAd->ad->id, $adGroupAd->ad->url);
+  } else {
+    print "Ad for upgrade was not found.\n";
+    return;
+  }
+
+  // Proceed with URL upgrade.
+  $upgradeUrl = new AdUrlUpgrade();
+  $upgradeUrl->adId = $adGroupAd->ad->id;
+  $upgradeUrl->finalUrl = $adGroupAd->ad->url;
+
+  $result = $adGroupAdService->upgradeUrl(array($upgradeUrl));
+
+  // Display results.
+  foreach ($result as $adGroupAd) {
+    printf("Text ad with ID %d was upgraded to final URLs: '%s'.\n",
+        $adGroupAd->id, join(",", $adGroupAd->finalUrls));
+  }
+}
+
+// Don't run the example if the file is being included.
+if (__FILE__ != realpath($_SERVER['PHP_SELF'])) {
+  return;
+}
+
+try {
+  // Get AdWordsUser from credentials in "../auth.ini"
+  // relative to the AdWordsUser.php file's directory.
+  $user = new AdWordsUser();
+
+  // Log every SOAP XML request and response.
+  $user->LogAll();
+
+  // Run the example.
+  UpgradeAdUrlExample($user, $adGroupId, $adId);
+} catch (Exception $e) {
+  printf("An error has occurred: %s\n", $e->getMessage());
+}