bing-ads-api 0.1.0

data/lib/bing-ads-api/data/ad_group.rb

@@ -0,0 +1,121 @@
+# -*- encoding : utf-8 -*-
+
+module BingAdsApi
+	
+	# Public : Defines an ad group. 
+	# 
+	# Author:: jlopezn@neonline.cl 
+	# 
+	# Examples 
+	#   ad_group = BingAdsApi::AdGroup.new(
+	#     :ad_distribution => BingAdsApi::AdGroup::SEARCH,
+	#     :language => BingAdsApi::AdGroup::SPANISH,
+	#     :name => "Ad Group name",
+	#     :pricing_model => BingAdsApi::AdGroup::CPC,
+	#     :bidding_model => BingAdsApi::AdGroup::KEYWORD) 
+	#   # => <BingAdsApi::AdGroup>
+	class AdGroup < BingAdsApi::DataObject
+		include BingAdsApi::AdDistribution
+		include BingAdsApi::AdRotationType
+		include BingAdsApi::PricingModel
+		include BingAdsApi::BiddingModel
+		include BingAdsApi::AdLanguage
+		include BingAdsApi::AdGroupStatus
+		
+		
+		attr_accessor :id,
+			:ad_distribution,
+			:ad_rotation,
+
+			:broad_match_bid,
+			:content_match_bid,
+			:exact_match_bid,
+			:phrase_match_bid,
+
+			:bidding_model, 
+			:pricing_model,
+
+			:language,
+			:name,
+			:status,
+
+			:start_date,
+			:end_date
+			
+			
+
+		# Public : Constructor in a ActiveRecord style, with a hash of attributes as input 
+		# 
+		# Author:: jlopezn@neonline.cl 
+		# 
+		# attributes - Hash with the objects attributes
+		def initialize(attributes={})
+			super(attributes)
+			set_custom_attributes(attributes)
+		end
+		
+		
+		# Public : Returns this object as a hash to SOAP requests 
+		# This methods is a specialization for the +DataObject#to_hash+ method
+		# that ads specific hash keys for the AdGroup object
+		# 
+		# Author:: jlopezn@neonline.cl 
+		# 
+		# keys - specifies the keys case: CamelCase or underscore_case
+		# 
+		# Returns:: Hash
+		def to_hash(keys = :underscore)
+			hash = super(keys)
+			
+			amount_key = get_attribute_key("amount", keys)
+			if self.content_match_bid
+				#hash.delete(:content_match_bid)
+				hash[get_attribute_key("content_match_bid", keys)] = {amount_key => self.content_match_bid}
+			end 
+			
+			if self.exact_match_bid
+				hash[get_attribute_key("exact_match_bid", keys)] = {amount_key => self.exact_match_bid}
+			end
+			
+			if self.phrase_match_bid
+				hash[get_attribute_key("phrase_match_bid", keys)] = {amount_key => self.phrase_match_bid}
+			end
+			
+			if self.broad_match_bid
+				hash[get_attribute_key("broad_match_bid", keys)] = {amount_key => self.broad_match_bid}
+			end
+			
+			if self.start_date
+				hash[get_attribute_key("start_date", keys)] = date_to_hash(self.start_date, keys)
+			end
+			
+			if self.end_date
+				hash[get_attribute_key("end_date", keys)] = date_to_hash(self.end_date, keys)
+			end
+			
+			return hash
+		end
+		
+		
+		private
+			def set_custom_attributes(attributes)
+				self.content_match_bid = attributes[:content_match_bid][:amount] if attributes.key?(:content_match_bid) 
+				self.exact_match_bid = attributes[:exact_match_bid][:amount] if attributes.key?(:exact_match_bid) 
+				self.phrase_match_bid = attributes[:phrase_match_bid][:amount] if attributes.key?(:phrase_match_bid) 
+				self.broad_match_bid = attributes[:broad_match_bid][:amount] if attributes.key?(:broad_match_bid) 
+				
+				if attributes.key?(:start_date) && !attributes[:start_date].nil?
+					self.start_date = DateTime.strptime( 
+						"#{attributes[:start_date][:year]}-#{attributes[:start_date][:month]}-#{attributes[:start_date][:day]}",
+						"%Y-%m-%d")
+				end
+
+				if attributes.key?(:end_date) && !attributes[:end_date].nil?
+					self.end_date = DateTime.strptime( 
+						"#{attributes[:end_date][:year]}-#{attributes[:end_date][:month]}-#{attributes[:end_date][:day]}",
+						"%Y-%m-%d")
+				end
+				
+			end
+	end
+end

