adwords4r 12.0.0 → 12.1.0

data/ChangeLog.txt

@@ -1,3 +1,7 @@
+12.1.0
+- Removed support for v11 of the API, which has been deco'ed.
+- Replaced some old examples that weren't behaving properly with better, well-commented example code.
+
 12.0.0
 - Added support for v12 of the AdWords API.
   Removed support for v10 of the API, which has been deco'ed.

data/Rakefile

@@ -16,7 +16,7 @@ require 'lib/adwords4r/services'
 
 CLOBBER.include('pkg')
 
-CURRENT_VERSION = '12.0.0'
+CURRENT_VERSION = '12.1.0'
 PKG_VERSION = ENV['REL'] ? ENV['REL'] : CURRENT_VERSION
 
 SRC_RB = FileList['lib/**/*.rb']

data/Readme.txt

@@ -57,10 +57,10 @@ adwords = AdWords::API.new(credentials, version)
 
 In order to use the sandbox, you can add a credential named
 alternateUrl like:
-alternateUrl=https://sandbox.google.com/api/adwords/v11/
+alternateUrl=https://sandbox.google.com/api/adwords/v12/
 
 Then just use methods of the API against your driver.
-See sample code in examples, particularly reports.rb
+See sample code in the examples directory for working examples you can build from.
 
 It is often useful to see a trace of the raw SOAP XML being sent and received.
 To enable this, set the ADWORDS4R_DEBUG environment variable to TRUE.

data/adwords.properties

@@ -4,4 +4,4 @@ useragent=APPLICATION_NAME
 password=ADWORDS_PASSWORD
 email=ADWORDS_MCC_LOGIN
 clientEmail=OPTIONAL_CLIENT_LOGIN
-#alternateUrl=https://sandbox.google.com/api/adwords/v11/
+#alternateUrl=https://sandbox.google.com/api/adwords/v12/

data/examples/account_info.rb

@@ -0,0 +1,131 @@
+#!/usr/bin/ruby
+#
+# Copyright 2008, 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.
+#
+# This code sample illustrates how to fetch all the client accounts under an
+# MCC account, and then iteratively retrieves information about each account.
+
+require 'rubygems'
+gem 'soap4r', '>= 1.5.8'
+require 'adwords4r'
+
+
+def main()
+  begin
+    # AdWords::AdWordsCredentials.new will read a credentials file from
+    # ENV['HOME']/adwords.properties when called without parameters.
+    # The latest versioned release of the API will be assumed.
+    #
+    # Credentials can be either for the production or Sandbox environments.
+    # Production environment credentials overview:
+    # http://www.google.com/apis/adwords/developer/index.html
+    # Sandbox environment credentials overview:
+    # http://www.google.com/apis/adwords/developer/adwords_api_sandbox.html
+    #
+    # Instead of reading them from a file, the credentials can be
+    # specified inline as a hash:
+    #
+    # creds = {
+    #   'developerToken' => 'user@domain.com++USD',
+    #   'useragent' => 'Sample User Agent',
+    #   'password' => 'password',
+    #   'email' => 'user@domain.com',
+    #   'clientEmail' => 'client_1+user@domain.com',
+    #   'applicationToken' => 'IGNORED',
+    #   'alternateUrl' => 'https://sandbox.google.com/api/adwords/v12/',
+    # }
+    # adwords = AdWords::API.new(AdWords::AdWordsCredentials.new(creds), 12)
+
+    adwords = AdWords::API.new
+
+    # Clear out the clientEmail header temporarily so that we run under the
+    # context of the MCC user.
+    adwords.credentials.setHeader('clientEmail', '')
+
+    client_accounts = adwords.getClientAccounts
+
+    if client_accounts.length > 0 then
+      client_accounts.each do |client_account|
+        # Set the clientEmail header to each account's login email so that API
+        # calls are made in the context of that account.
+        adwords.credentials.setHeader('clientEmail', client_account)
+        account_info = adwords.getAccountInfo.getAccountInfoReturn
+
+        puts 'Client Email: %s' % client_account
+        if ! account_info.descriptiveName.empty? then
+          puts 'Client Name: %s' % account_info.descriptiveName
+        end
+        puts 'Client ID: %s' % account_info.customerId
+        puts
+      end
+    else
+      puts 'There are no client accounts beneath this account.'
+    end
+
+  rescue Errno::ECONNRESET, SOAP::HTTPStreamError, SocketError => e
+    # This exception indicates a connection-level error.
+    # In general, it is likely to be transitory.
+
+    puts 'Connection Error: %s' % e
+    puts 'Source: %s' % e.backtrace.first
+    
+  rescue AdWords::Error::UnknownAPICall => e
+    # This exception is thrown when an unknown SOAP method is invoked.
+
+    puts e
+    puts 'Source: %s' % e.backtrace.first
+    
+  rescue AdWords::Error::ApiError => e
+    # This exception maps to receiving a SOAP Fault back from the service.
+    # The e.soap_faultstring_ex, e.code_ex, and potentially e.trigger_ex
+    # attributes are the most useful, but other attributes may be populated
+    # as well. To display all attributes, the following can be used:
+    #
+    # e.instance_variables.each do |var|
+    #   value = e.instance_variable_get(var)
+    #   if ! value.nil?
+    #     puts '%s => %s' % [var, value]
+    #   end
+    # end
+
+    puts 'SOAP Error: %s (code: %d)' % [e.soap_faultstring_ex, e.code_ex]
+    puts 'Trigger: %s' % e.trigger_ex unless e.trigger_ex.nil?
+    puts 'Source: %s' % e.backtrace.first
+
+  ensure
+    # Display API unit usage info. This data is stored as a class variable
+    # in the AdWords::API class and accessed via static methods.
+    # AdWords::API.get_total_units() returns a running total of units used in
+    # the scope of the current program.
+    # AdWords::API.get_last_units() returns the number used in the last call.
+
+    puts
+    puts '%d API units consumed total (%d in last call).' %
+      [AdWords::API.get_total_units(), AdWords::API.get_last_units()]
+  end
+end
+
+
+if __FILE__ == $0
+  # The adwords4r library can log all SOAP requests and responses to files.
+  # This is often useful for debugging purposes.
+  # To enable this, set the ADWORDS4R_DEBUG environement varaible to 'true'.
+  # This can be done either from your operating system environment or via
+  # code, as done below.
+
+  ENV['ADWORDS4R_DEBUG'] = 'false'
+
+  main()
+end

