google-adx-buyer-api 0.4.6 → 0.4.7

data/ChangeLog

@@ -1,3 +1,8 @@
+0.4.7:
+  - Now require google-adwords-api-0.9.3 or later.
+  - Added examples for v201306.
+  - Removed examples for sunset API versions.
+
 0.4.6:
   - Now require google-adwords-api-0.8.2 or later.
   - Added examples for v201302.

data/README

@@ -3,7 +3,7 @@
 Welcome to the next generation Google-developed Ruby client library for the
 AdWords and DoubleClick Ad Exchange Buyer API!
 
-It contains full support for v201206, v201209 and v201302, with full stubs, and
+It contains full support for v201209, v201302 and v201306, with full stubs, and
 a simplified programming interface that lets you handle everything in native
 Ruby collections.
 
@@ -45,20 +45,25 @@ There is an example configuration file shipped with these libraries.
 You can also pass API a manually constructed config hash like:
    adwords = AdwordsApi::Api.new({
      :authentication => {
-         :method => 'ClientLogin',
+         :method => 'OAuth2',
+         :oauth2_client_id: 'INSERT_OAUTH2_CLIENT_ID_HERE'
+         :oauth2_client_secret: 'INSERT_OAUTH2_CLIENT_SECRET_HERE'
          :developer_token => 'DEVELOPER_TOKEN',
-         :user_agent => 'Ruby Sample',
-         :password => 'PASSWORD',
-         :email => 'user@domain.com',
-         :client_customer_id => '012-345-6789'
+         :client_customer_id => '012-345-6789',
+         :user_agent => 'Ruby Sample'
      },
      :service => {
        :environment => 'PRODUCTION'
      }
    })
 
-Then, just specify which service you're looking to use, and which version:
-   campaign_srv = adwords.service(:CampaignService, :v201302)
+To obtain OAuth2 client credentials, follow instructions on the wiki:
+
+  http://code.google.com/p/google-api-ads-ruby/wiki/OAuth2
+
+Once the library instance is create, specify which service you're looking to
+use, and which version:
+   campaign_srv = adwords.service(:CampaignService, :v201306)
 
 and you should now be able to just use the API methods in the object you were
 returned:
@@ -91,14 +96,12 @@ In order to make things more Ruby-like for our Ruby developers, we've renamed
 API objects and methods to more closely match Ruby conventions. This means using
 snake_case for methods and parameters, and UpperCamelCase for class names.
 
-For example, the 'getReportFields' method of the ReportDefinitionService is
-named 'get_report_fields' in the client library. You invoke it by doing:
-   response = report_def_srv.get_report_fields(report_type)
+For example, the 'startDate' field of the Campaign object is named 'start_date'
+in the client library. The 'get' method, returns a CampaignPage object which has
+an 'entries' and a 'total_num_entries' field. So, to access the return
+values, you would do this:
 
-The 'get' method, on the other hand, returns a ReportDefinitionPage object which
-has an 'entries' and a 'total_num_entries' field. So, to access the return
-values, you would do:
-   response = report_def_srv.get(selector)
+   response = campaign_srv.get(selector)
    num_entries = response[:total_num_entries]
 
 Essentially, all you have to do is follow Ruby conventions, and the library will
@@ -142,20 +145,23 @@ Request details and units spend are logged at the INFO log level, while raw HTTP
 headers and XML dumps are logged at the DEBUG log level. For more details on
 using Logger refer to the Ruby Logger documentation.
 
-=== 2.4 - Calculating unit spend:
+=== 2.4 - Calculating operations usage
+
+Each AdWords API operation performed consumes a certain number of operations as
+described in the rate sheet:
 
-Each AdWords API operation performed consumes a certain number of API units, as
-specified in the rate sheet:
-  http://code.google.com/apis/adwords/docs/ratesheet.html
+  https://developers.google.com/adwords/api/docs/ratesheet
 
-The amount of units spent is returned in the header part of the SOAP response.
-This information can be obtained by passing a user block during method call:
-  response = report_def_srv.get(selector) do |header|
-    puts "Units spent: %d" % header[:units]
+The amount of operations consumed is returned in the header part of the SOAP
+response. This information can be obtained by passing a user block during the
+method call:
+
+  response = campaign_srv.get(selector) do |header|
+    puts "Operations consumed: %d" % header[:operations]
   end
 
 You can also retrieve the response body as the second block parameter:
-  report_def_srv.get(selector) {|header, body| ... }
+  campaign_srv.get(selector) {|header, body| ... }
 
 === 2.5 - GZip compression
 
