sem4r 0.1.1

data/lib/sem4r/ad_group/ad_group.rb

@@ -0,0 +1,340 @@
+# -------------------------------------------------------------------
+# Copyright (c) 2009-2010 Sem4r sem4ruby@gmail.com
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+# -------------------------------------------------------------------
+
+module Sem4r
+  class AdGroup < Base
+
+    #
+    # enum AdGroup.Status
+    #
+    enum :Statuses, [
+      :ENABLED,
+      :PAUSED,
+      :DELETED
+    ]
+
+    attr_reader :campaign
+    
+    g_accessor :name
+    g_accessor :status
+
+    def initialize(campaign, name = nil, &block)
+      super( campaign.adwords, campaign.credentials )
+      @campaign = campaign
+      @id = nil
+      @criterions = nil
+      self.name = name unless name.nil?
+      if block_given?
+        @inside_initialize = true
+        block.arity < 1 ? instance_eval(&block) : block.call(self)
+        save unless campaign.inside_initialize?
+      end
+      @inside_initialize = false
+    end
+
+    def inside_initialize?
+      @inside_initialize
+    end
+
+    def id
+      _save unless @id
+      @id
+    end
+
+    def to_s
+      "#{@id ? @id : 'unsaved'} '#{@name}' (#{@status}) - #{@bid}"
+    end
+
+    def xml(t)
+      t.campaignId campaign.id
+      t.name name
+      t.status "ENABLED"
+      @bids.to_xml(t) if @bids
+    end
+
+    def to_xml(tag)
+      builder = Builder::XmlMarkup.new
+      builder.tag!(tag) { |t|
+        xml(t)
+        #        xml.campaignId campaign.id
+        #        xml.name name
+        #        xml.status "ENABLED"
+        #        @bids.to_xml(xml) if @bids
+      }
+    end
+
+    def empty?
+      criterions.empty?
+    end
+
+    ###########################################################################
+    # management
+
+    def self.create(campaign, &block)
+      new(campaign, &block).save
+    end
+
+    def self.from_element(campaign, el)
+      new(campaign) do
+        @id          = el.elements["id"].text.strip.to_i
+        name           el.elements["name"].text.strip
+        status         el.elements["status"].text.strip
+        bids           el.elements["bids"]
+      end
+    end
+
+    def save
+      _save
+      _save_criterions
+      _save_ads
+      _save_ad_params
+      self
+    end
+
+    private
+
+    def _save
+      unless @id
+        soap_message = service.ad_group.create(credentials, to_xml("operand"))
+        add_counters( soap_message.counters )
+        rval = REXML::XPath.first( soap_message.response, "//mutateResponse/rval")
+        id = REXML::XPath.match( rval, "value/id" ).first
+        @id = id.text.strip.to_i
+      end
+    end
+
+    public
+
+    def delete
+      soap_message = service.ad_group.delete(credentials, @id)
+      add_counters( soap_message.counters )
+      @id = -1 # logical delete
+    end
+
+    ###########################################################################
+    # bids management
+
+    def bids(el = nil)
+      @bids = AdGroupBids.from_element(el) if el
+      @bids
+    end
+
+    def manual_cpc_bids(&block)
+      @bids = ManualCPCAdGroupBids.new(&block)
+    end
+
+    def manual_cpm_bids(&block)
+      @bids = ManualCPMAdGroupBids.new(&block)
+    end
+
+    ###########################################################################
+    # ad management
+
+    def text_ad(&block)
+      ad = AdGroupTextAd.new(self, &block)
+      @ads ||= []
+      @ads.push(ad)
+      ad
+    end
+
+    def mobile_ad(&block)
+      ad = AdGroupMobileAd.new(self, &block)
+      @ads ||= []
+      @ads.push(ad)
+      ad
+    end
+
+    def ads(refresh = false)
+      _ads unless @ads and !refresh
+      @ads
+    end
+
+    def p_ads(refresh = false)
+      ads(refresh).each do |ad|
+        puts ad.to_s
+      end
+      self
+    end
+
+    private
+
+    def _ads
+      soap_message = service.ad_group_ad.all(credentials, id)
+      add_counters( soap_message.counters )
+      rval = REXML::XPath.first( soap_message.response, "//getResponse/rval")
+      els = REXML::XPath.match( rval, "entries/ad")
+      @ads = els.map do |el|
+        AdGroupAd.from_element( self, el )
+      end
+    end
+
+    def _save_ads
+      return unless @ads
+
+      unsaved_ads = @ads.select { |a| !a.saved? }
+      return if unsaved_ads.empty?
+
+      xml = unsaved_ads.inject('') do |xml,ad|
+        o = AdGroupAdOperation.new.add(ad)
+        xml + o.to_xml("operations")
+      end
+      soap_message = service.ad_group_ad.mutate(credentials, xml)
+      add_counters( soap_message.counters )
+      els = REXML::XPath.match( soap_message.response, "//mutateResponse/rval/value/ad/id")
+      els.each_with_index do |e,index|
+        id = e.text.strip.to_i
+        unsaved_ads[index].instance_eval{ @id = id }
+      end
+    end
+
+    public
+
+    ###########################################################################
+    # criterion management
+
+    def negative_keyword(text = nil, match = CriterionKeyword::BROAD, &block)
+      negative_criterion = NegativeAdGroupCriterion.new(self)
+      criterion = CriterionKeyword.new(self, text, match, &block)
+      negative_criterion.criterion = criterion
+      @criterions ||= []
+      @criterions.push( negative_criterion )
+      negative_criterion
+    end
+
+    #
+    # instanziate an BiddableAdGroupCriterion but it is called 'keyword' for convenience
+    #
+    # http://code.google.com/apis/adwords/v2009/docs/reference/AdGroupCriterionService.BiddableAdGroupCriterion.html
+    #
+    def keyword(text = nil, match = nil, &block)
+      biddable_criterion = BiddableAdGroupCriterion.new(self)
+      criterion = CriterionKeyword.new(self, text, match, &block)
+      biddable_criterion.criterion = criterion
+      @criterions ||= []
+      @criterions.push( biddable_criterion )
+      biddable_criterion
+    end
+
+    def placement(url = nil, &block)
+      biddable_criterion = BiddableAdGroupCriterion.new(self)
+      criterion = CriterionPlacement.new(self, url, &block)
+      biddable_criterion.criterion = criterion
+      @criterions ||= []
+      @criterions.push( biddable_criterion )
+      biddable_criterion
+    end
+
+    def criterions(refresh = false)
+      _criterions unless @criterions and !refresh
+      @criterions
+    end
+
+    def p_criterions(refresh = false)
+      criterions(refresh).each do |criterion|
+        puts criterion.to_s
+      end
+      self
+    end
+
+    def find_criterion(criterion_id, refresh = false)
+      _criterions unless @criterions and !refresh
+      @criterions.find {|c| c.id == criterion_id}
+    end
+
+    private
+
+    def _criterions
+      soap_message = service.ad_group_criterion.all(credentials, id)
+      add_counters( soap_message.counters )
+      rval = REXML::XPath.first( soap_message.response, "//getResponse/rval")
+      els = REXML::XPath.match( rval, "entries/criterion")
+      @criterions = els.map do |el|
+        Criterion.from_element( self, el )
+      end
+    end
+
+    def _save_criterions
+      # @criterions.each { |criterion| criterion.save } if @criterions
+
+      return unless @criterions
+
+      unsaved_criterions = @criterions.select { |a| !a.saved? }
+      return if unsaved_criterions.empty?
+
+      xml = unsaved_criterions.inject('') do |xml,ad|
+        o = AdGroupCriterionOperation.new.add(ad)
+        xml + o.to_xml("operations")
+      end
+      soap_message = service.ad_group_criterion.mutate(credentials, xml)
+      add_counters( soap_message.counters )
+      els = REXML::XPath.match( soap_message.response, "//mutateResponse/rval/value/criterion/id")
+      els.each_with_index do |e,index|
+        id = e.text.strip.to_i
+        unsaved_criterions[index].criterion.instance_eval{ @id = id }
+      end
+    end
+
+    public
+
+    ###########################################################################
+    # ad param management
+
+    def ad_param(criterion, index = nil, text = nil, &block)
+      ad_param = AdParam.new(self, criterion, index, text, &block)
+      ad_param.save unless inside_initialize? or criterion.inside_initialize?
+      @ad_params ||= []
+      @ad_params.push( ad_param )
+      ad_param
+    end
+
+    def ad_params(refresh = false)
+      _ad_params unless @ad_params and !refresh
+      @ad_params
+    end
+
+    def p_ad_params(refresh = false)
+      ad_params(refresh).each do |ad_param|
+        puts ad_param.to_s
+      end
+      self
+    end
+
+    private
+
+    def _ad_params
+      soap_message = service.ad_param.all(credentials, id)
+      add_counters( soap_message.counters )
+      rval = REXML::XPath.first( soap_message.response, "//getResponse/rval")
+      els = REXML::XPath.match( rval, "entries")
+      @ad_params = els.map do |el|
+        AdParam.from_element( self, el )
+      end
+    end
+
+    def _save_ad_params
+      return unless @ad_params
+      @ad_params.each { |p| p.save }
+    end
+
+  end
+end

