adwords4r 11.1.0 → 12.0.0

data/ChangeLog.txt

@@ -1,3 +1,7 @@
+12.0.0
+- Added support for v12 of the AdWords API.
+  Removed support for v10 of the API, which has been deco'ed.
+
 11.1.0
 - Added additional attributes to the AdWords::Error::ApiError class.
   This should make it easier to get all the useful SOAP fault information, some of which wasn't available in the previous version.

data/Rakefile

@@ -16,7 +16,7 @@ require 'lib/adwords4r/services'
 
 CLOBBER.include('pkg')
 
-CURRENT_VERSION = '11.1.0'
+CURRENT_VERSION = '12.0.0'
 PKG_VERSION = ENV['REL'] ? ENV['REL'] : CURRENT_VERSION
 
 SRC_RB = FileList['lib/**/*.rb']
@@ -29,8 +29,8 @@ logger = Logger.new(STDERR)
 
 CLEAN.include(WSDLDIR)
 AdWords::Service.getVersions.each do |v|
-    vname = "v#{v}"
-    CLEAN.include(File.join(GENDIR, vname))
+  vname = "v#{v}"
+  CLEAN.include(File.join(GENDIR, vname))
 end
 
 desc "gets the wsdl and generates the classes"
@@ -38,73 +38,77 @@ task :default => [:getwsdl, :generate]
 
 desc "gets the wsdl files for AdWords services"
 task :getwsdl do
-    AdWords::Service.getVersions.each do |v|
-        vname = "v#{v}"
-        mkdir_p File.join(WSDLDIR, vname)
-        AdWords::Service.getServices(v).each {|s| save(getfile("adwords.google.com", "/api/adwords/#{vname}/#{s}Service?wsdl"), getWsdlFileName(vname,s))}
-    end
+  AdWords::Service.getVersions.each do |v|
+    vname = "v#{v}"
+    mkdir_p File.join(WSDLDIR, vname)
+    AdWords::Service.getServices(v).each {|s|
+      save(getfile("adwords.google.com",
+		   "/api/adwords/#{vname}/#{s}Service?wsdl"),
+           getWsdlFileName(vname,s))}
+  end
 end
 
 desc "generates AdWords classes from the wsdl files"
 task :generate do
-    AdWords::Service.getVersions.each do |v|
-        vname = "v#{v}"
-        gendir = "#{LIBDIR}/adwords4r/#{vname}"
-        mkdir_p gendir
-        AdWords::Service.getServices(v).each do |name|
-            worker = WSDL::SOAP::WSDL2Ruby.new
-            worker.logger = logger
-            worker.location = getWsdlFileName(vname,name)
-            worker.basedir = gendir
-            worker.opt.update(getWsdlOpt(name))
-            worker.run
-            fixImport(v, File.join(gendir, "#{name}Driver.rb"))
-            fixImport(v, File.join(gendir, "#{name}MappingRegistry.rb"))
-            fixImport(v, File.join(gendir, "#{name}.rb"))
-        end
+  AdWords::Service.getVersions.each do |v|
+    vname = "v#{v}"
+    gendir = "#{LIBDIR}/adwords4r/#{vname}"
+    mkdir_p gendir
+    AdWords::Service.getServices(v).each do |name|
+      worker = WSDL::SOAP::WSDL2Ruby.new
+      worker.logger = logger
+      worker.location = getWsdlFileName(vname,name)
+      worker.basedir = gendir
+      worker.opt.update(getWsdlOpt(name))
+      worker.run
+      fixImport(v, File.join(gendir, "#{name}Driver.rb"))
+      fixImport(v, File.join(gendir, "#{name}MappingRegistry.rb"))
+      fixImport(v, File.join(gendir, "#{name}.rb"))
     end
+  end
 end
 
 def fixImport(version, file)