data/examples/create_all.rb

@@ -0,0 +1,165 @@
+#!/usr/bin/ruby
+#
+# Copyright 2008, 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.
+#
+# This code sample illustrates how to create a new campaign, ad group, text ad,
+# keywords, and website criteria, all in one fell swoop.
+
+require 'rubygems'
+gem 'soap4r', '>= 1.5.8'
+require 'adwords4r'
+
+
+def main()
+  begin
+    # AdWords::AdWordsCredentials.new will read a credentials file from
+    # ENV['HOME']/adwords.properties when called without parameters.
+    # The latest versioned release of the API will be assumed.
+    #
+    # Credentials can be either for the production or Sandbox environments.
+    # Production environment credentials overview:
+    # http://www.google.com/apis/adwords/developer/index.html
+    # Sandbox environment credentials overview:
+    # http://www.google.com/apis/adwords/developer/adwords_api_sandbox.html
+    #
+    # Instead of reading them from a file, the credentials can be
+    # specified inline as a hash:
+    #
+    # creds = {
+    #   'developerToken' => 'user@domain.com++USD',
+    #   'useragent' => 'Sample User Agent',
+    #   'password' => 'password',
+    #   'email' => 'user@domain.com',
+    #   'clientEmail' => 'client_1+user@domain.com',
+    #   'applicationToken' => 'IGNORED',
+    #   'alternateUrl' => 'https://sandbox.google.com/api/adwords/v12/',
+    # }
+    # adwords = AdWords::API.new(AdWords::AdWordsCredentials.new(creds), 12)
+
+    adwords = AdWords::API.new
+
+    # Alternatively, you can create new AdWords::Campaign, AdWords::AdGroup,
+    # etc. objects and set their properties instead of working with hashes.
+    campaign_data = {
+      :name => 'Sample Campaign %s' % Time.new.to_s, # Ensure name is unique.
+      :budgetAmount => 1000000, # 1000000 micros = 1 unit of currency.
+      :budgetPeriod => 'Daily',
+      :languageTargeting => ['en'], # If the default all-language targeting is
+                                    # used then website placements criteria
+                                    # would not be supported.
+      :status => 'Paused', # Pause the campaign so that it doesn't actually run.
+      # Default geo and network targeting will be used.
+    }
+
+    campaign  = adwords.addCampaign(campaign_data).addCampaignReturn
+    puts 'Campaign id %d was successfully added.' % campaign.id
+
+    ad_group_data = {
+      :name => 'Sample Ad Group %s' % Time.new.to_s, # Ensure name is unique.
+      :keywordMaxCpc => 100000, # 100000 micros = 0.1 unit of currency.
+      :siteMaxCpc => 100000, # 100000 micros = 0.1 unit of currency.
+    }
+
+    ad_group = adwords.addAdGroup(campaign.id, ad_group_data).addAdGroupReturn
+    puts 'Ad group id %d was successfully added.' % ad_group.id
+
+    ad_data = {
+      :adGroupId => ad_group.id,
+      :adType => 'TextAd',
+      :headline => 'AdWords API Ruby Library',
+      :description1 => 'Write AdWords API apps in Ruby.',
+      :description2 => 'Use adwords4r!',
+      :destinationUrl => 'http://code.google.com/p/google-api-adwords-ruby/',
+      :displayUrl => 'http://code.google.com/',
+    }
+
+    ad = adwords.addAds([ad_data])[0]
+    puts 'Text ad id %d was successfully added.' % ad.id
+
+    keyword_data = {
+      :adGroupId => ad_group.id,
+      :criterionType => 'Keyword',
+      :text => 'adwords4r',
+      :type => 'Broad', # Or 'Phrase' or 'Exact' if desired.
+      # Default ad destination URL and ad group CPC values will be used.
+    }
+
+    website_data = {
+      :adGroupId => ad_group.id,
+      :criterionType => 'Website',
+      :url => 'http://www.ruby-forum.com/', # Target this site for ads.
+      # Default ad destination URL and ad group CPC values will be used.
+    }
+
+    criteria = adwords.addCriteria([keyword_data, website_data])
+    criteria.each do |criterion|
+      puts 'Criterion id %d was successfully added.' % criterion.id
+    end
+
+  rescue Errno::ECONNRESET, SOAP::HTTPStreamError, SocketError => e
+    # This exception indicates a connection-level error.
+    # In general, it is likely to be transitory.
+
+    puts 'Connection Error: %s' % e
+    puts 'Source: %s' % e.backtrace.first
+    
+  rescue AdWords::Error::UnknownAPICall => e
+    # This exception is thrown when an unknown SOAP method is invoked.
+
+    puts e
+    puts 'Source: %s' % e.backtrace.first
+    
+  rescue AdWords::Error::ApiError => e
+    # This exception maps to receiving a SOAP Fault back from the service.
+    # The e.soap_faultstring_ex, e.code_ex, and potentially e.trigger_ex
+    # attributes are the most useful, but other attributes may be populated
+    # as well. To display all attributes, the following can be used:
+    #
+    # e.instance_variables.each do |var|
+    #   value = e.instance_variable_get(var)
+    #   if ! value.nil?
+    #     puts '%s => %s' % [var, value]
+    #   end
+    # end
+
+    puts 'SOAP Error: %s (code: %d)' % [e.soap_faultstring_ex, e.code_ex]
+    puts 'Trigger: %s' % e.trigger_ex unless e.trigger_ex.nil?
+    puts 'Source: %s' % e.backtrace.first
+
+  ensure
+    # Display API unit usage info. This data is stored as a class variable
+    # in the AdWords::API class and accessed via static methods.
+    # AdWords::API.get_total_units() returns a running total of units used in
+    # the scope of the current program.
+    # AdWords::API.get_last_units() returns the number used in the last call.
+
+    puts
+    puts '%d API units consumed total (%d in last call).' %
+      [AdWords::API.get_total_units(), AdWords::API.get_last_units()]
+  end
+end
+
+
+if __FILE__ == $0
+  # The adwords4r library can log all SOAP requests and responses to files.
+  # This is often useful for debugging purposes.
+  # To enable this, set the ADWORDS4R_DEBUG environement varaible to 'true'.
+  # This can be done either from your operating system environment or via
+  # code, as done below.
+
+  ENV['ADWORDS4R_DEBUG'] = 'false'
+
+  main()
+end