@@ -195,6 +201,11 @@ Questions can be asked on forum
 
   http://groups.google.com/group/adwords-api
 
+Make sure to subscribe to our Google Plus page for API change announcements and
+other news:
+
+  https://plus.google.com/+GoogleAdsDevelopers
+
 
 = Copyright/License Info
 

data/examples/{v201206 → v201306}/account_management/get_account_changes.rb

@@ -114,11 +114,19 @@ def get_account_changes()
 end
 
 if __FILE__ == $0
-  API_VERSION = :v201206
+  API_VERSION = :v201306
 
   begin
     get_account_changes()
 
+  # 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

data/examples/{v201206 → v201306}/basic_operations/add_ad_group.rb

@@ -43,17 +43,17 @@ def add_ad_group(campaign_id)
       :name => 'Earth to Mars Cruises #%s' % (Time.new.to_f * 1000).to_i,
       :status => 'ENABLED',
       :campaign_id => campaign_id,
-      :bids => {
-        # The 'xsi_type' field allows you to specify the xsi:type of the object
-        # being created. It's only necessary when you must provide an explicit
-        # type that the client library can't infer.
-        :xsi_type => 'ManualCPMAdGroupBids',
-        :max_cpc => {
-          :amount => {
-            :micro_amount => 10000000
+      :bidding_strategy_configuration => {
+        :bids => [
+          {
+            # The 'xsi_type' field allows you to specify the xsi:type of the
+            # object being created. It's only necessary when you must provide
+            # an explicit type that the client library can't infer.
+            :xsi_type => 'CpmBid',
+            :bid => {:micro_amount => 10000000},
           }
-        }
-      },
+        ]
+      }
     }
   }
 
@@ -64,12 +64,20 @@ def add_ad_group(campaign_id)
 end
 
 if __FILE__ == $0
-  API_VERSION = :v201206
+  API_VERSION = :v201306
 
   begin
     campaign_id = 'INSERT_CAMPAIGN_ID_HERE'.to_i
     add_ad_group(campaign_id)
 
+  # 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

data/examples/{v201206 → v201306}/basic_operations/add_campaign.rb

@@ -20,7 +20,7 @@
 #
 # This example illustrates how to create a campaign.
 #
-# Tags: CampaignService.mutate
+# Tags: CampaignService.mutate, BudgetService.mutate
 
 require 'adwords_api'
 
@@ -33,27 +33,32 @@ def add_campaign()
   # the configuration file or provide your own logger:
   # adwords.logger = Logger.new('adwords_xml.log')
 
+  budget_srv = adwords.service(:BudgetService, API_VERSION)
   campaign_srv = adwords.service(:CampaignService, API_VERSION)
 
