touchlocal-openx 1.1.0

data/.gitignore

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

data/History.txt

@@ -0,0 +1,6 @@
+=== 1.0.0 / 2008-04-07
+
+* 1 major enhancement
+
+  * Birthday!
+

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.txt

@@ -0,0 +1,109 @@
+= openx
+
+* http://openx.rubyforge.org
+
+== DESCRIPTION:
+
+A Ruby interface to the OpenX XML-RPC 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 => 'Aaron Patterson',
+      :email        => 'aaron@tenderlovemaking.com',
+      :username     => 'user',
+      :password     => 'password'
+    )
+  end
+
+== REQUIREMENTS:
+
+* ruby
+
+== INSTALL:
+
+* sudo gem install openx
+* 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 line:
+
+  OpenX::Services::Base.configuration = 
+    YAML.load_file(File.join(Rails.root, 'config', 'credentials.yml'))[Rails.env]
+
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008:
+
+* {Aaron Patterson}[http://tenderlovemaking.com]
+* Andy Smith
+* {TouchLocal Plc}[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 = "touchlocal-openx"
+    gemspec.summary = "A Ruby interface to the OpenX XML-RPC API"
+    gemspec.description = "A Ruby interface to the OpenX XML-RPC API"
+    gemspec.email = "info@touchlocal.com"
+    gemspec.homepage = "http://github.com/touchlocal/openx"
+    gemspec.authors = ["Aaron Patterson", "Andy Smith", "TouchLocal Plc"]
+  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.0

data/lib/openx.rb

@@ -0,0 +1,9 @@
+require 'xmlrpc/client'
+require 'openx/xmlrpc_client'
+require 'openx/services'
+require 'openx/invocation'
+require 'openx/image'
+
+module OpenX
+  VERSION = '1.1.0'
+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,63 @@
+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']
+
+        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.rb

@@ -0,0 +1,8 @@
+require 'openx/services/base'
+require 'openx/services/session'
+require 'openx/services/advertiser'
+require 'openx/services/agency'
+require 'openx/services/campaign'
+require 'openx/services/banner'
+require 'openx/services/publisher'
+require 'openx/services/zone'

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,96 @@
+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 https://developer.openx.org/jira/browse/OX-4779
+                      # 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
+
+      def 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
+
+      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