adapi 0.0.4 → 0.0.5

data/lib/adapi/api.rb

@@ -28,6 +28,14 @@ module Adapi
       @version = API_VERSION
       @service = @adwords.service(params[:service_name].to_sym, @version)
       @params = params
+
+      # TODO add switched for logging (true/false) and log location
+      log_level = Adapi::Config.read[:library][:log_level] rescue nil
+      if log_level
+        logger = Logger.new( File.join(ENV['HOME'], (params[:logfile] || 'adapi.log')) )
+        logger.level = eval("Logger::%s" % Adapi::Config.read[:library][:log_level].to_s.upcase)
+        @adwords.logger = logger
+      end
     end
 
     def to_param

data/lib/adapi/campaign.rb

@@ -6,12 +6,12 @@ module Adapi
     # http://code.google.com/apis/adwords/docs/reference/latest/CampaignService.Campaign.html
     #
     attr_accessor :name, :serving_status, :start_date, :end_date, :budget,
-      :bidding_strategy, :network_setting, :targets, :ad_groups
+      :bidding_strategy, :network_setting, :criteria, :ad_groups
 
     def attributes
       super.merge('name' => name, 'start_date' => start_date, 'end_date' => end_date,
         'budget' => budget, 'bidding_strategy' => bidding_strategy,
-        'network_setting' => network_setting, 'targets' => targets,
+        'network_setting' => network_setting, 'criteria' => criteria,
         'ad_groups' => ad_groups)
     end
 
@@ -24,7 +24,7 @@ module Adapi
       @xsi_type = 'Campaign'
 
       %w{ name status start_date end_date budget bidding_strategy
-      network_setting targets ad_groups}.each do |param_name|
+      network_setting criteria ad_groups}.each do |param_name|
         self.send "#{param_name}=", params[param_name.to_sym]
       end
 
@@ -54,7 +54,7 @@ module Adapi
       # PS: not sure if this should be a default. maybe we don't even need it
       @budget[:delivery_method] ||= 'STANDARD'
 
-      @targets ||= []
+      @criteria ||=  []
       @ad_groups ||= []
 
       super(params)
@@ -81,15 +81,15 @@ module Adapi
       
       self.id = response[:value].first[:id] rescue nil
       
