google-adwords-api 0.13.2 → 0.14.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    NGFiZjhmY2VhYjA0NmQwYzgxNWY1Njk1ZmFjMWExMDMyNzQzMDFkMQ==
+    YTU0N2JkMzRmZjM1MmI4Nzc1ZTcyMTBjY2NjN2Y0ZTdhYjUzZjliNQ==
   data.tar.gz: !binary |-
-    OTBiYTQwM2RkNzdiNTM5ZGFkOGEwMjAwZTMyYWQ2MmRiOWFjMmE5MA==
+    NDM3YmM4YTJkYWUzYjk5NjQwYTE5OGQxZjUyYjc1OTIwMTAyMWIwYQ==
 SHA512:
   metadata.gz: !binary |-
-    MWU4MzAxNTgzNjRkMDJlZDdkZTVhZWE0MjNjMTg3YjJlOTA1OTEyNzM5NTM3
-    OGRmYjAxYjViNGUyZTg0MDdiNTYwNmE3MjE1NGQ5MjlhMDI3ZjJkMjNlNjg1
-    MTEwNDMxMmJjMWQyMjhiNDRjZTAwYTY4N2FkNjI5YTdmMmNjMmM=
+    MGNiMTBiNjlhMDZmZGQ5NmJjMjlmZWQ1NWViNmJlMjgzNWZjZjA1NGI1NjNh
+    OTMwYmZhZDVkOWI2YmRjZGJkNjAwY2M4MWQ4NmM1ZDgyMjAwYWY4YjE0MzAw
+    OWM0NjZjMmI0YTg2YzYwYWNmM2Q2YjNjYmE3YmYwZjMwMGU3Nzk=
   data.tar.gz: !binary |-
-    ODY3Mjk2YTBjZGU1N2JmZWVjYTFmZWU4MTIyOWM3ZmQ1NDAwNTg1YmE3YTlk
-    ODI4NjhiODUzODg3MzdkNzVhNTkyNzgzZTY1MDQyMWNlZjJmYWMwYTdmOWI3
-    NjU4NTc3YWY1N2QwZjQ3NGUzNjM2ZjI0MzBjYTAzN2U1Mzc2MDY=
+    NzIwNzQ5ZjdmNjI0OGIxOTVhYzY0YTI3Zjk1YmFhNzBhY2M0ZDEzNWI4MmU0
+    MWIwMDFlYzc0ZTJlMDVkNDRhMzU5NDllOWY1M2U2M2Q4M2U3Y2MzYjNhODNi
+    N2I5ZjA5ZDY1NGZjMjU0YTRhMTQ0MGVlYjkyNTRmYTE4YmRiYjQ=

data/ChangeLog

@@ -1,3 +1,15 @@
+0.14.0:
+  - Removed deprecated API version v201402.
+  - Removed support for returnMoneyInMicros header.
+  - Reworked Places examples to reference Google My Business.
+
+0.13.4:
+  - Added rule-based remarketing example.
+  - Require google-ads-common 0.9.6 or later from now on.
+
+0.13.3:
+  - Fixing file permissions on gem.
+
 0.13.2:
   - Support and examples for v201409.
 

data/examples/v201406/advanced_operations/{add_places_location_extensions.rb → add_google_my_business_location_extensions.rb}

@@ -18,15 +18,15 @@
 #           See the License for the specific language governing permissions and
 #           limitations under the License.
 #
-# This example adds a feed that syncs feed items from a Google Places account
-# and associates the feed with a customer.
+# This example adds a feed that syncs feed items from a Google My Business (GMB)
+# account and associates the feed with a customer.
 #
 # Tags: CustomerFeedService.mutate, FeedService.mutate
 
 require 'adwords_api'
 require 'date'
 
-def add_places_location_extensions(places_email_address, places_access_token)
+def add_gmb_location_extensions(gmb_email_address, gmb_access_token)
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
@@ -38,30 +38,33 @@ def add_places_location_extensions(places_email_address, places_access_token)
   feed_srv = adwords.service(:FeedService, API_VERSION)
   customer_feed_srv = adwords.service(:CustomerFeedService, API_VERSION)
 