data/lib/sem4r/ad_group/ad_group_bids.rb

@@ -0,0 +1,170 @@
+# -------------------------------------------------------------------
+# Copyright (c) 2009-2010 Sem4r sem4ruby@gmail.com
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+# -------------------------------------------------------------------
+
+module Sem4r
+  class AdGroupBids
+    include SoapAttributes
+
+    enum :Types, [
+      :BudgetOptimizerAdGroupBids,
+      :ConversionOptimizerAdGroupBids,
+      :ManualCPCAdGroupBids,
+      :ManualCPMAdGroupBids]
+
+    # g_accessor :type
+
+    def initialize(&block)
+      if block_given?
+        block.arity < 1 ? instance_eval(&block) : block.call(self)
+      end
+    end
+
+    def self.from_element(el)
+      type =  el.elements["AdGroupBids.Type"].text.strip
+      klass = Module::const_get(type)
+      klass.from_element(el)
+    end
+
+    def to_s
+      "#{@maxcpc / 10000} cents"
+    end
+  end
+
+  class BudgetOptimizerAdGroupBids < AdGroupBids
+  end
+
+  class ConversionOptimizerAdGroupBids < AdGroupBids
+  end
+
+  class ManualCPCAdGroupBids < AdGroupBids
+
+    g_accessor :keyword_max_cpc
+    g_accessor :site_max_cpc
+
+    def xml(t)
+      return "" unless @keyword_max_cpc or @site_max_cpc
+      t.tag!('bids', 'xsi:type' => 'ManualCPCAdGroupBids') { |xml|
+        xml.tag!('AdGroupBids.Type') { xml.text! 'ManualCPCAdGroupBids' }
+
+        if @keyword_max_cpc
+          xml.keywordMaxCpc {
+            xml.amount {
+              xml.tag!('ComparableValue.Type') { xml.text! 'Money' }
+              xml.microAmount keyword_max_cpc
+            }
+          }
+        end
+
+        if @site_max_cpc
+          xml.siteMaxCpc {
+            xml.amount {
+              xml.tag!('ComparableValue.Type') { xml.text! 'Money' }
+              xml.microAmount site_max_cpc
+            }
+          }
+        end
+      }
+    end
+
+    def to_xml(builder = nil)
+      builder = Builder::XmlMarkup.new unless builder
+      xml(builder)
+      #      xml = builder.tag!('bids', 'xsi:type' => 'ManualCPCAdGroupBids') { |xml|
+      #        xml.tag!('AdGroupBids.Type') { xml.text! 'ManualCPCAdGroupBids' }
+      #
+      #        if @keyword_max_cpc
+      #          xml.keywordMaxCpc {
+      #            xml.amount {
+      #              xml.tag!('ComparableValue.Type') { xml.text! 'Money' }
+      #              xml.microAmount keyword_max_cpc
+      #            }
+      #          }
+      #        end
+      #
+      #        if @site_max_cpc
+      #          xml.siteMaxCpc {
+      #            xml.amount {
+      #              xml.tag!('ComparableValue.Type') { xml.text! 'Money' }
+      #              xml.microAmount site_max_cpc
+      #            }
+      #          }
+      #        end
+      #      }
+    end
+
+    def self.from_element(el)
+      new do
+        kel = el.elements["keywordMaxCpc"]
+        if kel
+          el_amount = kel.elements["amount"]
+          keyword_max_cpc     el_amount.elements["microAmount"].text.strip.to_i
+        end
+        sel = el.elements["siteMaxCpc"]
+        if sel
+          el_amount = sel.elements["amount"]
+          site_max_cpc     el_amount.elements["microAmount"].text.strip.to_i
+        end
+        # TODO: it is possible something like:
+        #        el.elements["maxCpc"] do |el|
+        #          el.elements["amount"] do el
+        #            max_cpc el["microAmount"]
+        #          end
+        #        end
+      end
+    end
+  end
+
+  class ManualCPMAdGroupBids < AdGroupBids
+    g_accessor :max_cpm
+
+    def xml(t)
+      return "" unless @max_cpm
+      t.tag!('bids', 'xsi:type' => 'ManualCPMAdGroupBids') { |xml|
+        xml.tag!('AdGroupBids.Type') { xml.text! 'ManualCPMAdGroupBids' }
+        xml.maxCpm {
+          xml.amount {
+            xml.tag!('ComparableValue.Type') { xml.text! 'Money' }
+            xml.microAmount max_cpm
+          }
+        }
+      }
+    end
+
+    def to_xml(builder = nil)
+      builder = Builder::XmlMarkup.new unless builder
+      xml(builder)
+    end
+
+    def self.from_element(el)
+      new do
+        kel = el.elements["maxCpm"]
+        if kel
+          el_amount = kel.elements["amount"]
+          max_cpm     el_amount.elements["microAmount"].text.strip.to_i
+        end
+      end
+    end
+
+  end
+
+end

