Class: Adapi::CampaignCriterion

Inherits:
Api
  • Object
show all
Defined in:
lib/adapi/campaign_criterion.rb

Overview

code.google.com/apis/adwords/docs/reference/latest/CampaignTargetService.html

Constant Summary collapse

ATTRIBUTES = 
[ :campaign_id, :criteria ]
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 ]

Constants inherited from Api

Api::API_EXCEPTIONS, Api::LOGGER

Instance Attribute Summary

Attributes inherited from Api

#adwords, #id, #params, #service, #status, #version, #xsi_type

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Api

#[], #[]=, #check_for_errors, create, #mutate, #new?, #persisted?, #store_errors, to_micro_units, #to_param, update

Constructor Details

#initialize(params = {}) ⇒ CampaignCriterion

Returns a new instance of CampaignCriterion.



24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
 
# File 'lib/adapi/campaign_criterion.rb', line 24

def initialize(params = {})
  params[:service_name] = :CampaignCriterionService
  params[:negative] ||= false

  @xsi_type = if (params[:negative] == true)
    'NegativeCampaignCriterion'
  else
    'CampaignCriterion'
  end

  ATTRIBUTES.each do |param_name|
    self.send "#{param_name}=", params[param_name]
  end

  # HOTFIX backward compatibility with old field for criteria
  @criteria ||= params[:targets] || {}

  super(params)
end

Class Method Details

.create_criterion(criterion_type, criterion_data) ⇒ Object

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!

TODO return error if language cannot be found



232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
 
# File 'lib/adapi/campaign_criterion.rb', line 232

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

.find(params = {}) ⇒ Object

Raises:

  • (ArgumentError) 


183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
 
# File 'lib/adapi/campaign_criterion.rb', line 183

def self.find(params = {})
  params.symbolize_keys!
  
  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 list all applicable fields in select fields
  selector = {
    :fields => ['Id', 'CriteriaType', 'KeywordText', 'LocationName'],
    :ordering => [{:field => 'Id', :sort_order => 'ASCENDING'}],
    :predicates => predicates
  }
  
  response = CampaignCriterion.new.service.get(selector)

  response = (response and response[:entries]) ? response[:entries] : []

  # 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

  # TODO add custom column :value, which will return criterion value
  # unrelated to the actual column where value is stored (code,
  # location_name, etc.)

  response.map { |entry| entry[:criterion] }.compact
end

.parse_geodata(long_lat) ⇒ Object

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]



297
298
299
 
# File 'lib/adapi/campaign_criterion.rb', line 297

def self.parse_geodata(long_lat)
  long_lat.split(',', 2).map { |x| to_microdegrees(x) }
end

.parse_radius(radius) ⇒ Object 



285
286
287
288
289
290
291
 
# File 'lib/adapi/campaign_criterion.rb', line 285

def self.parse_radius(radius)
  radius_in_units, radius_units = radius.split(' ', 2)
  [
    radius_in_units.to_i,
    (radius_units == 'm') ? 'MILES' : 'KILOMETERS'
  ]
end

.to_microdegrees(x) ⇒ Object

convert latitude or longitude data to microdegrees, a format with AdWords API accepts

TODO alias :to_microdegrees :to_micro_units



306
307
308
 
# File 'lib/adapi/campaign_criterion.rb', line 306

def self.to_microdegrees(x)
  Api.to_micro_units(x)
end

.to_uppercase(values) ⇒ Object

convert either single value or array of value to uppercase



312
313
314
315
316
317
318
 
# File 'lib/adapi/campaign_criterion.rb', line 312

def self.to_uppercase(values)
  if values.is_a?(Array)
    values.map { |value| value.to_s.upcase }
  else
    values.to_s.upcase
  end
end

Instance Method Details

#attributes ⇒ Object 



20
21
22
 
# File 'lib/adapi/campaign_criterion.rb', line 20

def attributes
  super.merge Hash[ ATTRIBUTES.map { |k| [k, self.send(k)] } ]
end

#create(operator = 'ADD') ⇒ Object 



44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
 
# File 'lib/adapi/campaign_criterion.rb', line 44

def create(operator = 'ADD')
  # step 1 - convert input hash to new array of criteria
  # example: :language => [ :en, :cs ] -> [ [:language, :en], [:language, :cs] ]
  criteria_array = []

  @criteria.each_pair do |criterion_type, criterion_settings|
    case criterion_type
      when :language
        Array(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 => operator,
      :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

#delete_all! ⇒ Object

Deletes all current campaign criteria



159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
 
# File 'lib/adapi/campaign_criterion.rb', line 159

def delete_all!
  # find all current criteria and extract operand params from them 
  original_criteria = CampaignCriterion.find(:campaign_id => @campaign_id).map do |criterion|
    criterion.select { |k,v| [ :xsi_type, :id ].include?(k) }
  end

  # HOTFIX temporarily remove platforms, adwords api throws error on no platforms
  original_criteria.delete_if { |c| c[:xsi_type] == "Platform" }

  operations = original_criteria.map do |criterion|
    {
      :operator => 'REMOVE',
      :operand => {
        :campaign_id => @campaign_id,
        :criterion => criterion
      }
    }
  end
  
  response = self.mutate(operations)

  (response and response[:value]) ? true : false
end

#destroy ⇒ Object

REFACTOR



153
154
155
 
# File 'lib/adapi/campaign_criterion.rb', line 153

def destroy
  self.create('REMOVE')
end

#update! ⇒ Object

custom update method, which delete all current criteria and adds new ones



144
145
146
147
148
149
150
 
# File 'lib/adapi/campaign_criterion.rb', line 144

def update!
  result = self.delete_all!

  # TODO return error if result == false

  self.create
end