Changes for release v0_6. (#8)

CHANGELOG.md

@@ -1,3 +1,12 @@
+## 0.6.0
+
+*   Added support and examples for v0_6 of Google Ads API.
+*   Added support for passing log-in customer ID with API requests.
+*   Updated some examples to match the new API specifications, e.g.,
+    ApplyRecommendations.php, GetGeoTargetConstantByNames.php.
+*   Updated AddCampaignTargetingCriteria example to show how to include
+    proximity targeting.
+
 ## 0.5.0
 
 *   Added support and examples for v0_5 of Google Ads API.

README.md

@@ -113,11 +113,20 @@ To issue requests via the Google Ads API, you first need to create a
 For convenience, you can store the required settings in a properties file
 (`google_ads_php.ini`) with the following format:
 
+    [GOOGLE_ADS]
     developerToken = "INSERT_DEVELOPER_TOKEN_HERE"
+
+    [OAUTH2]
     clientId = "INSERT_OAUTH2_CLIENT_ID_HERE"
     clientSecret = "INSERT_OAUTH2_CLIENT_SECRET_HERE"
     refreshToken = "INSERT_OAUTH2_REFRESH_TOKEN_HERE"
 
+If you're authenticating as a manager account, additionally you must specify the manager account ID
+(with hyphens removed) as the login customer ID:
+
+    [GOOGLE_ADS]
+    loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
+
 This configuration file format is similar to the format used in the AdWords
 API's [client library for PHP](https://github.com/googleads/googleads-php-lib).
 
@@ -163,6 +172,7 @@ $oAuth2Credential = (new OAuth2TokenBuilder())
 $googleAdsClient = (new GoogleAdsClientBuilder())
     ->withOAuth2Credential($oAuth2Credential)
     ->withDeveloperToken('INSERT_DEVELOPER_TOKEN_HERE')
+    ->withLoginCustomerId('INSERT_LOGIN_CUSTOMER_ID_HERE')
     ->build();
 ```
 

examples/Authentication/AuthenticateInStandaloneApplication.php

@@ -91,12 +91,25 @@ public static function main()
 
         $oauth2->setCode($code);
         $authToken = $oauth2->fetchAuthToken();
-
         print "Your refresh token is: {$authToken['refresh_token']}" . PHP_EOL . PHP_EOL;
-        print "Copy the following lines to your 'google_ads_php.ini' file:" . PHP_EOL;
-        print "clientId = '$clientId'" . PHP_EOL;
-        print "clientSecret = '$clientSecret'" . PHP_EOL;
-        print "refreshToken = '{$authToken['refresh_token']}'" . PHP_EOL;
+
+        $propertiesToCopy = '[GOOGLE_ADS]' . PHP_EOL;
+        $propertiesToCopy .= 'developerToken = "INSERT_DEVELOPER_TOKEN_HERE"' . PHP_EOL;
+        $propertiesToCopy .=  <<<EOD
+; Required for manager accounts only: Specify the login customer ID used to authenticate API calls.
+; This will be the customer ID of the authenticated manager account. You can also specify this later
+; in code if your application uses multiple manager account + OAuth pairs.
+; loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
+EOD;
+        $propertiesToCopy .= PHP_EOL . '[OAUTH2]' . PHP_EOL;
+        $propertiesToCopy .= "clientId = \"$clientId\"" . PHP_EOL;
+        $propertiesToCopy .= "clientSecret = \"$clientSecret\"" . PHP_EOL;
+        $propertiesToCopy .= "refreshToken = \"{$authToken['refresh_token']}\"" . PHP_EOL;
+
+        print 'Copy the text below into a file named "google_ads_php.ini" in your home '
+            . 'directory, and replace "INSERT_DEVELOPER_TOKEN_HERE" with your developer '
+            . 'token:' . PHP_EOL;
+        print PHP_EOL . $propertiesToCopy;
     }
 }
 

examples/Authentication/AuthenticateInWebApplication.php

@@ -122,7 +122,13 @@ function (ServerRequestInterface $request) use ($oauth2, $loop, &$authToken) {
 
                 $propertiesToCopy = '[GOOGLE_ADS]' . PHP_EOL;
                 $propertiesToCopy .= 'developerToken = "INSERT_DEVELOPER_TOKEN_HERE"' . PHP_EOL;
-                $propertiesToCopy .= '[OAUTH2]' . PHP_EOL;
+                $propertiesToCopy .=  <<<EOD
+; Required for manager accounts only: Specify the login customer ID used to authenticate API calls.
+; This will be the customer ID of the authenticated manager account. You can also specify this later
+; in code if your application uses multiple manager account + OAuth pairs.
+; loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
+EOD;
+                $propertiesToCopy .= PHP_EOL . '[OAUTH2]' . PHP_EOL;
                 $propertiesToCopy .= "clientId = \"{$oauth2->getClientId()}\"" . PHP_EOL;
                 $propertiesToCopy .= "clientSecret = \"{$oauth2->getClientSecret()}\"" . PHP_EOL;
                 $propertiesToCopy .= "refreshToken = \"$refreshToken\"" . PHP_EOL;

examples/Authentication/google_ads_php.ini

@@ -3,6 +3,11 @@
 ; https://developers.google.com/google-ads/api/docs/first-call/overview#config
 developerToken = "INSERT_DEVELOPER_TOKEN_HERE"
 
+; Required for manager accounts only: Specify the login customer ID used to authenticate API calls.
+; This will be the customer ID of the authenticated manager account. You can also specify this later
+; in code if your application uses multiple manager account + OAuth pairs.
+; loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
+
 ; Optional additional settings.
 ; endpoint = "https://adwords.google.com/"
 

examples/BasicOperations/GetArtifactMetadata.php

@@ -109,9 +109,8 @@ public static function runExample(GoogleAdsClient $googleAdsClient, $artifactNam
             /** @var GoogleAdsField $googleAdsField */
             // Note that the category and data type printed below are enum values.
             // For example, a value of 2 will be returned when the category is 'RESOURCE'.
-            // A mapping of enum names to values can be found at
-            // GoogleAdsFieldCategoryEnum_GoogleAdsFieldCategory.php for the category and
-            // GoogleAdsFieldDataTypeEnum_GoogleAdsFieldDataType.php for the data type.
+            // A mapping of enum names to values can be found at GoogleAdsFieldCategory.php for the
+            // category and GoogleAdsFieldDataType.php for the data type.
             printf(
                 "An artifact named '%s' with category %d and data type %d %s selectable, %s "
                 . "filterable, %s sortable and %s repeated.%s",

examples/BasicOperations/GetExpandedTextAds.php

@@ -123,8 +123,7 @@ public static function runExample(GoogleAdsClient $googleAdsClient, $customerId,
             $ad = $googleAdsRow->getAdGroupAd()->getAd();
             // Note that the status printed below are enum values.
             // For example, a value of 2 will be returned when the status is 'ENABLED'.
-            // A mapping of enum names to values can be found in:
-            // AdGroupAdStatusEnum_AdGroupAdStatus.php
+            // A mapping of enum names to values can be found at AdGroupAdStatus.php
             printf(
                 "Expanded text ad with ID %d, status %d, and headline '%s - %s' was found in ad "
                 . "group with ID %d.%s",

examples/BasicOperations/GetKeywords.php

@@ -122,9 +122,8 @@ public static function runExample(GoogleAdsClient $googleAdsClient, $customerId,
             /** @var GoogleAdsRow $googleAdsRow */
             // Note that the match type and criteria type printed below are enum values.
             // For example, a value of 2 will be returned when the keyword match type is 'EXACT'.
-            // A mapping of enum names to values can be found in:
-            // Match type enum class: KeywordMatchTypeEnum_KeywordMatchType.php
-            // Criterion type enum class: CriterionTypeEnum_CriterionType.php
+            // A mapping of enum names to values can be found at KeywordMatchType.php for keyword
+            // match type and CriterionType.php for criterion type.
             printf(
                 "Keyword with text '%s', match type %d, criterion type %d, and ID %d "
                 . "was found in ad group with ID %d.%s",

examples/Recommendations/ApplyRecommendation.php

@@ -126,6 +126,8 @@ public static function runExample(
         $recommendationServiceClient = $googleAdsClient->getRecommendationServiceClient();
         $response = $recommendationServiceClient->applyRecommendation(
             $customerId,
+            // Sets the partial failure mode to false.
+            false,
             [$applyRecommendationOperation]
         );
         /** @var Recommendation $appliedRecommendation */

examples/Reporting/GetKeywordStats.php

@@ -128,8 +128,8 @@ public static function runExample(GoogleAdsClient $googleAdsClient, $customerId)
             $adGroup = $googleAdsRow->getAdGroup();
             $adGroupCriterion = $googleAdsRow->getAdGroupCriterion();
             $metrics = $googleAdsRow->getMetrics();
-            // A mapping of enum names to values for keyword match type can be found in:
-            // KeywordMatchTypeEnum_KeywordMatchType.php
+            // A mapping of enum names to values for keyword match type can be found at
+            // KeywordMatchType.php.
             printf(
                 "Keyword text '%s' with "
                 . "match type %d "

examples/Targeting/AddCampaignTargetingCriteria.php

@@ -27,14 +27,18 @@
 use Google\Ads\GoogleAds\Lib\GoogleAdsException;
 use Google\Ads\GoogleAds\Lib\OAuth2TokenBuilder;
 use Google\Ads\GoogleAds\Util\ResourceNames;
+use Google\Ads\GoogleAds\V0\Common\AddressInfo;
 use Google\Ads\GoogleAds\V0\Common\KeywordInfo;
 use Google\Ads\GoogleAds\V0\Common\LocationInfo;
+use Google\Ads\GoogleAds\V0\Common\ProximityInfo;
 use Google\Ads\GoogleAds\V0\Enums\KeywordMatchTypeEnum\KeywordMatchType;
+use Google\Ads\GoogleAds\V0\Enums\ProximityRadiusUnitsEnum\ProximityRadiusUnits;
 use Google\Ads\GoogleAds\V0\Errors\GoogleAdsError;
 use Google\Ads\GoogleAds\V0\Resources\CampaignCriterion;
 use Google\Ads\GoogleAds\V0\Services\CampaignCriterionOperation;
 use Google\ApiCore\ApiException;
 use Google\Protobuf\BoolValue;
+use Google\Protobuf\DoubleValue;
 use Google\Protobuf\StringValue;
 
 /**
@@ -130,7 +134,10 @@ public static function runExample(
                 $campaignResourceName
             ),
             // Creates a campaign criterion operation for the specified location ID.
-            self::createLocationCampaignCriterionOperation($locationId, $campaignResourceName)
+            self::createLocationCampaignCriterionOperation($locationId, $campaignResourceName),
+            // Creates a campaign criterion operation for the area around a specific address
+            // (proximity).
+            self::createProximityCampaignCriterionOperation($campaignResourceName)
         ];
 
         // Issues a mutate request to add the campaign criterion.
@@ -190,7 +197,7 @@ private static function createLocationCampaignCriterionOperation(
         // Constructs a campaign criterion for the specified campaign ID using the specified
         // location ID.
         $campaignCriterion = new CampaignCriterion([
-            // Creates another keyword with PHRASE type.
+            // Creates a location using the specified location ID.
             'location' => new LocationInfo([
                 'geo_target_constant' => new StringValue(
                     // Besides using location ID, you can also search by location names using
@@ -205,6 +212,34 @@ private static function createLocationCampaignCriterionOperation(
 
         return new CampaignCriterionOperation(['create' => $campaignCriterion]);
     }
+
+    /**
+     * Creates a campaign criterion operation for the area around a specific address (proximity).
+     *
+     * @param string $campaignResourceName the campaign resource name that the created criterion
+     *      belongs to
+     * @return CampaignCriterionOperation the created campaign criterion operation
+     */
+    private static function createProximityCampaignCriterionOperation($campaignResourceName)
+    {
+        // Constructs a campaign criterion as a proximity.
+        $campaignCriterion = new CampaignCriterion([
+            'proximity' => new ProximityInfo([
+                'address' => new AddressInfo([
+                    'street_address' => new StringValue(['value' => '38 avenue de l\'Opéra']),
+                    'city_name' => new StringValue(['value' => 'Paris']),
+                    'postal_code' => new StringValue(['value' => '75002']),
+                    'country_code' => new StringValue(['value' => 'FR']),
+                ]),
+                'radius' => new DoubleValue(['value' => 10.0]),
+                // Default is kilometers.
+                'radius_units' => ProximityRadiusUnits::MILES
+            ]),
+            'campaign' => new StringValue(['value' => $campaignResourceName])
+        ]);
+
+        return new CampaignCriterionOperation(['create' => $campaignCriterion]);
+    }
 }
 
 AddCampaignTargetingCriteria::main();

examples/Targeting/GetCampaignTargetingCriteria.php

@@ -26,7 +26,7 @@
 use Google\Ads\GoogleAds\Lib\GoogleAdsClientBuilder;
 use Google\Ads\GoogleAds\Lib\GoogleAdsException;
 use Google\Ads\GoogleAds\Lib\OAuth2TokenBuilder;
-use Google\Ads\GoogleAds\V0\Enums\CriterionTypeEnum_CriterionType;
+use Google\Ads\GoogleAds\V0\Enums\CriterionTypeEnum\CriterionType;
 use Google\Ads\GoogleAds\V0\Errors\GoogleAdsError;
 use Google\Ads\GoogleAds\V0\Services\GoogleAdsRow;
 use Google\ApiCore\ApiException;
@@ -120,14 +120,13 @@ public static function runExample(GoogleAdsClient $googleAdsClient, $customerId,
             $campaignCriterion = $googleAdsRow->getCampaignCriterion();
             // Note that the match type printed below is an enum value.
             // For example, a value of 4 will be returned when the keyword match type is 'BROAD'.
-            // A mapping of enum names to values can be found in:
-            // Match type enum class: KeywordMatchTypeEnum_KeywordMatchType.php
+            // A mapping of enum names to values can be found at KeywordMatchType.php
             printf(
                 "Campaign criterion with ID %d was found as a %s",
                 $campaignCriterion->getCriterionId()->getValue(),
                 $campaignCriterion->getNegative()->getValue() ? 'negative ' : ''
             );
-            if ($campaignCriterion->getType() === CriterionTypeEnum_CriterionType::KEYWORD) {
+            if ($campaignCriterion->getType() === CriterionType::KEYWORD) {
                 printf(
                     "keyword with text '%s' and match type %d.%s",
                     $campaignCriterion->getKeyword()->getText()->getValue(),

examples/Targeting/GetGeoTargetConstantByNames.php

@@ -40,6 +40,9 @@ class GetGeoTargetConstantByNames
     // Locale is using ISO 639-1 format. If an invalid locale is given, 'en' will be used by
     // default.
     const LOCALE = 'en';
+    // A list of country codes can be referenced here:
+    // https://developers.google.com/adwords/api/docs/appendix/geotargeting.
+    const COUNTRY_CODE = 'FR';
     // The location names to get suggested geo target constants.
     private static $LOCATION_NAMES = ['Paris', 'Quebec', 'Spain', 'Deutschland'];
 
@@ -51,7 +54,8 @@ public static function main()
         // into the constants above.
         $options = (new ArgumentParser())->parseCommandArguments([
             ArgumentNames::LOCATION_NAMES => GetOpt::MULTIPLE_ARGUMENT,
-            ArgumentNames::LOCALE => GetOpt::OPTIONAL_ARGUMENT
+            ArgumentNames::LOCALE => GetOpt::OPTIONAL_ARGUMENT,
+            ArgumentNames::COUNTRY_CODE => GetOpt::OPTIONAL_ARGUMENT
         ]);
 
         // Generate a refreshable OAuth2 credential for authentication.
@@ -68,7 +72,8 @@ public static function main()
             self::runExample(
                 $googleAdsClient,
                 $options[ArgumentNames::LOCATION_NAMES] ?: self::$LOCATION_NAMES,
-                $options[ArgumentNames::LOCALE] ?: self::LOCALE
+                $options[ArgumentNames::LOCALE] ?: self::LOCALE,
+                $options[ArgumentNames::COUNTRY_CODE] ?: self::COUNTRY_CODE
             );
         } catch (GoogleAdsException $googleAdsException) {
             printf(
@@ -101,11 +106,13 @@ public static function main()
      * @param GoogleAdsClient $googleAdsClient the Google Ads API client
      * @param array $locationNames the list of location names to get suggested geo target constants
      * @param string $locale the locale of the geo target constant to be retrieved
+     * @param string $countryCode the country code of the geo target constant to be retrieved
      */
     public static function runExample(
         GoogleAdsClient $googleAdsClient,
         array $locationNames,
-        $locale
+        $locale,
+        $countryCode
     ) {
         $geoTargetConstantServiceClient = $googleAdsClient->getGeoTargetConstantServiceClient();
 
@@ -115,6 +122,7 @@ public static function runExample(
         }
         $response = $geoTargetConstantServiceClient->suggestGeoTargetConstants(
             new StringValue(['value' => $locale]),
+            new StringValue(['value' => $countryCode]),
             ['locationNames' => new LocationNames(['names' => $names])]
         );
 

examples/Utils/ArgumentNames.php

@@ -31,6 +31,7 @@ final class ArgumentNames
     const CAMPAIGN_ID = 'campaignId';
     const CAMPAIGN_IDS = 'campaignIds';
     const CHECK_IN_DAY_CRITERION_ID = 'checkInDayCriterionId';
+    const COUNTRY_CODE = 'countryCode';
     const CPC_BID_CEILING_MICRO_AMOUNT = 'cpcBidCeilingMicroAmount';
     const CPC_BID_MICRO_AMOUNT = 'cpcBidMicroAmount';
     const CRITERION_ID = 'criterionId';
@@ -55,12 +56,13 @@ final class ArgumentNames
         self::CAMPAIGN_BUDGET_ID => 'The campaign budget ID',
         self::CAMPAIGN_ID => 'The campaign ID',
         self::CAMPAIGN_IDS => 'The campaign IDs',
+        self::CHECK_IN_DAY_CRITERION_ID => 'The hotel check-in day criterion ID',
+        self::COUNTRY_CODE => 'The country code',
         self::CPC_BID_CEILING_MICRO_AMOUNT => 'The CPC bid ceiling micro amount',
         self::CPC_BID_MICRO_AMOUNT => 'The CPC bid micro amount',
         self::CRITERION_ID => 'The criterion ID',
         self::CUSTOMER_ID => 'The customer ID without dashes',
         self::HOTEL_CENTER_ACCOUNT_ID => 'The hotel center account ID',
-        self::CHECK_IN_DAY_CRITERION_ID => 'The hotel check-in day criterion ID',
         self::KEYWORD_TEXT => 'The keyword text',
         self::LOCALE => 'The locale',
         self::LOCATION_ID => 'The location ID',