-    vname = "v#{version}"
-    tempfile = file + '.tmp'
-    outfile = File.new(tempfile,"w")
-    File.open(file, "r") do |infile|
-        infile.each do |l|
-            if (l =~ /require.*Service.*\.rb/) then
-                outfile.puts l.gsub(/require '(.*)Service(.*)\.rb'/, "require 'adwords4r/#{vname}/\\1Service\\2'")
-            else
-                outfile.puts l
-            end
-        end
+  vname = "v#{version}"
+  tempfile = file + '.tmp'
+  outfile = File.new(tempfile,"w")
+  File.open(file, "r") do |infile|
+    infile.each do |l|
+      if (l =~ /require.*Service.*\.rb/) then
+        outfile.puts l.gsub(/require '(.*)Service(.*)\.rb'/,
+                            "require 'adwords4r/#{vname}/\\1Service\\2'")
+      else
+        outfile.puts l
+      end
     end
-    outfile.close
-    File.rename(tempfile, file)
+  end
+  outfile.close
+  File.rename(tempfile, file)
 end 
 
 def getWsdlOpt(s)
-    optcmd= {}
-    s << "Service"
-    optcmd['classdef'] = s
-    optcmd['force'] = true
-    optcmd['mapping_registry'] = true
-    optcmd['driver'] = nil
-
-    # Causes soap4r to wrap the classes it outputs into the given modules
-    optcmd['module_path'] = ['AdWords', s]
-    return optcmd
-end
+  optcmd= {}
+  s << "Service"
+  optcmd['classdef'] = s
+  optcmd['force'] = true
+  optcmd['mapping_registry'] = true
+  optcmd['driver'] = nil
   
+  # Causes soap4r to wrap the classes it outputs into the given modules
+  optcmd['module_path'] = ['AdWords', s]
+  return optcmd
+end
+
 def getWsdlFileName(v,s)
-    "#{WSDLDIR}/#{v}/#{s}.wsdl"
+  "#{WSDLDIR}/#{v}/#{s}.wsdl"
 end
-     
+
 def getfile(host, path)
-    puts "getting https//#{host}#{path}"
-    https = Net::HTTP.new(host, 443)
-    https.use_ssl = true
-    https.verify_mode = OpenSSL::SSL::VERIFY_NONE
-    https.start { |w| w.get2(path).body }
+  puts "getting https//#{host}#{path}"
+  https = Net::HTTP.new(host, 443)
+  https.use_ssl = true
+  https.verify_mode = OpenSSL::SSL::VERIFY_NONE
+  https.start { |w| w.get2(path).body }
 end
 
 def fix_attribute(text, name, type)
@@ -112,21 +116,23 @@ def fix_attribute(text, name, type)
 end
 
 def fixWsdl(wsdl)
-    ['type', 'base'].each {|name| ['long', 'string', 'date', 'int', 'boolean'].each {|type| fix_attribute(wsdl, name, type)}}
-    schema_ns = "xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\""
-    if wsdl !~ Regexp.new(schema_ns)
-        wsdl.gsub!(/(<wsdl:definitions[^>]*)>/, '\1 ' + schema_ns + '>')
-    end
-    return wsdl
-    #wsdl.gsub(/type=\"long\"/, 'type="xsd:long"')
+  ['type', 'base'].each {|name| 
+    ['long', 'string', 'date', 'int', 'boolean'].each {|type|
+      fix_attribute(wsdl, name, type)}}
+  schema_ns = "xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\""
+  if wsdl !~ Regexp.new(schema_ns)
+    wsdl.gsub!(/(<wsdl:definitions[^>]*)>/, '\1 ' + schema_ns + '>')
+  end
+  return wsdl
+  #wsdl.gsub(/type=\"long\"/, 'type="xsd:long"')
 end
 
 # Saves this document to the specified @var path.
 #doesn't create the file if contains markup for google 404 page
 def save(content, path)
-    if content !~ /<H2>Error 404<\/H2>/
-        File::open(path, 'w') {|f| f.write(fixWsdl(content))}
-    end
+  if content !~ /<H2>Error 404<\/H2>/
+    File::open(path, 'w') {|f| f.write(fixWsdl(content))}
+  end
 end
 
 # ====================================================================