-  places_feed = {
-    :name => "Places feed #%d" % (Time.new.to_f * 1000).to_i,
+  # Create a feed that will sync to the Google My Business account specified
+  # by gmb_email_address. Do not add FeedAttributes to this object, as AdWords
+  # will add them automatically because this will be a system generated feed.
+  gmb_feed = {
+    :name => "GMB feed #%d" % (Time.new.to_f * 1000).to_i,
     :system_feed_generation_data => {
       :xsi_type => 'PlacesLocationFeedData',
       :o_auth_info => {
         :http_method => 'GET',
-        :http_request_url => 'https://www.google.com/local/add',
-        :http_authorization_header => "Bearer %s" % places_access_token
+        :http_request_url => 'https://www.googleapis.com/auth/adwords',
+        :http_authorization_header => "Bearer %s" % gmb_access_token
       },
-      :email_address => places_email_address
+      :email_address => gmb_email_address
     },
     # Since this feed's feed items will be managed by AdWords, you must set
     # its origin to ADWORDS.
     :origin => 'ADWORDS'
   }
 
-  places_operation = {
+  gmb_operation = {
     :operator => 'ADD',
-    :operand => places_feed
+    :operand => gmb_feed
   }
 
-  result = feed_srv.mutate([places_operation])
+  result = feed_srv.mutate([gmb_operation])
   added_feed = result[:value].first
-  puts "Added places feed with ID %d" % added_feed[:id]
+  puts "Added GMB feed with ID %d" % added_feed[:id]
 
   # Add a CustomerFeed that associates the feed with this customer for the
   # LOCATION placeholder type.
@@ -127,10 +130,16 @@ if __FILE__ == $0
   MAX_CUSTOMER_FEED_ADD_ATTEMPTS = 10
 
   begin
-    places_email_address = 'INSERT_PLACES_EMAIL_ADDRESS_HERE'
-    places_access_token = 'INSERT_PLACES_ACCESS_TOKEN_HERE'
+    # The email address of the owner of the GMB account.
+    gmb_email_address = 'INSERT_GMB_EMAIL_ADDRESS_HERE'
 
-    add_places_location_extensions(places_email_address, places_access_token)
+    # To obtain an access token for your GMB account, generate a refresh token
+    # as you did for AdWords, but make sure you are logged in as the same user
+    # as gmb_email_address above when you follow the link, then capture
+    # the generated access token.
+    gmb_access_token = 'INSERT_GMB_ACCESS_TOKEN_HERE'
+
+    add_gmb_location_extensions(gmb_email_address, gmb_access_token)
 
   # Authorization error.
   rescue AdsCommon::Errors::OAuth2VerificationRequired => e

data/examples/v201409/advanced_operations/{add_places_location_extensions.rb → add_google_my_business_location_extensions.rb}

@@ -18,15 +18,16 @@
 #           See the License for the specific language governing permissions and
 #           limitations under the License.
 #
-# This example adds a feed that syncs feed items from a Google Places account
-# and associates the feed with a customer.
+# This example adds a feed that syncs feed items from a Google My Business (GMB)
+# account and associates the feed with a customer.
 #
 # Tags: CustomerFeedService.mutate, FeedService.mutate
 
 require 'adwords_api'
 require 'date'
 
-def add_places_location_extensions(places_email_address, places_access_token)
+def add_gmb_location_extensions(gmb_email_address, gmb_access_token,
+                                business_account_identifier)
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
@@ -38,30 +39,39 @@ def add_places_location_extensions(places_email_address, places_access_token)
   feed_srv = adwords.service(:FeedService, API_VERSION)
   customer_feed_srv = adwords.service(:CustomerFeedService, API_VERSION)
 
-  places_feed = {
-    :name => "Places feed #%d" % (Time.new.to_f * 1000).to_i,
+  # Create a feed that will sync to the Google My Business account specified
+  # by gmb_email_address. Do not add FeedAttributes to this object, as AdWords
+  # will add them automatically because this will be a system generated feed.
+  gmb_feed = {
+    :name => "GMB feed #%d" % (Time.new.to_f * 1000).to_i,
     :system_feed_generation_data => {
       :xsi_type => 'PlacesLocationFeedData',
       :o_auth_info => {
         :http_method => 'GET',
-        :http_request_url => 'https://www.google.com/local/add',
-        :http_authorization_header => "Bearer %s" % places_access_token
+        :http_request_url => 'https://www.googleapis.com/auth/adwords',
+        :http_authorization_header => "Bearer %s" % gmb_access_token
       },
-      :email_address => places_email_address
+      :email_address => gmb_email_address
     },
     # Since this feed's feed items will be managed by AdWords, you must set
     # its origin to ADWORDS.
     :origin => 'ADWORDS'
   }
+  # Only include the business_account_identifier if it's specified.
+  # A nil value will cause an invalid request.
+  unless business_account_identifier.nil?
+    gmb_feed[:system_feed_generation_data][:business_account_identifier] =
+        business_account_identifier
+  end
 
-  places_operation = {
+  gmb_operation = {
     :operator => 'ADD',
-    :operand => places_feed
+    :operand => gmb_feed
   }
 
-  result = feed_srv.mutate([places_operation])
+  result = feed_srv.mutate([gmb_operation])
   added_feed = result[:value].first
-  puts "Added places feed with ID %d" % added_feed[:id]
+  puts "Added GMB feed with ID %d" % added_feed[:id]
 
   # Add a CustomerFeed that associates the feed with this customer for the
   # LOCATION placeholder type.
@@ -127,10 +137,25 @@ if __FILE__ == $0
   MAX_CUSTOMER_FEED_ADD_ATTEMPTS = 10
 
   begin
-    places_email_address = 'INSERT_PLACES_EMAIL_ADDRESS_HERE'
-    places_access_token = 'INSERT_PLACES_ACCESS_TOKEN_HERE'
-
-    add_places_location_extensions(places_email_address, places_access_token)
+    # The email address of either an owner or a manager of the GMB account.
+    gmb_email_address = 'INSERT_GMB_EMAIL_ADDRESS_HERE'
+
+    # To obtain an access token for your GMB account, generate a refresh token
+    # as you did for AdWords, but make sure you are logged in as the same user
+    # as gmb_email_address above when you follow the link, then capture
+    # the generated access token
+    gmb_access_token = 'INSERT_GMB_OAUTH_ACCESS_TOKEN_HERE'
+
+    # If the gmb_email_address above is for a GMB manager instead of 
+    # the GMB account owner, then set business_account_identifier to the
+    # +Page ID of a location for which the manager has access. See the
+    # location extensions guide at
+    # https://developers.google.com/adwords/api/docs/guides/feed-services-locations
+    # for details.
+    business_account_identifier = nil
+
+    add_gmb_location_extensions(gmb_email_address, gmb_access_token,
+                                business_account_identifier)
 
   # Authorization error.
   rescue AdsCommon::Errors::OAuth2VerificationRequired => e

data/examples/v201409/advanced_operations/use_shared_bidding_strategy.rb

@@ -85,13 +85,7 @@ def use_shared_bidding_strategy()
         :target_google_search => true,
         :target_search_network => true,
         :target_content_network => true
-      },
-      :settings => [
-        {
-          :xsi_type => 'KeywordMatchSetting',
-          :opt_in => true
-        }
-      ]
+      }
     },
     {
       :name => "Interplanetary Cruise banner #%d" % (Time.new.to_f * 1000).to_i,
@@ -101,12 +95,6 @@ def use_shared_bidding_strategy()
       },
       :budget => {:budget_id => budget_id},
       :advertising_channel_type => 'DISPLAY',
-      :settings => [
-        {
-          :xsi_type => 'KeywordMatchSetting',
-          :opt_in => true
-        }
-      ],
       :network_setting => {
         :target_google_search => false,
         :target_search_network => false,

data/examples/v201409/basic_operations/add_campaigns.rb

@@ -75,10 +75,6 @@ def add_campaigns()
           :xsi_type => 'GeoTargetTypeSetting',
           :positive_geo_target_type => 'DONT_CARE',
           :negative_geo_target_type => 'DONT_CARE'
-        },
-        {
-          :xsi_type => 'KeywordMatchSetting',
-          :opt_in => true
         }
       ],
       :frequency_cap => {
@@ -94,12 +90,6 @@ def add_campaigns()
         :bidding_strategy_type => 'MANUAL_CPC'
       },
       :budget => {:budget_id => budget_id},