+  # Create a budget, which can be shared by multiple campaigns.
+  budget = {
+    :name => 'Interplanetary budget #%d' % (Time.new.to_f * 1000).to_i,
+    :amount => {:micro_amount => 50000000},
+    :delivery_method => 'STANDARD',
+    :period => 'DAILY'
+  }
+  budget_operation = {:operator => 'ADD', :operand => budget}
+
+  # Add budget.
+  return_budget = budget_srv.mutate([budget_operation])
+  budget_id = return_budget[:value].first[:budget_id]
+
   # Prepare for adding campaign.
   operation = {
     :operator => 'ADD',
     :operand => {
       :name => 'Interplanetary Cruise #%s' % (Time.new.to_f * 1000).to_i,
       :status => 'PAUSED',
-      :bidding_strategy => {
-        # The 'xsi_type' field allows you to specify the xsi:type of the object
-        # being created. It's only necessary when you must provide an explicit
-        # type that the client library can't infer.
-        :xsi_type => 'ManualCPM'
-      },
-      :budget => {
-        :period => 'DAILY',
-        :amount => {
-          :micro_amount => 50000000
-        },
-        :delivery_method => 'STANDARD'
+      :bidding_strategy_configuration => {
+        :bidding_strategy_type => 'MANUAL_CPM'
       },
+      :budget => {:budget_id => budget_id},
       # Set the campaign network options to Search and Search Network.
       :network_setting => {
         :target_google_search => false,
@@ -74,11 +79,19 @@ def add_campaign()
 end
 
 if __FILE__ == $0
-  API_VERSION = :v201206
+  API_VERSION = :v201306
 
   begin
     add_campaign()
 
+  # 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

data/examples/{v201206 → v201306}/basic_operations/add_placements.rb

@@ -75,12 +75,20 @@ def add_placements(ad_group_id)
 end
 
 if __FILE__ == $0
-  API_VERSION = :v201206
+  API_VERSION = :v201306
 
   begin
     ad_group_id = 'INSERT_AD_GROUP_ID_HERE'.to_i
     add_placements(ad_group_id)
 
+  # 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

data/examples/{v201206 → v201306}/basic_operations/add_thirdparty_redirect_ad.rb

@@ -49,13 +49,15 @@ def add_thirdparty_redirect_ad(ad_group_id)
       :width => 300
     },
     # This field normally contains the javascript ad tag.
-    :snippet =>
-        '<img src="https://sandbox.google.com/sandboximages/image.jpg"/>',
-    :impression_beacon_url => 'http://www.examples.com/beacon',
-    :certified_vendor_format_id => 119,
+    :snippet => '<img src="http://goo.gl/HJM3L"/>',
+    # DoubleClick Rich Media Expandable format ID.
+    :certified_vendor_format_id => 232,
     :is_cookie_targeted => false,
     :is_user_interest_targeted => false,
-    :is_tagged => false
+    :is_tagged => false,
+    # Expandable Ad properties.
+    :expanding_directions => ['EXPANDING_UP', 'EXPANDING_DOWN'],
+    :ad_attributes => ['ROLL_OVER_TO_EXPAND']
   }
 
   # Create in-stream third party redirect ad.
@@ -102,13 +104,21 @@ def add_thirdparty_redirect_ad(ad_group_id)
 end
 
 if __FILE__ == $0
-  API_VERSION = :v201206
+  API_VERSION = :v201306
 
   begin
     # Ad group ID to add text ads to.
     ad_group_id = 'INSERT_AD_GROUP_ID_HERE'.to_i
     add_thirdparty_redirect_ad(ad_group_id)
 
+  # 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

data/examples/{v201206 → v201306}/basic_operations/delete_ad.rb

@@ -55,13 +55,21 @@ def delete_ad(ad_group_id, ad_id)
 end
 
 if __FILE__ == $0
-  API_VERSION = :v201206
+  API_VERSION = :v201306
 
   begin
     ad_group_id = 'INSERT_AD_GROUP_ID_HERE'.to_i
     ad_id = 'INSERT_AD_ID_HERE'.to_i
     delete_ad(ad_group_id, ad_id)
 
+  # 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

data/examples/{v201206 → v201306}/basic_operations/delete_ad_group.rb

@@ -52,12 +52,20 @@ def delete_ad_group(ad_group_id)
 end
 
 if __FILE__ == $0
-  API_VERSION = :v201206
+  API_VERSION = :v201306
 
   begin
     ad_group_id = 'INSERT_AD_GROUP_ID_HERE'.to_i
     delete_ad_group(ad_group_id)
 
+  # 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

data/examples/{v201206 → v201306}/basic_operations/delete_campaign.rb

@@ -53,12 +53,20 @@ def delete_campaign(campaign_id)
 end
 
 if __FILE__ == $0
-  API_VERSION = :v201206
+  API_VERSION = :v201306
 
   begin
     campaign_id = 'INSERT_CAMPAIGN_ID_HERE'.to_i
     delete_campaign(campaign_id)
 
+  # 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

data/examples/{v201206 → v201306}/basic_operations/delete_placement.rb

@@ -60,7 +60,7 @@ def delete_placement(ad_group_id, criterion_id)
 end
 
 if __FILE__ == $0
-  API_VERSION = :v201206
+  API_VERSION = :v201306
 
   begin
     # IDs of criterion to delete and its ad group.
@@ -68,6 +68,14 @@ if __FILE__ == $0
     criterion_id = 'INSERT_CRITERION_ID_HERE'.to_i
     delete_placement(ad_group_id, criterion_id)
 
+  # 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

data/examples/{v201206 → v201306}/basic_operations/get_ad_groups.rb

@@ -56,12 +56,20 @@ def get_all_ad_groups(campaign_id)
 end
 
 if __FILE__ == $0
-  API_VERSION = :v201206
+  API_VERSION = :v201306
 
   begin
     campaign_id = 'INSERT_CAMPAIGN_ID_HERE'.to_i
     get_all_ad_groups(campaign_id)
 
+  # 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

data/examples/{v201206 → v201306}/basic_operations/get_campaigns.rb

@@ -54,11 +54,19 @@ def get_all_campaigns()
 end
 
 if __FILE__ == $0
-  API_VERSION = :v201206
+  API_VERSION = :v201306
 
   begin
     get_all_campaigns()
 
+  # 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