data/lib/bing-ads-api/data/campaign.rb

@@ -0,0 +1,40 @@
+# -*- encoding : utf-8 -*-
+
+module BingAdsApi
+	
+	# Public : Define a campaign 
+	# 
+	# Author:: jlopezn@neonline.cl 
+	# 
+	# Examples 
+	#   campaign = BingAdsApi::Campaign.new(
+	#     :budget_type => BingAdsApi::Campaign::DAILY_BUDGET_STANDARD, 
+	#     :conversion_tracking_enabled => "false",
+	#     :daily_budget => 2000,
+	#     :daylight_saving => "false",
+	#     :description => name + " first description",
+	#     :monthly_budget => 5400,
+	#     :name => name + " first name",
+	#     :status => BingAdsApi::Campaign::PAUSED,
+	#     :time_zone => BingAdsApi::Campaign::SANTIAGO)
+	#   # => <BingAdsApi::Campaign> 
+	class Campaign < BingAdsApi::DataObject
+		include BingAdsApi::TimeZone
+		include BingAdsApi::BudgetLimitType
+		include BingAdsApi::CampaignStatus
+		include BingAdsApi::PricingModel
+		
+		
+		attr_accessor :id, 
+			:budget_type, 
+			:conversion_tracking_enabled,
+			:daily_budget,
+			:daylight_saving,
+			:description,
+			:monthly_budget,
+			:name,
+			:status,
+			:time_zone
+		
+	end
+end

data/lib/bing-ads-api/data/report_request.rb

@@ -0,0 +1,78 @@
+# -*- encoding : utf-8 -*-
+
+module BingAdsApi
+	
+	##
+	# Public : Defines the base object for all report requests.
+	# Do not instantiate this object. Instead, you may instantiate one 
+	# of the following report request objects which derives from this object to request a report.
+	# 
+	# Reference: http://msdn.microsoft.com/en-us/library/bing-ads-reporting-bing-ads-reportrequest.aspx
+	# 
+	# Author:: jlopezn@neonline.cl 
+	class ReportRequest < BingAdsApi::DataObject
+		
+		# Valid Formats for reports 
+		FORMATS = BingAdsApi::Config.instance.
+			reporting_constants['format']
+		
+		# Valid languages for reports 
+		LANGUAGES = BingAdsApi::Config.instance.
+			reporting_constants['language']
+
+		# Valid report request status for reports 
+		REQUEST_STATUS = BingAdsApi::Config.instance.
+			reporting_constants['request_status_type']
+		
+		attr_accessor :format, :language, :report_name, :return_only_complete_data
+		
+		# Public : Constructor. Adds validations to format and language attributes 
+		# 
+		# Author:: jlopezn@neonline.cl 
+		# 
+		# === Parameters
+		# attributes - Hash with Report request parameters
+		def initialize(attributes={})
+			raise Exception.new("Invalid format '#{attributes[:format]}'") if !valid_format(attributes[:format])
+			raise Exception.new("Invalid language '#{attributes[:language]}'") if !valid_language(attributes[:language])
+			super(attributes)
+			self.return_only_complete_data = attributes[:return_only_complete_data] || false
+		end
+	
+		
+		# Public:: Returns this object as a Hash for SOAP Requests 
+		# 
+		# Author:: jlopezn@neonline.cl 
+		# 
+		# === Parameters
+		# * +keys_case+ - specifies the case for the hash keys
+		# ==== keys_case
+		# * :camelcase  - CamelCase
+		# * :underscore - underscore_case
+		# 
+		# === Examples 
+		#   report_request.to_hash(:camelcase) 
+		#   # => {"Format"=>"Xml", "Language"=>"English", "ReportName"=>"My Report", "ReturnOnlyCompleteData"=>true}
+		# 
+		# Returns:: Hash
+		def to_hash(keys_case = :underscore)
+			hash = super(keys_case)
+			hash[get_attribute_key('format', keys_case)]   = FORMATS[self.format.to_s]
+			hash[get_attribute_key('language', keys_case)] = LANGUAGES[self.language.to_s]
+			return hash
+		end
+	
+		private
+		
+			def valid_format(format)
+				return FORMATS.key?(format.to_s)
+			end
+			
+			
+			def valid_language(language)
+				return LANGUAGES.key?(language.to_s)
+			end
+			
+	end
+	
+end

