jjp-openx 1.1.4

data/.gitignore

@@ -0,0 +1,3 @@
+*.swp
+.svn/
+pkg/

data/History.txt

@@ -0,0 +1,24 @@
+=== 1.0.0 / 2008-04-07
+
+* 1 major enhancement
+
+  * Birthday!
+
+=== 1.1.0 / 2009-10-26
+
+* 2 major enhancements
+
+  * OpenX API Version 2 Support added
+  * OpenX Invocation API Support added
+
+* 1 minor enhancement
+
+  * Ruby on Rails documentation support added
+
+=== 1.1.1 / 2009-11-06
+
+* Minor bugfix to environment handling for Win32 users
+
+=== 1.1.2 / 2009-11-19
+
+* Documentation updates and patch to enable banner support on the OpenX Server

data/Manifest.txt

@@ -0,0 +1,26 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+lib/openx.rb
+lib/openx/image.rb
+lib/openx/services.rb
+lib/openx/services/advertiser.rb
+lib/openx/services/agency.rb
+lib/openx/services/banner.rb
+lib/openx/services/base.rb
+lib/openx/services/campaign.rb
+lib/openx/services/publisher.rb
+lib/openx/services/session.rb
+lib/openx/services/zone.rb
+test/assets/300x250.jpg
+test/assets/cat.swf
+test/helper.rb
+test/test_advertiser.rb
+test/test_agency.rb
+test/test_banner.rb
+test/test_base.rb
+test/test_campaign.rb
+test/test_publisher.rb
+test/test_session.rb
+test/test_zone.rb

data/README.rdoc