@@ -138,7 +144,7 @@ PKG_FILES = FileList[
   'Rakefile', 
   'lib/**/*.rb', 
   'examples/**/*.rb', 
-#  'test/**/*.rb',
+  #  'test/**/*.rb',
   'scripts/**/*.rb'
 ]
 
@@ -152,7 +158,7 @@ else
   spec = Gem::Specification.new do |s|
     
     #### Basic information.
-
+    
     s.name = 'adwords4r'
     s.version = PKG_VERSION
     s.summary = "Client library for the AdWords API."
@@ -163,7 +169,7 @@ Currently the following AdWords API versions are supported:\
 * V10\
 * V11\
 }
-
+    
     s.files = PKG_FILES.to_a
     s.require_path = 'lib'
     s.autorequire = 'adwords4r'
@@ -174,9 +180,9 @@ Currently the following AdWords API versions are supported:\
     s.has_rdoc = false
     #s.extra_rdoc_files = rd.rdoc_files.reject { |fn| fn =~ /\.rb$/ }.to_a
     #s.rdoc_options <<
-#      '--title' <<  'Builder -- Easy XML Building' <<
-#      '--main' << 'README' <<
-#      '--line-numbers'
+    #      '--title' <<  'Builder -- Easy XML Building' <<
+    #      '--main' << 'README' <<
+    #      '--line-numbers'
     
     s.author = "Jeffrey Posnick, Patrick Chanezon, Ryan Leavengood"
     s.email = "jeffy@google.com"

data/examples/campaign.rb

@@ -0,0 +1,40 @@
+#!/usr/bin/env ruby
+
+# Use adwords4r in parent dir
+$LOAD_PATH.unshift '../lib/'
+
+require 'adwords4r'
+
+SEP = "---"
+
+def dumpObj(o)
+  str = ""
+  o.instance_variables.each { |v| str << dumpAttr(o, v)}
+  return str << SEP
+end
+
+def dumpAttr(o, v)
+  name = v.sub(/@/,'')
+  value = eval("o.#{name}.to_s")
+  return "#{name}: #{value}\n"
+end
+
+begin
+  adwords = AdWords::API.new
+  
+  res = adwords.getAllAdWordsCampaigns(123).getAllAdWordsCampaignsReturn
+  res.each {|c| puts dumpObj(c)}
+  
+  c = AdWords::Campaign.new
+  c.dailyBudget = 10000
+  c.status = 'Paused'
+  c.name = "Test Campaign #{rand(10000)}"
+  c.endDay = SOAP::SOAPDate.new("2010-01-01")
+  puts dumpObj(adwords.addCampaign(c).addCampaignReturn)
+  
+rescue AdWords::Error::UnknownAPICall => e
+  puts e
+rescue AdWords::Error::ApiError => e
+  puts e.code
+  puts e.message
+end

data/examples/{old/get_free_usage_this_month.rb → get_free_usage_this_month.rb}

@@ -6,13 +6,15 @@ $LOAD_PATH.unshift '../lib/'
 require 'adwords4r'
 
 begin
-    adwords = AdWords::API.new
-    puts "result = #{adwords.getFreeUsageQuotaThisMonth().getFreeUsageQuotaThisMonthReturn}"
-
+  adwords = AdWords::API.new
+  result = adwords.getFreeUsageQuotaThisMonth().
+    getFreeUsageQuotaThisMonthReturn
+  puts "result = #{result}"
+  
 rescue AdWords::Error::UnknownAPICall => e
-    puts e
+  puts e
 rescue AdWords::Error::ApiError => e
-    puts e.code
-    puts e.message
+  puts e.code
+  puts e.message
 end
 

data/examples/get_unit_count.rb