data/lib/bing-ads-api/data/report_request_status.rb

@@ -0,0 +1,48 @@
+# -*- encoding : utf-8 -*-
+
+module BingAdsApi
+	
+	##
+	# Public : Defines the status of a report request.
+	# 
+	# Reference: http://msdn.microsoft.com/en-US/library/bing-ads-reporting-bing-ads-reportrequeststatus.aspx
+	# 
+	# Author:: jlopezn@neonline.cl 
+	class ReportRequestStatus < BingAdsApi::DataObject
+
+		# Valid report request status for reports 
+		REQUEST_STATUS = BingAdsApi::Config.instance.
+			reporting_constants['request_status_type']
+		
+		attr_accessor :report_download_url, :status
+		
+		# Public:: Returns true if the status is success 
+		# 
+		# Author:: jlopezn@neonline.cl 
+		# 
+		# Returns:: boolean
+		def success?
+			return status == REQUEST_STATUS['success']
+		end
+		
+		# Public:: Returns true if the status is pending 
+		# 
+		# Author:: jlopezn@neonline.cl 
+		# 
+		# Returns:: boolean
+		def pending?
+			return status == REQUEST_STATUS['pending']
+		end
+		
+		# Public:: Returns true if the status is error 
+		# 
+		# Author:: jlopezn@neonline.cl 
+		# 
+		# Returns:: boolean
+		def error?
+			return status == REQUEST_STATUS['error']
+		end
+		
+	end
+	
+end

data/lib/bing-ads-api/data/reporting/account_performance_report_request.rb