data/examples/keyword_suggestions.rb

@@ -44,9 +44,9 @@ def main()
     #   'email' => 'user@domain.com',
     #   'clientEmail' => 'client_1+user@domain.com',
     #   'applicationToken' => 'IGNORED',
-    #   'alternateUrl' => 'https://sandbox.google.com/api/adwords/v11/',
+    #   'alternateUrl' => 'https://sandbox.google.com/api/adwords/v12/',
     # }
-    # adwords = AdWords::API.new(AdWords::AdWordsCredentials.new(creds), 11)
+    # adwords = AdWords::API.new(AdWords::AdWordsCredentials.new(creds), 12)
 
     adwords = AdWords::API.new
 

data/examples/reports.rb

@@ -44,9 +44,9 @@ def main()
     #   'email' => 'user@domain.com',
     #   'clientEmail' => 'client_1+user@domain.com',
     #   'applicationToken' => 'IGNORED',
-    #   'alternateUrl' => 'https://sandbox.google.com/api/adwords/v11/',
+    #   'alternateUrl' => 'https://sandbox.google.com/api/adwords/v12/',
     # }
-    # adwords = AdWords::API.new(AdWords::AdWordsCredentials.new(creds), 11)
+    # adwords = AdWords::API.new(AdWords::AdWordsCredentials.new(creds), 12)
 
     adwords = AdWords::API.new
     