-      :settings => [
-        {
-          :xsi_type => 'KeywordMatchSetting',
-          :opt_in => true
-        }
-      ],
       :advertising_channel_type => 'DISPLAY'
     }
   ]

data/examples/v201409/remarketing/add_audience.rb

@@ -48,7 +48,6 @@ def add_audience()
       :xsi_type => 'BasicUserList',
       :name => name,
       :description => 'A list of mars cruise customers in the last year',
-      :status => 'OPEN',
       :membership_life_span => 365,
       :conversion_types => [{:name => name}],
       # Optional field.

data/examples/v201409/remarketing/add_rule_based_user_lists.rb

@@ -0,0 +1,171 @@
+#!/usr/bin/env ruby
+# Encoding: utf-8
+#
+# Author:: api.mcloonan@gmail.com (Michael Cloonan)
+#
+# Copyright:: Copyright 2014, Google Inc. All Rights Reserved.
+#
+# License:: 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.
+#
+# This example adds two rule-based remarketing user lists: one with no site
+# visit data restrictions, and another that will only include users who visit
+# your site in the next six months.
+#
+# Tags: AdwordsUserListService.mutate
+
+require 'adwords_api'
+
+def add_rule_based_user_lists()
+  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
+  # when called without parameters.
+  adwords = AdwordsApi::Api.new
+
+  # To enable logging of SOAP requests, set the log_level value to 'DEBUG' in
+  # the configuration file or provide your own logger:
+  # adwords.logger = Logger.new('adwords_xml.log')
+
+  user_list_srv = adwords.service(:AdwordsUserListService, API_VERSION)
+
+  # First rule item group - users who visited the checkout page and had more
+  # than one item in their shopping cart.
+  cart_rule_item = {
+    :xsi_type => 'StringRuleItem',
+    :key => {
+      :name => 'ecomm_pagetype'
+    },
+    :op => 'EQUALS',
+    :value => 'checkout'
+  }
+
+  cart_size_rule_item = {
+    :xsi_type => 'NumberRuleItem',
+    :key => {
+      :name => 'cartsize'
+    },
+    :op => 'GREATER_THAN',
+    :value => 1.0
+  }
+
+  # Combine the two rule items into a RuleItemGroup so AdWords will AND
+  # their rules together.
+  checkout_multiple_item_group = {
+    :items => [cart_rule_item, cart_size_rule_item]
+  }
+
+  # Second rule item group - users who checked out after October 31st
+  # and before January 1st.
+  start_date_rule_item = {
+    :xsi_type => 'DateRuleItem',
+    :key => {
+      :name => 'checkoutdate'
+    },
+    :op => 'AFTER',
+    :value => '20141031'
+  }
+
+  end_date_rule_item = {
+    :xsi_type => 'DateRuleItem',
+    :key => {
+      :name => 'checkoutdate'
+    },
+    :op => 'BEFORE',
+    :value => '20150101'
+  }
+
+  # Combine the date rule items into a RuleItemGroup.
+  checked_out_nov_dec_item_group = {
+    :items => [start_date_rule_item, end_date_rule_item]
+  }
+
+  # Combine the rule item groups into a Rule so AdWords will OR the
+  # groups together.
+  rule = {
+    :groups => [checkout_multiple_item_group, checked_out_nov_dec_item_group]
+  }
+
+  # Create the user list with no restrictions on site visit date.
+  expression_user_list = {
+    :xsi_type => 'ExpressionRuleUserList',
+    :name => 'Users who checked out in November or December OR ' +
+        'visited the checkout page with more than one item in their cart',
+    :description => 'Expression based user list',
+    :rule => rule
+  }
+
+  # Create the user list restricted to users who visit your site within the
+  # specified timeframe.
+  date_user_list = {
+    :xsi_type => 'DateSpecificRuleUserList',
+    :name => 'Date rule user list created at ' + Time.now.to_s,
+    :description => 'Users who visited the site between 20141031 and ' +
+        '20150331 and checked out in November or December OR visited the ' +
+        'checkout page with more than one item in their cart',
+    # We re-use the rule here. To avoid side effects, we need a deep copy.
+    :rule => Marshal.load(Marshal.dump(rule)),
+    # Set the start and end dates of the user list.
+    :start_date => '20141031',
+    :end_date => '20150331'
+  }
+
+  # Create operations to add the user lists.
+  operations = [expression_user_list, date_user_list].map do |user_list|
+    {
+      :operand => user_list,
+      :operator => 'ADD'
+    }
+  end
+
+  # Submit the operations.
+  response = user_list_srv.mutate(operations)
+
+  # Display the results.
+  response[:value].each do |user_list|
+    puts ("User list added with ID %d, name '%s', status '%s', " +
+        "list type '%s', accountUserListStatus '%s', description '%s'.") %
+        [user_list[:id], user_list[:name], user_list[:status],
+        user_list[:list_type], user_list[:account_user_list_status],
+        user_list[:description]]
+  end
+end
+
+if __FILE__ == $0
+  API_VERSION = :v201409
+
+  begin
+    add_rule_based_user_lists()
+
+  # Authorization error.
+  rescue AdsCommon::Errors::OAuth2VerificationRequired => e
+    puts "Authorization credentials are not valid. Edit adwords_api.yml for " +
+        "OAuth2 client ID and secret and run misc/setup_oauth2.rb example " +
+        "to retrieve and store OAuth2 tokens."
+    puts "See this wiki page for more details:\n\n  " +
+        'http://code.google.com/p/google-api-ads-ruby/wiki/OAuth2'
+
+  # HTTP errors.
+  rescue AdsCommon::Errors::HttpError => e
+    puts "HTTP Error: %s" % e
+
+  # API errors.
+  rescue AdwordsApi::Errors::ApiException => e
+    puts "Message: %s" % e.message
+    puts 'Errors:'
+    e.errors.each_with_index do |error, index|
+      puts "\tError [%d]:" % (index + 1)
+      error.each do |field, value|
+        puts "\t\t%s: %s" % [field, value]
+      end
+    end
+  end
+end