adapi 0.0.3 → 0.0.4

data/examples/log_to_specific_account.rb

@@ -1,3 +1,4 @@
+# encoding: utf-8
 
 require 'adapi'
 

data/examples/rollback_campaign.rb

@@ -1,3 +1,4 @@
+# encoding: utf-8
 
 require 'adapi'
 

data/lib/adapi.rb

@@ -1,7 +1,7 @@
+# encoding: utf-8
 
 require 'rubygems'
 require 'adwords_api'
-require 'collection'
 require 'yaml'
 require 'pp'
 
@@ -27,10 +27,13 @@ HTTPI.adapter = :curb
 # supress HTTPI output
 # HTTPI.log = false
 
-# load factories for development environment
-# require 'factory_girl'
-# Dir[ File.join(File.dirname(__FILE__), '../test/factories/*.rb') ].each { |f| require f }
-
 module Adapi
   API_VERSION = :v201101  
 end
+
+# check ruby version, should be 1.9
+# FIXME there's gotta be more elegant way to do this
+`ruby -v`.to_s =~ /^ruby (\d\.\d)\./
+if $1.to_f < 1.9
+  puts "WARNING: please use ruby 1.9, adapi gem won't work properly in 1.8 and earlier versions"
+end

data/lib/adapi/ad.rb

@@ -1,3 +1,5 @@
+# encoding: utf-8
+
 module Adapi
 
   # Ad == AdGroupAd

data/lib/adapi/ad/text_ad.rb

@@ -1,3 +1,5 @@
+# encoding: utf-8
+
 module Adapi
   # Ad::TextAd == AdGroupAd::TextAd
   #
@@ -122,5 +124,18 @@ module Adapi
       first_only ? response.first : response
     end
 
+    # Converts text ad data to hash - of the same structure which is used when
+    # creating a complete campaign.
+    #
+    def to_hash
+      {
+        :headline => self[:headline],
+        :description1 => self[:description1],
+        :description2 => self[:description2],
+        :url => self[:url],
+        :display_url => self[:display_url]
+      }
+    end
+
   end
 end

data/lib/adapi/ad_group.rb

@@ -1,3 +1,5 @@
+# encoding: utf-8
+
 module Adapi
   class AdGroup < Api
   
@@ -19,6 +21,25 @@ module Adapi
         self.send "#{param_name}=", params[param_name.to_sym]
       end
 
+      # convert bids to GoogleApi format
+      #
+      # can be either string (just xsi_type) or hash (xsi_type with params)
+      # althogh I'm not sure if just string makes sense in this case
+      #
+      if @bids
+        unless @bids.is_a?(Hash)
+          @bids = { :xsi_type => @bids }
+        end
+  
+        if @bids[:keyword_max_cpc] and not @bids[:keyword_max_cpc].is_a?(Hash)
+          @bids[:keyword_max_cpc] = {
+            :amount => {
+              :micro_amount => Api.to_micro_units(@bids[:keyword_max_cpc])
+            }
+          }
+        end
+      end
+
       @keywords ||= []
       @ads ||= []
 
@@ -71,7 +92,7 @@ module Adapi
       params.symbolize_keys!
       first_only = (amount.to_sym == :first)
 
-      raise "No Campaign ID is required" unless params[:campaign_id]
+      raise "Campaign ID is required" unless params[:campaign_id]
 
       predicates = [ :campaign_id, :id ].map do |param_name|
         if params[param_name]
@@ -87,22 +108,40 @@ module Adapi
 
       response = AdGroup.new.service.get(selector)
 
-      response = (response and response[:entries]) ? response[:entries] : []
+      ad_groups = (response and response[:entries]) ? response[:entries] : []
 
-      #response.map! do |data|
-      #  TextAd.new(data[:ad].merge(:ad_group_id => data[:ad_group_id], :status => data[:status]))
-      #end
+      ad_groups = ad_groups.slice(0,1) if first_only
 
-      first_only ? response.first : response
+      # find keywords and ads
+      ad_groups.map! do |ad_group|
+        ad_group.merge(
+          :keywords => Keyword.shortened(Keyword.find(:all, :ad_group_id => ad_group[:id]).keywords),
+          :ads => Ad::TextAd.find(:all, :ad_group_id => ad_group[:id]).map(&:to_hash) 
+        )
+      end
+
+      first_only ? ad_groups.first : ad_groups
     end
 
     def find_keywords(first_only = false)
       Keyword.find( (first_only ? :first : :all), :ad_group_id => self.id )
     end
 