data/lib/adwords4r/credentials.rb

@@ -3,6 +3,9 @@ require 'soap/header/simplehandler'
 module AdWords
 
   class HeaderHandler < SOAP::Header::SimpleHandler
+    attr_reader :tag
+    attr_writer :value
+
     def initialize(tag, value)
       super(XSD::QName.new(nil, tag))
       @tag = tag
@@ -41,5 +44,13 @@ module AdWords
         @handlers << HeaderHandler.new(key, value) if !(key =~ /^alternateUrl/)}
       @alternateUrl = credentials['alternateUrl']
     end
+
+    def setHeader(header, value)
+      handlers.each do |handler|
+        if handler.tag == header then
+          handler.value = value
+        end
+      end
+    end
   end
 end

data/lib/adwords4r/services.rb

@@ -2,8 +2,6 @@ module AdWords
   class Service
 
     @services = {
-      11 => ["Account", "AdGroup", "Ad", "Campaign", "Criterion", "Info",
-        "KeywordTool", "Report", "SiteSuggestion", "TrafficEstimator"],
       12 => ["Account", "AdGroup", "Ad", "Campaign", "Criterion", "Info",
         "KeywordTool", "Report", "SiteSuggestion", "TrafficEstimator"]
     }

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.9.4
 specification_version: 1
 name: adwords4r
 version: !ruby/object:Gem::Version 
-  version: 12.0.0
-date: 2008-04-08 00:00:00 -04:00
+  version: 12.1.0
+date: 2008-08-25 00:00:00 -04:00
 summary: Client library for the AdWords API.
 require_paths: 
 - lib
@@ -36,80 +36,44 @@ files:
 - Copying.txt
 - Readme.txt
 - adwords.properties
-- svn-commit.tmp
-- svn-commit.2.tmp
 - Rakefile
 - lib/adwords4r.rb
 - lib/adwords4r/credentials.rb
 - lib/adwords4r/services.rb
-- lib/adwords4r/v11/CriterionService.rb
-- lib/adwords4r/v11/CriterionServiceMappingRegistry.rb
-- lib/adwords4r/v11/CriterionServiceDriver.rb
-- lib/adwords4r/v11/AdGroupService.rb
-- lib/adwords4r/v11/AdGroupServiceMappingRegistry.rb
-- lib/adwords4r/v11/AdGroupServiceDriver.rb
-- lib/adwords4r/v11/CampaignService.rb
-- lib/adwords4r/v11/CampaignServiceMappingRegistry.rb
-- lib/adwords4r/v11/CampaignServiceDriver.rb
-- lib/adwords4r/v11/TrafficEstimatorService.rb
-- lib/adwords4r/v11/TrafficEstimatorServiceMappingRegistry.rb
-- lib/adwords4r/v11/TrafficEstimatorServiceDriver.rb
-- lib/adwords4r/v11/ReportService.rb
-- lib/adwords4r/v11/ReportServiceMappingRegistry.rb
-- lib/adwords4r/v11/ReportServiceDriver.rb
-- lib/adwords4r/v11/InfoService.rb
-- lib/adwords4r/v11/InfoServiceMappingRegistry.rb
-- lib/adwords4r/v11/InfoServiceDriver.rb
-- lib/adwords4r/v11/AccountService.rb
-- lib/adwords4r/v11/AccountServiceMappingRegistry.rb
-- lib/adwords4r/v11/AccountServiceDriver.rb
-- lib/adwords4r/v11/KeywordToolService.rb
-- lib/adwords4r/v11/KeywordToolServiceMappingRegistry.rb
-- lib/adwords4r/v11/KeywordToolServiceDriver.rb
-- lib/adwords4r/v11/AdService.rb
-- lib/adwords4r/v11/AdServiceMappingRegistry.rb
-- lib/adwords4r/v11/AdServiceDriver.rb
-- lib/adwords4r/v11/SiteSuggestionService.rb
-- lib/adwords4r/v11/SiteSuggestionServiceMappingRegistry.rb
-- lib/adwords4r/v11/SiteSuggestionServiceDriver.rb
 - lib/adwords4r/v12/AccountService.rb