@@ -0,0 +1,176 @@
+# -*- encoding : utf-8 -*-
+
+module BingAdsApi
+	
+	##
+	# Public : Defines the base object for all report requests.
+	# Do not instantiate this object. Instead, you may instantiate one 
+	# of the following report request objects which derives from this object to request a report.
+	# 
+	# Reference: http://msdn.microsoft.com/en-us/library/bing-ads-reporting-bing-ads-reportrequest.aspx
+	#
+	# Author:: jlopezn@neonline.cl 
+	# 
+	# === Usage
+	#   
+	#   request = BingAdsApi::AccountPerformanceReportRequest.new(
+	#     :format   => :xml,
+	#     :language => :english,
+	#     :report_name => "Me report",
+	#     :aggregation => :hourly,
+	#     :columns => [:account_name, :account_number, :time_period],
+	#     # The filter is specified as a hash
+	#     :filter => {
+	#       :ad_distribution => :search, 
+	#       :device_os => :android,
+	#       :device_type => :tablet,
+	#       :status => :submited },
+	#     :scope => { 
+	#       :account_ids => [123456, 234567],
+	#       :campaigns => [<BingAdsApi::CampaignReportScope>] },
+	#     # predefined date
+	#     :time => :this_week)
+	#   
+	#   request2 = BingAdsApi::AccountPerformanceReportRequest.new(
+	#     :format   => :csv,
+	#     :language => :french,
+	#     :report_name => "Me report",
+	#     :aggregation => :daily,
+	#     :columns => [:account_name, :account_number, :time_period],
+	#     # no filter is specified
+	#     :scope => { 
+	#       :account_ids => [123456, 234567],
+	#       :campaigns => [<BingAdsApi::CampaignReportScope>] },
+	#     # Custom date range
+	#     :time => {
+	#       :custom_date_range_start => {:day => 1, :month => 12, :year => 2013},
+	#       :custom_date_range_end   => {:day => 12, :month => 12, :year => 2013} }
+	#     )
+	class AccountPerformanceReportRequest < BingAdsApi::PerformanceReportRequest
+		
+		# Valid Columns for this report request 
+		COLUMNS = BingAdsApi::Config.instance.
+			reporting_constants['account_performance_report']['columns']
+		
+		# Valid Filters for this report request 
+		FILTERS = BingAdsApi::Config.instance.
+			reporting_constants['account_performance_report']['filter']
+		
+		
+		# Public : Constructor. Adds a validations for the columns, filter 
+		# and scope attributes 
+		# 
+		# Author:: jlopezn@neonline.cl 
+		# 
+		# === Parameters
+		# attributes - Hash with the report request attributes
+		#
+		# === Example
+		#   
+		#   request = BingAdsApi::AccountPerformanceReportRequest.new(
+		#     :format   => :xml,
+		#     :language => :english,
+		#     :report_name => "Me report",
+		#     :aggregation => :hourly,
+		#     :columns => [:account_name, :account_number, :time_period],
+		#     # The filter is specified as a hash
+		#     :filter => {
+		#       :ad_distribution => :search, 
+		#       :device_os => :android,
+		#       :device_type => :tablet,
+		#       :status => :submited },
+		#     :scope => { 
+		#       :account_ids => [123456, 234567],
+		#       :campaigns => [<BingAdsApi::CampaignReportScope>] },
+		#     # predefined date
+		#     :time => :this_week)
+		#   
+		#   request2 = BingAdsApi::AccountPerformanceReportRequest.new(
+		#     :format   => :csv,
+		#     :language => :french,
+		#     :report_name => "Me report",
+		#     :aggregation => :daily,
+		#     :columns => [:account_name, :account_number, :time_period],
+		#     # no filter is specified
+		#     :scope => { 
+		#       :account_ids => [123456, 234567],
+		#       :campaigns => [<BingAdsApi::CampaignReportScope>] },
+		#     # Custom date range
+		#     :time => {
+		#       :custom_date_range_start => {:day => 1, :month => 12, :year => 2013},
+		#       :custom_date_range_end   => {:day => 12, :month => 12, :year => 2013} }
+		#     )
+		def initialize(attributes={})
+			raise "Invalid columns" if !valid_columns(COLUMNS, attributes[:columns])
+			raise "Invalid filters" if !valid_filter(FILTERS, attributes[:filter])
+			raise "Invalid scope" if !valid_scope(attributes[:scope])
+			super(attributes)
+		end
+
+		# Public:: Returns the object as a Hash valid for SOAP requests 
+		# 
+		# Author:: jlopezn@neonline.cl 
+		# 
+		# === Parameters
+		# * +keys_case+ - case for the hashes keys: underscore or camelcase
+		# 
+		# Returns:: Hash
+		def to_hash(keys = :underscore)
+			hash = super(keys)
+			hash[get_attribute_key('columns', keys)] = 
+				columns_to_hash(COLUMNS, columns, keys)
+			hash[get_attribute_key('filter', keys)] = 
+				filter_to_hash(FILTERS, keys)
+			hash[get_attribute_key('scope', keys)] = scope_to_hash(keys) 
+			hash["@xsi:type"] = type_attribute_for_soap 
+			return hash
+		end
+		
+		private
+			
+
+			
+			# Internal:: Validates the scope attribute given in the constructor 
+			# 
+			# Author:: jlopezn@neonline.cl 
+			# 
+			# === Parameters
+			# * +scope+ - value for the 'scope' key in the has initializer
+			# 
+			# Returns:: true if the scope specification is valid. Raises Exception otherwise
+			# 
+			# Raises:: Exception if the scope is not valid
+			def valid_scope(scope)
+				raise Exception.new("Invalid scope: no account_ids key") if !scope.key?(:account_ids)
+				return true
+			end
+			
+			
+			# Internal:: Returns the scope attribute as a hash for the SOAP request 
+			# 
+			# Author:: jlopezn@neonline.cl 
+			# 
+			# === Parameters
+			# * +keys_case+ - case for the hash: underscore or camelcase
+			# 
+			# Returns:: Hash
+			def scope_to_hash(keys_case=:underscore)
+				return { get_attribute_key('account_ids', keys_case) => 
+						{"ins0:long" => object_to_hash(scope[:account_ids], keys_case)} }
+			end
+			
+			
+			# Internal:: Returns a string with type attribute for the ReportRequest SOAP tag 
+			# 
+			# Author:: jlopezn@neonline.cl 
+			# 
+			# Returns:: "v9:AccountPerformanceReportRequest"
+			def type_attribute_for_soap
+				return BingAdsApi::ClientProxy::NAMESPACE.to_s + ":" + 
+					BingAdsApi::Config.instance.
+						reporting_constants['account_performance_report']['type']
+			end
+
+	end
+	
+end