@@ -0,0 +1,139 @@
+= OpenX
+
+* http://rubygems.org/gems/jjp-openx
+* http://github.com/DoppioJP/openx
+
+== Description
+
+A Ruby interface to the OpenX XML-RPC API. Used touchlocal 1.1.2 version as base for adding more API calls to OpenX API from http://developer.openx.org/api/
+
+== Synopsis
+
+  OpenX::Services::Base.configuration = {
+    'username'  => 'admin',
+    'password'  => 'password',
+    'url'       => 'http://localhost/www/api/v2/xmlrpc/',
+  }
+
+  OpenX::Services::Agency.find(:all).each do |agency|
+    puts agency.name
+
+    # Look up publishers
+    agency.publishers.each do |publisher|
+      puts "-- #{publisher.name}"
+    end
+
+    # Create a publisher
+    Publisher.create!(
+      :agency       => agency,
+      :name         => 'My Test Publisher',
+      :contact_name => 'My Contact',
+      :email        => 'agency@example.com',
+      :username     => 'user',
+      :password     => 'password'
+    )
+  end
+
+== Requirements
+
+* ruby
+
+== Install
+
+* sudo gem install touchlocal-openx --source "http://gemcutter.org"
+* add "require 'openx'" to your code
+* Update your $HOME/.openx/credentials.yml file.  Here is a sample:
+
+    production:
+      username: admin
+      password: admin
+      url: http://www.example.com/www/api/v2/xmlrpc/
+      invocation_url: http://www.example.com/www/delivery/axmlrpc.php
+
+The YAML file lists configuration for each environment.  The gem uses the
+'production' environment by default. Trailing slash is required on the 'url'.
+'invocation_url' is only used by the OpenX::Invocation methods to serve 
+advertisements over XML-RPC
+
+== Ruby on Rails Integration
+
+As common deployment scenarios for RoR projects dictates that you manage all
+of your dependent files from within your project, storing your credentials.yml
+file in the default location (as above) will not work. However, this is easily
+fixed.
+
+Create your credentials.yml file in your ./config folder, and populate it with
+the necessary environment settings. It may in fact be more useful to name your
+file something like openx_credentials.yml to be explicit about the content.
+
+Then, add your gem require line to the initialize block of the environment.rb:
+
+  config.gem "touchlocal-openx", 
+    :lib => "openx", :source => "http://gemcutter.org"
+
+You will of course need to install the gem, either manually or via 
+rake gems:install
+
+Finally, create a config/initializers/openx.rb and include the following:
+
+  require 'yaml'
+  OpenX::Services::Base.configuration = 
+    YAML.load_file(File.join(Rails.root, 'config', 'credentials.yml'))[Rails.env]
+
+
+== Banner Keyword Support
+
+Not all attributes of OpenX objects that can be set in the web interface are 
+accessible via the API. A notable case of this is the ability to access 
+Banner Keywords. While it seems to be a case of "We'll add them as people 
+need them," this process is slower than one might expect; 
+https://developer.openx.org/jira/browse/OX-4779 has been an open ticket since 
+January 2009.
+
+As TouchLocal required the ability to access Banner Keywords, the 
+OpenX::Services::Banner object has the support for this attribute. If the 
+server does not support the attribute, then setting it will have no effect, 
+and it will return nil when retrieving it. To enable support on the server, 
+you will need access to the server source, and the included 
+php/openx-2.8.1-keywords.diff
+
+Copy the openx-2.8.1-keywords.diff file to the root of the OpenX distribution 
+on your server, and execute:
+
+    patch -p0 < openx-2.8.1-keywords.diff
+
+This will patch the relevant OpenX API to allow access to the keyword 
+attribute, meaning that now both your client and server support it. Happy days.
+
+This patch has been tested on OpenX Server versions 2.8.1 and 2.8.2 at the 
+time of writing.
+
+
+== License
+
+(The MIT License)
+
+Copyright (c) 2008:
+
+* {Aaron Patterson}[http://tenderlovemaking.com]
+* Andy Smith
+* {TouchLocal Ltd}[http://www.touchlocal.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.

data/Rakefile

@@ -0,0 +1,40 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "jjp-openx"
+    gemspec.summary = "A Ruby interface to the OpenX XML-RPC API with more OpenX APIs used"
+    gemspec.description = "A Ruby interface to the OpenX XML-RPC API. Used touchlocal 1.1.2 version as base for adding more API calls to OpenX API from http://developer.openx.org/api/"
+    gemspec.email = "jacobjp@mac.com"
+    gemspec.homepage = "http://github.com/DoppioJP/openx"
+    gemspec.authors = ["Aaron Patterson", "Andy Smith", "TouchLocal Plc", "DoppioJP"]
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+$: << "lib/"
+require 'openx'
+
+namespace :openx do
+  task :clean do
+    include OpenX::Services
+    ENV['OPENX_ENV'] = 'test'
+    Agency.find(:all) do |agency|
+      Advertiser.find(:all, agency.id).each do |advertiser|
+        Campaign.find(:all, advertiser.id).each do |campaign|
+          Banner.find(:all, campaign.id).each do |banner|
+            banner.destroy
+          end
+          campaign.destroy
+        end
+        advertiser.destroy
+      end
+    end
+  end
+end

data/VERSION

@@ -0,0 +1 @@
+1.1.4

data/jjp-openx.gemspec

@@ -0,0 +1,78 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE
+# Instead, edit Jeweler::Tasks in Rakefile, and run `rake gemspec`
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{jjp-openx}
+  s.version = "1.1.4"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Aaron Patterson", "Andy Smith", "TouchLocal Plc", "DoppioJP"]
+  s.date = %q{2010-04-18}
+  s.description = %q{A Ruby interface to the OpenX XML-RPC API. Used touchlocal 1.1.2 version as base for adding more API calls to OpenX API from http://developer.openx.org/api/}
+  s.email = %q{jacobjp@mac.com}
+  s.extra_rdoc_files = [
+    "README.rdoc"
+  ]
+  s.files = [
+    ".gitignore",
+     "History.txt",
+     "Manifest.txt",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "jjp-openx.gemspec",
+     "lib/openx.rb",
+     "lib/openx/image.rb",
+     "lib/openx/invocation.rb",
+     "lib/openx/services.rb",
+     "lib/openx/services/advertiser.rb",
+     "lib/openx/services/agency.rb",
+     "lib/openx/services/banner.rb",
+     "lib/openx/services/base.rb",
+     "lib/openx/services/campaign.rb",
+     "lib/openx/services/publisher.rb",
+     "lib/openx/services/session.rb",
+     "lib/openx/services/zone.rb",
+     "lib/openx/xmlrpc_client.rb",
+     "php/openx-2.8.1-keywords.diff",
+     "test/assets/300x250.jpg",
+     "test/assets/cat.swf",
+     "test/helper.rb",
+     "test/test_advertiser.rb",
+     "test/test_agency.rb",
+     "test/test_banner.rb",
+     "test/test_base.rb",
+     "test/test_campaign.rb",
+     "test/test_publisher.rb",
+     "test/test_session.rb",
+     "test/test_zone.rb"
+  ]
+  s.homepage = %q{http://github.com/DoppioJP/openx}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.6}
+  s.summary = %q{A Ruby interface to the OpenX XML-RPC API with more OpenX APIs used}
+  s.test_files = [
+    "test/helper.rb",
+     "test/test_advertiser.rb",
+     "test/test_agency.rb",
+     "test/test_banner.rb",
+     "test/test_base.rb",
+     "test/test_campaign.rb",
+     "test/test_publisher.rb",
+     "test/test_session.rb",
+     "test/test_zone.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end

data/lib/openx/image.rb

@@ -0,0 +1,22 @@
+module OpenX
+  class Image
+    include XMLRPC::Marshallable
+    attr_accessor :filename, :content, :editswf
+
+    def initialize(hash_or_file)
+      @editswf = 0
+      if hash_or_file.is_a?(File)
+        @filename = File.basename(hash_or_file.path)
+        @editswf = File.basename(@filename, '.swf') == @filename ? 0 : 1
+        @content  = XMLRPC::Base64.new(hash_or_file.read)
+      else
+        raise ArgumentError unless hash_or_file.key?(:filename)
+        raise ArgumentError unless hash_or_file.key?(:content)
+        hash_or_file.each { |k,v| send(:"#{k}=", v) }
+        unless self.content.is_a?(XMLRPC::Base64)
+          self.content = XMLRPC::Base64.new(self.content)
+        end
+      end
+    end
+  end
+end

data/lib/openx/invocation.rb

@@ -0,0 +1,64 @@
+module OpenX
+  class Invocation
+    class << self
+      #
+      # banner = OpenX::Invocation.view("Plumber")
+      #
+      # banners = OpenX::Invocation.view("Plumber", :count => 2, :exclude_by_campaignid => true) ;nil
+      # banners.each do |banner|
+      #   puts "Banner #{banner['bannerid']}"
+      # end; nil
+      #
+      def view(what, params = {})
+        defaults = {
+          :count => 1,
+          :campaignid => 0,
+          :target => '',
+          :source => '',
+          :with_text => false,
+          :exclusions => [],
+          :inclusions => [],
+          :exclude_by_campaignid => false,
+          :exclude_by_bannerid => false
+        }
+        params = defaults.merge(params)
+        
+        url = OpenX::Services::Base.configuration['invocation_url']
+
+        # Basic requirement as per /lib/max/Delivery/XML-RPC.php in OpenX
+        settings = {:cookies => [], :remote_addr => 'localhost'}
+        
+        context = [] # used by reference after initial use
+        params[:exclusions].each { |item| context << convert_to_context(false, item) }
+        params[:inclusions].each { |item| context << convert_to_context(true,  item) }
+        count = params[:count].to_i
+        
+        remote_params = [ what, params[:campaignid], params[:target], params[:source], params[:with_text], context]
+        server = XmlrpcClient.new2(url)
+        
+        out = []
+        if count > 0
+          (0...count).each do 
+            out << banner = server.call('openads.view', settings, *remote_params)
+            if count > 1
+              if params[:exclude_by_campaignid]
+                campaign_id = banner['campaignid']
+                context << convert_to_context(false, "campaignid:#{campaign_id}")
+              elsif params[:exclude_by_bannerid]
+                banner_id = banner['bannerid']
+                context << convert_to_context(false, "bannerid:#{banner_id}")
+              end
+            end
+          end
+        end
+        count > 1 ? out : out.first
+      end
+      
+      def convert_to_context(is_inclusion, item)
+        key = is_inclusion ? '==' : '!='
+        { key => item }
+      end
+      protected :convert_to_context
+    end
+  end
+end

data/lib/openx/services/advertiser.rb

@@ -0,0 +1,31 @@
+module OpenX
+  module Services
+    class Advertiser < Base
+      openx_accessor :name          => :advertiserName,
+                     :contact_name  => :contactName,
+                     :email         => :emailAddress,
+                     :username      => :username,
+                     :password      => :password,
+                     :agency_id     => :agencyId,
+                     :id            => :advertiserId
+
+      has_one :agency
+
+      self.create   = 'ox.addAdvertiser'
+      self.update   = 'ox.modifyAdvertiser'
+      self.delete   = 'ox.deleteAdvertiser'
+      self.find_one = 'ox.getAdvertiser'
+      self.find_all = 'ox.getAdvertiserListByAgencyId'
+
+      def initialize(params = {})
+        raise "need agency" unless params[:agency_id] || params[:agency]
+        params[:agency_id] ||= params[:agency].id
+        super(params)
+      end
+
+      def campaigns
+        Campaign.find(:all, self.id)
+      end
+    end
+  end
+end

data/lib/openx/services/agency.rb

@@ -0,0 +1,34 @@
+module OpenX
+  module Services
+    class Agency < Base
+      # Translate our property names to OpenX property names
+      openx_accessor  :name          => :agencyName,
+                      :contact_name  => :contactName,
+                      :email         => :emailAddress,
+                      :username      => :username,
+                      :password      => :password,
+                      :id            => :agencyId,
+                      :account_id    => :accountId
+
+      self.create   = 'ox.addAgency'
+      self.update   = 'ox.modifyAgency'
+      self.delete   = 'ox.deleteAgency'
+      self.find_one = 'ox.getAgency'
+      self.find_all = 'ox.getAgencyList'
+
+      def create_advertiser!(params = {})
+        Advertiser.create!(params.merge({
+          :agency   => self,
+        }))
+      end
+
+      def advertisers
+        Advertiser.find(:all, self.id)
+      end
+
+      def publishers
+        Publisher.find(:all, self.id)
+      end
+    end
+  end
+end

data/lib/openx/services/banner.rb

@@ -0,0 +1,119 @@
+require 'date'
+
+module OpenX
+  module Services
+    class Banner < Base
+      LOCAL_SQL = 'sql'
+      LOCAL_WEB = 'web'
+      EXTERNAL  = 'url'
+      HTML      = 'html'
+      TEXT      = 'txt'
+
+      RUNNING = 0
+      PAUSED  = 1
+
+      class << self
+        def find(id, *args)
+          session   = self.connection
+          server    = XmlrpcClient.new2("#{session.url}")
+          if id == :all
+            responses = server.call(find_all(), session, *args)
+            response = responses.first
+            return [] unless response
+            responses = [response]
+
+            ### Annoying..  For some reason OpenX returns a linked list.
+            ### Probably a bug....
+            while response.key?('aImage')
+              response = response.delete('aImage')
+              break unless response
+              responses << response
+            end
+
+            responses.map { |response|
+              new(translate(response))
+            }
+          else
+            response  = server.call(find_one(), session, id)
+            new(translate(response))
+          end
+        end
+      end
+
+      # Translate our property names to OpenX property names
+      openx_accessor  :name           => :bannerName,
+                      :campaign_id    => :campaignId,
+                      :id             => :bannerId,
+                      :storage_type   => :storageType,
+                      :file_name      => :fileName,
+                      :image_url      => :imageURL,
+                      :html_template  => :htmlTemplate,
+                      :width          => :width,
+                      :height         => :height,
+                      :weight         => :weight,
+                      :target         => :target,
+                      :url            => :url,
+                      :status         => :status,
+                      :adserver       => :adserver,
+                      :transparent    => :transparent,
+                      :image          => :aImage,
+                      :backup_image   => :aBackupImage,
+                      # 'keyword' only supported by patched server
+                      # as per README.rdoc
+                      # No averse effect when unsupported by server (returns nil)
+                      :keyword        => :keyword
+
+      has_one :campaign
+
+      self.create   = 'ox.addBanner'
+      self.update   = 'ox.modifyBanner'
+      self.delete   = 'ox.deleteBanner'
+      self.find_one = 'ox.getBanner'
+      self.find_all = 'ox.getBannerListByCampaignId'
+
+      def initialize(params = {})
+        raise ArgumentError.new("Missing campaign_id") unless params[:campaign_id] || params[:campaign]
+        params[:campaign_id] ||= params[:campaign].id
+        super(params)
+      end
+
+      # Alias for daily_statistics method to keep consistency with OpenX API calls
+      # Originally it was call for ox.bannerDailyStatistics so it is kept for compatibility with the previous version
+      def statistics start_on = Date.today, end_on = Date.today
+        daily_statistics start_on, end_on
+      end
+      
+      # Returns statistics in Array of Hashes by day, which are: impressions, clicks, requests and revenue.
+      # Each day is represented by XMLRPC::DateTime which has instant variables:
+      # @year, @month, @day, @hour, @min, @sec
+      def daily_statistics start_on = Date.today, end_on = Date.today
+        session = self.class.connection
+        @server.call('ox.bannerDailyStatistics', session, self.id, start_on, end_on)
+      end
+      
+      # Returns statistics in Array of Hashes by publisher, which are: impression, clicks, requests and revenue.
+      # Also returns publisherName and publisherId
+      def publisher_statistics start_on = Date.today, end_on = Date.today
+        session = self.class.connection
+        @server.call('ox.bannerPublisherStatistics', session, self.id, start_on, end_on)
+      end
+
+      # Returns statistics in Array of Hashes by zone, which are: impression, clicks, requests, conversions and revenue.
+      # Also returns publisherName, publisherId, zoneName, zoneId
+      def zone_statistics start_on = Date.today, end_on = Date.today
+        session = self.class.connection
+        @server.call('ox.bannerZoneStatistics', session, self.id, start_on, end_on)
+      end
+
+      def targeting
+        session = self.class.connection
+        @server.call('ox.getBannerTargeting', session, self.id)
+      end
+
+      def targeting= targeting
+        session = self.class.connection
+        @server.call('ox.setBannerTargeting', session, self.id, targeting)
+      end
+    end
+  end
+end