+- lib/adwords4r/v12/CriterionService.rb
+- lib/adwords4r/v12/KeywordToolServiceDriver.rb
+- lib/adwords4r/v12/AdServiceDriver.rb
+- lib/adwords4r/v12/InfoServiceMappingRegistry.rb
 - lib/adwords4r/v12/AccountServiceMappingRegistry.rb
-- lib/adwords4r/v12/AccountServiceDriver.rb
 - lib/adwords4r/v12/AdGroupService.rb
+- lib/adwords4r/v12/CriterionServiceMappingRegistry.rb
 - lib/adwords4r/v12/AdGroupServiceMappingRegistry.rb
+- lib/adwords4r/v12/TrafficEstimatorService.rb
+- lib/adwords4r/v12/InfoServiceDriver.rb
+- lib/adwords4r/v12/AccountServiceDriver.rb
+- lib/adwords4r/v12/CriterionServiceDriver.rb
+- lib/adwords4r/v12/TrafficEstimatorServiceMappingRegistry.rb
+- lib/adwords4r/v12/ReportService.rb
+- lib/adwords4r/v12/SiteSuggestionService.rb
 - lib/adwords4r/v12/AdGroupServiceDriver.rb
-- lib/adwords4r/v12/AdService.rb
-- lib/adwords4r/v12/AdServiceMappingRegistry.rb
-- lib/adwords4r/v12/AdServiceDriver.rb
-- lib/adwords4r/v12/InfoService.rb
 - lib/adwords4r/v12/CampaignService.rb
-- lib/adwords4r/v12/CampaignServiceMappingRegistry.rb
-- lib/adwords4r/v12/CampaignServiceDriver.rb
-- lib/adwords4r/v12/CriterionService.rb
-- lib/adwords4r/v12/CriterionServiceMappingRegistry.rb
-- lib/adwords4r/v12/CriterionServiceDriver.rb
-- lib/adwords4r/v12/InfoServiceMappingRegistry.rb
-- lib/adwords4r/v12/InfoServiceDriver.rb
+- lib/adwords4r/v12/ReportServiceMappingRegistry.rb
+- lib/adwords4r/v12/SiteSuggestionServiceMappingRegistry.rb
 - lib/adwords4r/v12/KeywordToolService.rb
+- lib/adwords4r/v12/TrafficEstimatorServiceDriver.rb
+- lib/adwords4r/v12/AdService.rb
+- lib/adwords4r/v12/CampaignServiceMappingRegistry.rb
 - lib/adwords4r/v12/KeywordToolServiceMappingRegistry.rb
-- lib/adwords4r/v12/KeywordToolServiceDriver.rb
-- lib/adwords4r/v12/ReportService.rb
-- lib/adwords4r/v12/ReportServiceMappingRegistry.rb
 - lib/adwords4r/v12/ReportServiceDriver.rb
-- lib/adwords4r/v12/SiteSuggestionService.rb
-- lib/adwords4r/v12/SiteSuggestionServiceMappingRegistry.rb
 - lib/adwords4r/v12/SiteSuggestionServiceDriver.rb
-- lib/adwords4r/v12/TrafficEstimatorService.rb
-- lib/adwords4r/v12/TrafficEstimatorServiceMappingRegistry.rb
-- lib/adwords4r/v12/TrafficEstimatorServiceDriver.rb
+- lib/adwords4r/v12/AdServiceMappingRegistry.rb
+- lib/adwords4r/v12/CampaignServiceDriver.rb
+- lib/adwords4r/v12/InfoService.rb
 - examples/reports.rb
 - examples/keyword_suggestions.rb
-- examples/campaign.rb
-- examples/framework.rb
-- examples/get_free_usage_this_month.rb
-- examples/get_unit_count.rb
-- examples/keyword_tool_demo.rb
-- examples/traffic_estimator.rb
+- examples/account_info.rb
+- examples/create_all.rb
 test_files: []
 
 rdoc_options: []