data/lib/sem4r/ad_group/ad_group_service.rb

@@ -0,0 +1,75 @@
+# -------------------------------------------------------------------
+# Copyright (c) 2009-2010 Sem4r sem4ruby@gmail.com
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+# -------------------------------------------------------------------
+
+module Sem4r
+  class AdGroupService
+    include SoapCall
+
+    def initialize(connector)
+      @connector = connector
+      @service_namespace = "https://adwords.google.com/api/adwords/cm/v201003"
+      @header_namespace = @service_namespace
+      @sandbox_service_url = "https://adwords-sandbox.google.com/api/adwords/cm/v201003/AdGroupService"
+    end
+
+    soap_call_v2009 :all,       :mutate => false
+    soap_call_v2009 :create,    :mutate => true
+    soap_call_v2009 :delete,    :mutate => true
+
+    def _all(campaign_id)
+      <<-EOFS
+      <get xmlns="#{@service_namespace}">
+        <selector>
+          <campaignIds>#{campaign_id}</campaignIds>
+        </selector>
+      </get>
+      EOFS
+    end
+
+    def _create( xml )
+      <<-EOFS
+      <mutate xmlns="#{@service_namespace}">
+        <operations xsi:type="AdGroupOperation">
+          <operator>ADD</operator>
+            #{xml}
+        </operations>
+      </mutate>
+      EOFS
+    end
+
+    def _delete( id )
+      <<-EOFS
+      <mutate xmlns="#{@service_namespace}">
+        <operations xsi:type="AdGroupOperation">
+          <operator>SET</operator>
+          <operand>
+            <id>#{id}</id>
+            <status>DELETED</status>
+          </operand>
+        </operations>
+      </mutate>
+      EOFS
+    end
+
+  end
+end

data/lib/sem4r/ad_group/mobile_ad_image.rb

@@ -0,0 +1,33 @@
+# -------------------------------------------------------------------------
+# Copyright (c) 2009-2010 Sem4r sem4ruby@gmail.com
+# 
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+# 
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+# 
+# -------------------------------------------------------------------------
+
+module Sem4r
+
+  class MobileAdImage
+    def initialize(mobile_ad, &block)
+      @mobile_ad = mobile_ad
+    end
+  end
+
+end