@@ -0,0 +1,21 @@
+#!/usr/bin/env ruby
+
+# Use adwords4r in parent dir
+$LOAD_PATH.unshift '../lib/'
+
+require 'adwords4r'
+
+begin
+  adwords = AdWords::API.new
+  # Get the units for the last month or so
+  end = Date.today
+  start = end_date - 31
+  puts "result = #{adwords.getUnitCount(start, end).getUnitCountReturn}"
+  
+rescue AdWords::Error::UnknownAPICall => e
+  puts e
+rescue AdWords::Error::ApiError => e
+  puts e.code
+  puts e.message
+end
+

data/examples/keyword_suggestions.rb

@@ -0,0 +1,179 @@
+#!/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 get keyword variations for seed keyword(s)
+# and then estimate the traffic that the "top" variations might receive.
+
+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/v11/',
+    # }
+    # adwords = AdWords::API.new(AdWords::AdWordsCredentials.new(creds), 11)
+
+    adwords = AdWords::API.new
+
+    # Modify the following values to set the seed keywords, language,
+    # country targeting, and synonyms options.
+
+    keywords = ['hot dog']
+    languages = %w{en}
+    countries = %w{US}
+    use_synonyms = false
+
+    seed_keywords = []
+    keywords.each do |keyword|
+      seed_keyword = AdWords::KeywordToolService::SeedKeyword.new
+      seed_keyword.text = keyword
+      seed_keyword.type = 'Broad'  # Or 'Phrase' or 'Exact' if desired.
+      seed_keywords << seed_keyword
+    end
+
+    variations = adwords.getKeywordVariations(seed_keywords, use_synonyms,
+					      languages, countries
+					      ).getKeywordVariationsReturn
+
+    variation_objects = []
+    unless variations.moreSpecific.nil?
+      variation_objects.concat(variations.moreSpecific)
+    end
+    unless variations.additionalToConsider.nil?
+      variation_objects.concat(variations.additionalToConsider)
+    end
+    variation_objects.sort! do |a, b|
+      if b.searchVolumeScale == a.searchVolumeScale
+	a.advertiserCompetitionScale <=> b.advertiserCompetitionScale
+      else
+	b.searchVolumeScale <=> a.searchVolumeScale
+      end
+    end
+
+    max_estimates = 3
+    keywords_to_estimate = []
+    variation_objects[0..max_estimates - 1].each do |variation_object|
+      keywords_to_estimate << variation_object.text
+    end
+
+    ad_group_request = AdWords::TrafficEstimatorService::AdGroupRequest.new
+    ad_group_request.maxCpc = 1000000
+    keywords_to_estimate.each do |keyword_to_estimate|
+      keyword_request = AdWords::TrafficEstimatorService::KeywordRequest.new
+      keyword_request.text = keyword_to_estimate
+      keyword_request.type = 'Broad'  # Or 'Phrase' or 'Exact' if desired.
+      ad_group_request.keywordRequests << keyword_request
+    end
+
+    geo_targeting = AdWords::TrafficEstimatorService::GeoTarget.new
+    geo_targeting.countryTargets = countries
+
+    campaign_request = AdWords::TrafficEstimatorService::CampaignRequest.new
+    campaign_request.adGroupRequests = ad_group_request
+    campaign_request.geoTargeting = geo_targeting
+    campaign_request.languageTargeting = languages
+    campaign_request.networkTargeting = %w{SearchNetwork ContentNetwork}
+
+    campaign_estimate = adwords.estimateCampaignList([campaign_request]).first
+    ad_group_estimate = campaign_estimate.adGroupEstimates.first
+    keyword_estimates = ad_group_estimate.keywordEstimates
+    for i in 0..keyword_estimates.length - 1
+      estimate = keyword_estimates[i]
+      text = keywords_to_estimate[i]
+
+      puts "Keyword: %s\tClicks: %f - %f\tCPC: %d - %d\tPosition: %f - %f" %
+	[text, estimate.lowerClicksPerDay, estimate.upperClicksPerDay,
+	estimate.lowerCpc, estimate.upperCpc, estimate.lowerAvgPosition,
+	estimate.upperAvgPosition]
+    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