-      # create targets if they are available
-      if targets.size > 0
-        target = Adapi::CampaignTarget.create(
+      # create criteria (former targets) if they are available
+      if criteria.size > 0
+        criterion = Adapi::CampaignCriterion.create(
           :campaign_id => @id,
-          :targets => targets
+          :criteria => criteria
         )
         
-        if (target.errors.size > 0)
-          self.errors.add("[campaign target]", target.errors.to_a)
+        if (criterion.errors.size > 0)
+          self.errors.add("[campaign criterion]", criterion.errors.to_a)
           self.rollback
           return false 
         end
@@ -116,9 +116,8 @@ module Adapi
     # TODO implement class method
     # 
     def update(params = {})
-      # TODO validation or refuse to update
-
-      response = self.mutate(
+      # HOTFIX can't use current instance, gotta create new one
+      response = Adapi::Campaign.new().mutate(
         :operator => 'SET', 
         :operand => params.merge(:id => @id)
       )
@@ -128,16 +127,24 @@ module Adapi
       # faster than self.find
       params.each_pair { |k,v| self.send("#{k}=", v) }
 
-      true      
+      true
     end
 
     def activate; update(:status => 'ACTIVE'); end
     def pause; update(:status => 'PAUSED'); end
+
+    # Deletes campaign - which means, sets its status to deleted (because
+    # AdWords campaigns are never really deleted.)
+    #
     def delete; update(:status => 'DELETED'); end
 
     def rename(new_name); update(:name => new_name); end
 
     # when Campaign#create fails, "delete" campaign
+
+    # Deletes campaign if it's not already deleted. For more information about
+    # "deleted" campaigns, see `delete` method
+    #
     def rollback
       if (@status == 'DELETED')
         self.errors.add(:base, 'Campaign is already deleted.')
@@ -170,7 +177,9 @@ module Adapi
 
       predicates = [ :id ].map do |param_name|
         if params[param_name]
-          {:field => param_name.to_s.camelcase, :operator => 'EQUALS', :values => params[param_name] }
+          # convert to array
+          value = Array.try_convert(params[param_name]) ? params_param_name : [params[param_name]]
+          {:field => param_name.to_s.camelcase, :operator => 'IN', :values => value }
         end
       end.compact
 
@@ -200,13 +209,13 @@ module Adapi
       AdGroup.find( (first_only ? :first : :all), :campaign_id => self.id )
     end
 
-    # Returns complete campaign data: targets, ad groups, keywords and ads.
+    # Returns complete campaign data: criteria, 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[:criteria] = CampaignCriterion.find(:campaign_id => campaign.to_param)
 
       campaign[:ad_groups] = AdGroup.find(:all, :campaign_id => campaign.to_param)
 
@@ -226,7 +235,7 @@ module Adapi
         :status => self[:status],
         :budget => self[:budget],
         :bidding_strategy => self[:bidding_strategy],
-        :targets => self[:targets],
+        :criteria => self[:criteria],
         :ad_groups => self[:ad_groups]
       }
     end

data/lib/adapi/campaign_criterion.rb

@@ -0,0 +1,278 @@
+# encoding: utf-8
+
+module Adapi
+
+  # http://code.google.com/apis/adwords/docs/reference/latest/CampaignTargetService.html
+  #
+  class CampaignCriterion < Api
+
+    attr_accessor :campaign_id, :criteria
+
+    validates_presence_of :campaign_id
+
+    CRITERION_TYPES = [ :age_range, :carrier, :content_label, :gender, :keyword,
+      :language, :location, :operating_system_version, :placement, :platform,
+      :polygon, :product, :proximity, :criterion_user_interest,
+      :criterion_user_list, :vertical ]
+
+    def attributes
+      super.merge( 'campaign_id' => campaign_id, 'criteria' => criteria )
+    end
+
+    def initialize(params = {})
+      params[:service_name] = :CampaignCriterionService
+      params[:negative] ||= false
+
+      @xsi_type = if (params[:negative] == true)
+        'NegativeCampaignCriterion'
+      else
+        'CampaignCriterion'
+      end
+
+      %w{ campaign_id criteria }.each do |param_name|
+        self.send "#{param_name}=", params[param_name.to_sym]
+      end
+
+      super(params)
+    end
+
+    def create
+      # step 1 - convert input hash to new array of criteria
+      # example: :language => [ :en, :cz ] ->  [:language, :en]
+      criteria_array = []
+
+      @criteria.each_pair do |criterion_type, criterion_settings|
+        case criterion_type
+          when :language
+            criterion_settings.each do |value|
+              criteria_array << [criterion_type, value]
+            end
+
+          # location - besides standard, expected interface, this criterion is
+          # heavily customized to comply with legacy interfaces (pre-v201109).
+          #
+          # Standard v201109 location interface:
+          # :location => location_id
+          # :location => { :id => location_id }
+          # :location => { :id => [ location_id ] }
+          #
+          # Accepted subtypes:
+          # id
+          # proximity (just actually redirects to proximity criterion)
+          # city
+          # province
+          # country
+          #
+          when :location, :geo # PS: geo is legacy synonym for location
+            # handles ":location => location_id" shortcut
+            unless criterion_settings.is_a?(Hash)
+              criterion_settings = { :id => criterion_settings.to_i }
+            end
+            
+            criterion_settings.each_pair do |subtype, subtype_settings|
+              # any location subtypes can be in array
+              subtype_settings = [ subtype_settings ] unless subtype_settings.is_a?(Array)
+              
+              case subtype
+                when :id
+                  subtype_settings.each do |value|
+                    criteria_array << [:location, value]
+                  end                  
+
+                # find id for location(s) by LocationCriterion service
+                when :name
+                  subtype_settings = [subtype_settings] unless subtype_settings.is_a?(Array)
+                  
+                  subtype_settings.each do |location_criteria|                   
+                    location = Adapi::Location.find(location_criteria)
+  
+                    raise "Location not found" if location.nil?
+
+                    criteria_array << [ :location, location[:id] ]
+                  end
+
+                when :proximity
+                  subtype_settings.each do |value|
+                    criteria_array << [subtype, value]
+                  end
+                  
+                else
+                  raise "Unknown location subtype: %s" % subtype
+              end
+            end
+
+          # not-supported criterions (they work, but have to be entered in
+          # google format, no shortcuts are set up for them)
+          else
+            unless CRITERION_TYPES.include?(criterion_type)
+              raise "Unknown criterion type; #{criterion_type}"
+            end
+          
+            if criterion_settings.is_a?(Array)
+              criterion_settings.each do |value|
+                criteria_array << [criterion_type, value]
+              end
+            else
+              criteria_array << [criterion_type, criterion_settings]
+            end
+          end
+      end
+
+      # step 2 - convert individual criteria to low-level google params
+      operations = criteria_array.map do |criterion_type, criterion_settings|
+        {
+          :operator => 'ADD',
+          :operand => {
+            :campaign_id => @campaign_id,
+            :criterion => CampaignCriterion::create_criterion(criterion_type, criterion_settings)
+          }
+        }
+      end
+      
+      response = self.mutate(operations)
+
+      (response and response[:value]) ? true : false
+    end
+  
+    def self.find(params = {})
+      params.symbolize_keys!
+
+      # by default, skip criteria types that have no criterion data
+      params[:skip_empty_criterion_types] ||= true
+      
+      if params[:conditions]
+        params[:campaign_id] = params[:campaign_id] || params[:conditions][:campaign_id]
+      end
+
+      raise ArgumentError, "Campaign ID is required" unless params[:campaign_id]
+
+      predicates = [ :campaign_id ].map do |param_name|
+        if params[param_name]
+          # convert to array
+          value = Array.try_convert(params[param_name]) ? params_param_name : [params[param_name]]
+          {:field => param_name.to_s.camelcase, :operator => 'IN', :values => value }
+        end
+      end.compact
+
+      # TODO: get more fields
+      selector = {
+        :fields => ['Id'],
+        :ordering => [{:field => 'Id', :sort_order => 'ASCENDING'}],
+        :predicates => predicates
+      }
+  
+      response = CampaignCriterion.new.service.get(selector)
+
+      response = (response and response[:entries]) ? response[:entries] : []
+
+      # return everything or only 
+      if params[:skip_empty_criterion_types]
+        response.select! { |criterion_type| criterion_type.has_key?(:criteria) }
+      end
+
+      # TODO optionally return just certain type(s)
+      # easy, just add condition (single type or array), filter and set
+      # :skip_empty_target_types option to false
+
+      response
+    end
+
+    # Transforms our custom high-level criteria parameters to AdWords API parameters
+    #
+    # Every criterion can be entered as high-level alias or as id
+    #
+    # Language:
+    # :language => [ :en, :cs ]
+    # :language => [ 1000, 1021 ] # integers!
+    #
+    #
+    def self.create_criterion(criterion_type, criterion_data)
+      case criterion_type
+        # 
+        # example: [:language, 'en'] -> {:xsi_type => 'Language', :id => 1000}
+        when :language
+          {
+            :xsi_type => 'Language',
+            :id => ConstantData::Language.find(criterion_data).id
+          }
+
+        when :location
+          {
+            :xsi_type => 'Location',
+            :id => criterion_data.to_i
+          }
+
+        when :proximity
+          radius_in_units, radius_units = parse_radius(criterion_data[:radius])
+          long, lat = parse_geodata(criterion_data[:geo_point])
+
+          {
+            :xsi_type => 'Proximity',
+            :radius_in_units => radius_in_units,
+            :radius_distance_units => radius_units,
+            :geo_point => {
+              :longitude_in_micro_degrees => long,
+              :latitude_in_micro_degrees => lat
+            }
+          }
+
+=begin
+            when :city
+              geo_values.merge(
+                :xsi_type => "#{geo_type.to_s.capitalize}Target",
+                :excluded => false
+              )
+
+            else # :country, :province
+              {
+                :xsi_type => "#{geo_type.to_s.capitalize}Target",
+                :excluded => false,
+                "#{geo_type}_code".to_sym => to_uppercase(geo_values)
+              }
+          end
+=end
+        
+        # unsupported criterion types
+        else
+          { :xsi_type => criterion_type.to_s.camelize }.merge(criterion_data)
+
+      end
+    end
+
+    def self.parse_radius(radius)
+      radius_in_units, radius_units = radius.split(' ', 2)
+      [
+        radius_in_units.to_i,
+        (radius_units == 'm') ? 'MILES' : 'KILOMETERS'
+      ]
+    end
+
+    # parse longitude and lattitude from string in this format:
+    # "longitude,lattitude" to [int,int] in Google microdegrees
+    # for example: "38.89859,-77.035971" -> [38898590, -77035971]
+    #
+    def self.parse_geodata(long_lat)
+      long_lat.split(',', 2).map { |x| to_microdegrees(x) }
+    end
+
+    # convert latitude or longitude data to microdegrees,
+    # a format with AdWords API accepts
+    #
+    # TODO alias :to_microdegrees :to_micro_units
+    #
+    def self.to_microdegrees(x)
+      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/campaign_target.rb

@@ -1,5 +1,8 @@
 # encoding: utf-8
 
+# This class is obsolete in v201109, CampaignCriterion is used instead. Only
+# AdScheduleTarget is still being used, but it's not implemented yet.
+
 module Adapi
 
   # http://code.google.com/apis/adwords/docs/reference/latest/CampaignTargetService.html
@@ -10,8 +13,6 @@ module Adapi
 
     validates_presence_of :campaign_id
 
-    # TODO validate if targets are in correct format
-
     def attributes
       super.merge( 'campaign_id' => campaign_id, 'targets' => targets )
     end
@@ -52,9 +53,6 @@ module Adapi
 
     def self.find(params = {})
       params.symbolize_keys!
-
-      # 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]
@@ -68,129 +66,13 @@ module Adapi
 
       response = (response and response[:entries]) ? response[:entries] : []
 
-      # 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
+    # Obsolete. Transforms our own high-level target parameters to google low-level
     #
     def self.create_targets(target_type, target_data)
-      case target_type
-        when :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|
-            case geo_type
-              when :proximity
-                radius_in_units, radius_units = parse_radius(geo_values[:radius])
-                long, lat = parse_geodata(geo_values[:geo_point])
-
-                {
-                  :xsi_type => "#{geo_type.to_s.capitalize}Target",
-                  :excluded => false,
-                  :radius_in_units => radius_in_units,
-                  :radius_distance_units => radius_units,
-                  :geo_point => {
-                    :longitude_in_micro_degrees => long,
-                    :latitude_in_micro_degrees => lat
-                  }
-                }
-
-              when :city
-                geo_values.merge(
-                  :xsi_type => "#{geo_type.to_s.capitalize}Target",
-                  :excluded => false
-                )
-
-              else # :country, :province
-                {
-                  :xsi_type => "#{geo_type.to_s.capitalize}Target",
-                  :excluded => false,
-                  "#{geo_type}_code".to_sym => to_uppercase(geo_values)
-                }
-            end
-          end
-        else nil 
-      end
-    end
-
-    def self.parse_radius(radius)
-      radius_in_units, radius_units = radius.split(' ', 2)
-      [
-        radius_in_units.to_i,
-        (radius_units == 'm') ? 'MILES' : 'KILOMETERS'
-      ]
-    end
-
-    # parse longitude and lattitude from string in this format:
-    # "longitude,lattitude" to [int,int] in Google microdegrees
-    # for example: "38.89859,-77.035971" -> [38898590, -77035971]
-    #
-    def self.parse_geodata(long_lat)
-      long_lat.split(',', 2).map { |x| to_microdegrees(x) }
-    end
-
-    # convert latitude or longitude data to microdegrees,
-    # a format with AdWords API accepts
-    #
-    # TODO alias :to_microdegrees :to_micro_units
-    #
-    def self.to_microdegrees(x)
-      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
+      nil 
     end
 
   end