+    # TODO find all types of ads
     def find_ads(first_only = false)
       Ad::TextAd.find( (first_only ? :first : :all), :ad_group_id => self.id )
     end
 
+    # Converts ad group data to hash - of the same structure which is used when
+    # creating an ad group.
+    #
+    def to_hash
+      ad_group_hash = {
+        :id => self[:id],
+        :name => self[:name],
+        :status => self[:status]
+      }
+    end
+
   end
 end

data/lib/adapi/ad_group_criterion.rb

@@ -1,3 +1,5 @@
+# encoding: utf-8
+
 module Adapi
 
   # http://code.google.com/apis/adwords/docs/reference/latest/AdGroupCriterionService.html
@@ -22,5 +24,17 @@ module Adapi
       super(params)
     end
 
+    def delete(criterion_id)
+      response = self.mutate(
+        :operator => 'REMOVE',
+        :operand => {
+          :ad_group_id => self.ad_group_id,
+          :criterion => { :id => criterion_id.to_i }
+        }
+      )
+
+      (response and response[:value])
+    end
+
   end
 end

data/lib/adapi/api.rb

@@ -1,3 +1,5 @@
+# encoding: utf-8
+
 module Adapi
   class Api
     extend ActiveModel::Naming
@@ -28,6 +30,10 @@ module Adapi
       @params = params
     end
 
+    def to_param
+      self[:id]
+    end
+
     def persisted?
       false
     end

data/lib/adapi/campaign.rb

@@ -1,3 +1,5 @@
+# encoding: utf-8
+
 module Adapi
   class Campaign < Api
 
@@ -34,7 +36,7 @@ module Adapi
         @bidding_strategy = { :xsi_type => @bidding_strategy }
       end
 
-      if @bidding_strategy[:bid_ceiling]
+      if @bidding_strategy[:bid_ceiling] and not @bidding_strategy[:bid_ceiling].is_a?(Hash)
         @bidding_strategy[:bid_ceiling] = {
           :micro_amount => Api.to_micro_units(@bidding_strategy[:bid_ceiling])
         }
@@ -46,7 +48,9 @@ module Adapi
       # budget can be integer (amount) or hash
       @budget = { :amount => @budget } unless @budget.is_a?(Hash)
       @budget[:period] ||= 'DAILY'
-      @budget[:amount] = { :micro_amount => Api.to_micro_units(@budget[:amount]) }
+      if @budget[:amount] and not @budget[:amount].is_a?(Hash)
+        @budget[:amount] = { :micro_amount => Api.to_micro_units(@budget[:amount]) }
+      end
       # PS: not sure if this should be a default. maybe we don't even need it
       @budget[:delivery_method] ||= 'STANDARD'
 
@@ -150,12 +154,20 @@ module Adapi
       Campaign.find(:first, :id => @id)
     end
 
+
+    # if nothing else than single number or string at the input, assume it's an
+    # id and we want to find campaign by id
+    #
     def self.find(amount = :all, params = {})
+      # find campaign by id - related syntactic sugar
+      if params.empty? and not amount.is_a?(Symbol)
+        params[:id] = amount.to_i
+        amount = :first
+      end
+
       params.symbolize_keys!
       first_only = (amount.to_sym == :first)
 
-      raise "Campaign ID (:id param) is required" unless params[:id]
-
       predicates = [ :id ].map do |param_name|
         if params[param_name]
           {:field => param_name.to_s.camelcase, :operator => 'EQUALS', :values => params[param_name] }
@@ -165,7 +177,7 @@ module Adapi
       # TODO display the rest of the data
       # TODO get NetworkSetting - setting as in fields doesn't work
       selector = {
-        :fields => ['Id', 'Name', 'Status', 'BiddingStrategy' ],
+        :fields => ['Id', 'Name', 'Status', 'BiddingStrategy'],
         :ordering => [{:field => 'Name', :sort_order => 'ASCENDING'}],
         :predicates => predicates
       }
@@ -188,5 +200,36 @@ module Adapi
       AdGroup.find( (first_only ? :first : :all), :campaign_id => self.id )
     end
 
+    # Returns complete campaign data: targets, ad groups, keywords and ads.
+    # Basically everything what you can set when creating a campaign.
+    #
+    def self.find_complete(campaign_id)
+      campaign = self.find(campaign_id)
+      
+      campaign[:targets] = CampaignTarget.find(:campaign_id => campaign.to_param)
+
+      campaign[:ad_groups] = AdGroup.find(:all, :campaign_id => campaign.to_param)
+
+      campaign
+    end
+
+    # Converts campaign data to hash - of the same structure which is used when
+    # creating a campaign.
+    #
+    # PS: could be implemented more succintly, but let's leave it like this for
+    # now, code can change and this is more readable
+    #
+    def to_hash
+      {
+        :id => self[:id],
+        :name => self[:name],
+        :status => self[:status],
+        :budget => self[:budget],
+        :bidding_strategy => self[:bidding_strategy],
+        :targets => self[:targets],
+        :ad_groups => self[:ad_groups]
+      }
+    end
+
   end
 end

data/lib/adapi/campaign_target.rb

@@ -1,3 +1,5 @@
+# encoding: utf-8
+
 module Adapi
 
   # http://code.google.com/apis/adwords/docs/reference/latest/CampaignTargetService.html
@@ -48,12 +50,15 @@ module Adapi
   
     alias :create :set
 
-    # FIXME doesn't display everything, check the issues in google-adwords-api
-    #
-    def self.find(amount = :all, params = {})
+    def self.find(params = {})
       params.symbolize_keys!
-      params = params[:conditions] if params[:conditions]
-      first_only = (amount.to_sym == :first)
+
+      # by default, return skip target types that have no target data
+      params[:skip_empty_target_types] ||= true
+      
+      if params[:conditions]
+        params[:campaign_id] = params[:campaign_id] || params[:conditions][:campaign_id]
+      end
 
       raise ArgumentError, "Campaing ID is required" unless params[:campaign_id]
   
@@ -63,15 +68,59 @@ module Adapi
 
       response = (response and response[:entries]) ? response[:entries] : []
 
-      first_only ? response.first : response
+      # return everything or only 
+      if params[:skip_empty_target_types]
+        response.select! { |target_type| target_type.has_key?(:targets) }
+      end
+
+      # TODO optionally return just certain target type(s)
+      # easy, just add condition (single type or array), filter and set
+      # :skip_empty_target_types option to false
+      
+      # optionally convert to original input shortcuts specified by Adapi DSL
+      # TODO on second thought, no need to do that now. it's simpler to make
+      # CampaignTarget.new accept original AdWords data
+      # if params[:format] == :adapi_dsl
+      #   response = Hash[ response.map { |t| CampaignTarget.parse_dsl(t) } ]
+      # end
+
+      response
     end
 
+=begin TODO
+    def self.parse_dsl(target)
+      case target[:target_list_type]
+      when "LanguageTargetList"
+        [ :language, target[:targets].map { |t| t[:language_code] } ]
+      when "GeoTargetList"
+        targets = Hash[ target[:targets].map do |t|
+          target_type = t[:target_type].gsub(/Target$/, '')
+
+          case target_type
+          when :proximity
+            [ target_type, { :geo_point => '', :radius => '' } ]
+          when :city
+          else
+            [ target_type, t ]
+          end          
+        end ]
+
+        [ :geo, targets ]
+      else
+        warn "Unsupported target type! %s" % target.inspect
+        [ target[:target_list_type], target[:targets] ] 
+      end
+    end
+=end
+
     # transform our own high-level target parameters to google low-level
+    # 
+    # TODO allow to enter AdWords parameters in original format
     #
     def self.create_targets(target_type, target_data)
       case target_type
         when :language
-          target_data.map { |language| { :language_code => language } }       
+          target_data.map { |language| { :language_code => language.to_s.downcase } }       
           # example: ['cz','sk'] => [{:language_code => 'cz'}, {:language_code => 'sk'}]
         when :geo
           target_data.map do |geo_type, geo_values|
@@ -101,7 +150,7 @@ module Adapi
                 {
                   :xsi_type => "#{geo_type.to_s.capitalize}Target",
                   :excluded => false,
-                  "#{geo_type}_code".to_sym => geo_values
+                  "#{geo_type}_code".to_sym => to_uppercase(geo_values)
                 }
             end
           end
@@ -134,5 +183,15 @@ module Adapi
       Api.to_micro_units(x)
     end
 
+    # convert either single value or array of value to uppercase
+    # 
+    def self.to_uppercase(values)
+      if values.is_a?(Array)
+        values.map { |value| value.to_s.upcase }
+      else
+        values.to_s.upcase
+      end
+    end
+
   end
 end

data/lib/adapi/config.rb

@@ -1,3 +1,4 @@
+# encoding: utf-8
 
 # PS: what about this config setting?
 # Campaign.create(:data => campaign_data, :account => :my_account_alias)

data/lib/adapi/keyword.rb

@@ -1,3 +1,20 @@
+# encoding: utf-8
+
+# TODO user should be able to delete keywords
+# TODO user should not see deleted keywords by default
+#
+# TODO program should be able to detect keywords in shortened or Google form
+# automatically on input (outsource into separate method?)
+#
+# TODO user should be able to enter keywords in both shortened, parameterized and Google form
+# 
+# FIXME broken Keyword.negative param 
+
+# Currently the Keyword DSL is a mess. There are basically three forms:
+# * ultra short form on input: keyword example
+# * shortened form: {:text=>"keyword example", :match_type=>"BROAD", :negative=>false} 
+# * google form
+
 module Adapi
   class Keyword < AdGroupCriterion
 
@@ -22,22 +39,22 @@ module Adapi
       super(params)
     end
 
-    # TODO include formatting in create method
+    # Converts keyword specification from shortened form to Google format
     #
     def self.keyword_attributes(keyword)
       # detect match type
       match_type = case keyword[0]
-        when '"'
-          keyword = keyword.slice(1, (keyword.size - 2))
-          'PHRASE'
-        when '['
-          keyword = keyword.slice(1, (keyword.size - 2))
-          'EXACT'
-        else
-          'BROAD'
+      when '"'
+        keyword = keyword.slice(1, (keyword.size - 2))
+        'PHRASE'
+      when '['
+        keyword = keyword.slice(1, (keyword.size - 2))
+        'EXACT'
+      else
+        'BROAD'
       end
 
-      # detect if keyword is negative
+      # sets whether keyword is negative or not
       negative = if (keyword =~ /^\-/)
         keyword.slice!(0, 1)
         true
@@ -74,6 +91,8 @@ module Adapi
     end
 
     def self.find(amount = :all, params = {})
+      params[:format] ||= :google # default, don't do anything with the data from google
+      
       params.symbolize_keys!
       # this has no effect, it's here just to have the same interface everywhere
       first_only = (amount.to_sym == :first)
@@ -99,11 +118,59 @@ module Adapi
 
       response = (response and response[:entries]) ? response[:entries] : []
 
+# for now, always return keywords in :google format
+=begin
+      response = case params[:format].to_sym
+      when :short
+        Keyword.shortened(response)
+      when :params
+        Keyword.parameterized(response)
+      else
+        response
+      end
+=end
+
       Keyword.new(
         :ad_group_id => params[:ad_group_id],
-        :keywords => response.map { |keyword| keyword[:criterion] }
+        :keywords => response
       )
     end
 
+    # PS: create a better UI for this?
+    # Keyword.convert(:to => :params, :source => $google_keywords)
+    # and Keyword.parametrized($google_keywords) just calling that?
+
+    # Converts list of keywords from Google format to short format
+    #
+    def self.shortened(google_keywords = [])
+      self.parameterized(google_keywords).map do |keyword|
+        keyword[:text] = "-%s" % keyword[:text] if keyword[:negative]
+        
+        case keyword[:match_type]
+        when 'PHRASE'
+          "\"%s\"" % keyword[:text]
+        when 'EXACT'
+          "[%s]" % keyword[:text]
+        else # 'BROAD'
+          keyword[:text]
+        end
+      end
+    end
+
+    # Converts list of keywords from Google format to params format
+    # (the way it can be entered into Keywords model)
+    # 
+    def self.parameterized(google_keywords = [])
+      google_keywords.map do |keyword|        
+        kw = keyword[:text][:criterion]
+        
+        {
+          :text => kw[:text],
+          :match_type => kw[:match_type],
+          :negative => (keyword[:text][:xsi_type] == "NegativeAdGroupCriterion")
+        }
+      end
+    end
+
   end
 end