sessionm-vast 1.0.4

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Chris Dinn
+
+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/README.rdoc

@@ -0,0 +1,51 @@
+= VAST
+
+A library for parsing Digital Video Ad Serving Template (VAST) 2.0 XML documents, as outlined by the Interactive Advertising Bureau at 
+http://www.iab.net/iab_products_and_industry_services/508676/digitalvideo/vast. VAST outlines a standard document format for communication between digital video players and ad servers, including support for 
+multiple forms of creative and tracking support that conforms to the latest IAB standards. 
+
+It's recommended that you review the resources made available for the IAB. Whenever possible the documentation in this library has been 
+pulled directly from those resources.
+
+This library strives to be as true to the standard as possible, while presenting a Ruby-friendly interface.
+
+== Installation
+
+VAST is available as a RubyGem.  
+
+  gem install vast
+
+== Usage
+
+Parse a VAST document and access its contents using an easy-to-understand model. For example:
+
+  document = VAST::Document.parse(File.read("vast_document.xml"))
+  inline_ad = document.inline_ads.first
+  puts inline_ad.linear_creative.mediafiles.first.type
+  => "video/x-flv"
+  puts inline_ad.linear_creative.mediafiles.first.url
+  => #<URI::HTTP:0x1015ad5f0 URL:http://creativeurl.ca/mediafile>
+
+See the documentation for the individual classes for an overview of what information available for each class.
+
+== Documentation
+
+Read the rdoc at http://rdoc.info/projects/chrisdinn/vast
+
+== Problems/Bugs/Requests
+
+Please, file an issue.
+
+== Note on Patches/Pull Requests
+
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+== Copyright
+
+© 2010 Chris Dinn. See LICENSE for details.

data/lib/vast/ad.rb

@@ -0,0 +1,103 @@
+module VAST
+  # Contains some combination of video, companions, and non-linear units for a single advertiser.
+  #
+  # A single VAST response may include multiple Ads from multiple advertisers. It will be up to 
+  # the Video Player to determine the order, timing, placement, etc for the multiple ads. However, 
+  # the player should generally respect the sequential order of the Ad elements within a VAST response.
+  #
+  # The VAST response does not contain information on the placement or timing of each ad. It is up 
+  # to the Video Player to determine the optimal inclusion points of the ads.
+  #
+  # Can either be a InlineAd, meaning it contains all the elements necessary to display the 
+  # visual experience, or a WrapperAd, which points to a downstream VAST document that must be 
+  # requested from another server.
+  # 
+  # An Ad may include one or more pieces of creative that are part of a single execution. For example, an Ad 
+  # may include a linear video element with a set of companion banners; this would be reflected by two Creative
+  # elements, one LinearCreative and one CompanionCreative.
+  class Ad < Element
+    
+    # Creates proper ad type
+    def self.create(node)
+      if node.at('InLine')
+        InlineAd.new(node)
+      elsif node.at('Wrapper')
+        WrapperAd.new(node)
+      else
+        raise InvalidAdError
+      end
+    end
+    
+    # Ad id, if indicated
+    def id
+      source_node[:id]
+    end
+
+    def sequence
+      source_node[:sequence]
+    end
+    
+    # Returns name of source ad server
+    def ad_system
+      ad_system_node = source_node.at("AdSystem")
+      if ad_system_node
+        ad_system_node.content
+      else
+        raise InvalidAdError, "missing AdSystem node in Ad"   
+      end
+    end
+    
+    # Returns URI to request if ad does not play due to error.
+    def error_url
+      error_url_node = source_node.at("Error")
+      URI.parse(URI.escape(error_url_node.content.strip)) if error_url_node
+    end
+    
+    # Returns an array containing all linear creatives.
+    def linear_creatives
+      source_node.xpath('.//Creative/Linear').to_a.collect do |node|
+        LinearCreative.new(node)
+      end
+    end
+    
+    # This is a convenience method for when only the first piece of linear creative is needed. 
+    # It's common for an ad to contain only one piece of linear creative.
+    def linear_creative
+      linear_creatives.first
+    end
+    
+    # Returns an array containing all non linear creatives.
+    def non_linear_creatives
+      source_node.xpath('.//Creative/NonLinearAds/NonLinear').to_a.collect do |node|
+        NonLinearCreative.new(node)
+      end
+    end
+    
+    # Returns an array containing all companion creatives.
+    def companion_creatives
+      source_node.xpath('.//Creative/CompanionAds/Companion').to_a.collect do |node|
+        CompanionCreative.new(node)
+      end
+    end
+    
+    # Each Ad must contain at least one impression.
+    def impression
+      URI.parse(URI.escape(source_node.at('Impression').content.strip))
+    end
+    
+    # Array of all impressions available for this ad, excluding those specific
+    # to a particular creative.
+    def impressions
+      source_node.xpath('.//Impression').to_a.collect do |node|
+        URI.parse(URI.escape(node.content.strip))
+      end
+    end
+    
+    # All extensions included with this ad.
+    def extensions
+      source_node.xpath('.//Extension').to_a.collect do |node|
+        Extension.new(node)
+      end
+    end
+  end
+end

data/lib/vast/companion_creative.rb

@@ -0,0 +1,81 @@
+module VAST
+  # Commonly text, display ads, rich media, or skins that wrap around the video experience. These ads come 
+  # in a number of sizes and shapes and typically run alongside or surrounding the video player.
+  class CompanionCreative < Creative
+    
+    def id
+      source_node[:id]
+    end
+    
+    # Width in pixels of companion
+    def width
+      source_node[:width].to_i
+    end
+    
+    # Height in pixels of companion
+    def height
+      source_node[:height].to_i
+    end
+    
+    # Width in pixels of expanding companion ad when in expanded state  
+    def expanded_width
+      source_node[:expandedWidth].to_i
+    end
+    
+    # Height in pixels of expanding companion ad when in expanded state  
+    def expanded_height
+      source_node[:expandedHeight].to_i
+    end
+    
+    # Defines the method to use for communication with the companion
+    def api_framework
+      source_node[:apiFramework]
+    end
+    
+    # URI to open as destination page when user clicks on the video
+    def click_through_url
+      URI.parse URI.escape(source_node.at('CompanionClickThrough').content.strip)
+    end
+    
+    # Alternate text to be displayed when companion is rendered in HTML environment.
+    def alt_text
+      node = source_node.at('AltText')
+      node.nil? ? nil : node.content
+    end
+    
+    # Type of companion resource, returned as a symbol. Either :static, :iframe, or :html.
+    def resource_type
+      if source_node.at('StaticResource')
+        :static
+      elsif source_node.at('IFrameResource')
+        :iframe
+      elsif source_node.at('HTMLResource')
+        :html
+      end
+    end
+    
+    # Returns MIME type of static creative
+    def creative_type
+      if resource_type == :static
+        source_node.at('StaticResource')[:creativeType]
+      end
+    end
+    
+    # Returns URI for static or iframe resource
+    def resource_url
+      case resource_type
+      when :static
+        URI.parse URI.escape(source_node.at('StaticResource').content.strip)
+      when :iframe
+        URI.parse URI.escape(source_node.at('IFrameResource').content.strip)
+      end
+    end
+    
+    # Returns HTML text for html resource
+    def resource_html
+      if resource_type == :html
+        source_node.at('HTMLResource').content
+      end
+    end
+  end
+end

data/lib/vast/creative.rb

@@ -0,0 +1,62 @@
+module VAST
+  # Contains the information related to a piece of creative.
+  # 
+  # === Sequence
+  # The Creative element takes an optional “sequence” attribute that indicates the suggested order in which the 
+  # Creatives should be displayed. If two Creative elements are intended to be shown at the same time they should 
+  # share the same sequence number.
+  class Creative < Element
+    
+    def ad
+      Ad.create source_node.ancestors('Ad').first
+    end
+    
+    def id
+      creative_node[:id]
+    end
+    
+    def ad_id
+      creative_node[:AdID]
+    end
+    
+    # The preferred order in which multiple Creatives should be displayed
+    def sequence
+      creative_node[:sequence]
+    end
+    
+    # Data to be passed into the video ad.
+    def ad_parameters
+      source_node.at('AdParameters').content
+    end
+    
+    # Returns a hash, keyed by event name, containing an array of URIs to be called for each event.
+    def tracking_urls
+      tracking_urls = {}
+      source_node.xpath('.//Tracking').to_a.collect do |node|
+        underscored_name = underscore(node[:event])
+        if tracking_urls[underscored_name.to_sym]
+           tracking_urls[underscored_name.to_sym] << URI.parse(URI.escape(node.content.strip))
+        else
+           tracking_urls[underscored_name.to_sym] = [URI.parse(URI.escape(node.content.strip))]
+        end
+      end
+      tracking_urls
+    end
+    
+    protected
+    
+    def underscore(camel_cased_word)
+       camel_cased_word.to_s.gsub(/::/, '/').
+          gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+          gsub(/([a-z\d])([A-Z])/,'\1_\2').
+          tr("-", "_").
+          downcase
+    end
+    
+    private
+    
+    def creative_node
+      source_node.ancestors('Creative').first
+    end
+  end
+end

data/lib/vast/document.rb

@@ -0,0 +1,71 @@
+module VAST
+  # A complete VAST document
+  class Document < Nokogiri::XML::Document
+    @macros = ["ERRORCODE", "CONTENTPLAYHEAD", "CACHEBUSTING", "ASSETURI"]
+
+    def self.eval_macro(xml_string)
+    end
+
+    # Parse a VAST XML document
+    def self.parse(*args)
+      # VAST 3 support macro, need to uri escape all macros
+      if (args[0].is_a? String)
+        @macros.each{|x|  args[0].gsub!("[#{x}]", "%5B#{x}%5D")}
+      end
+      super(*args)
+    end
+    
+    # Same as parse, but raises InvalidDocumentError if document is not valid
+    def self.parse!(*args)
+      document = parse(*args)
+      raise InvalidDocumentError unless document.valid?
+      document
+    end
+    
+    # Checks whether document conforms to the VAST XML Schema Definitions, accessible at
+    # http://www.iab.net/iab_products_and_industry_services/508676/digitalvideo/vast
+    def valid?
+      version_node = self.xpath('/VAST/@version').first
+      major_version = version_node ? version_node.value.to_i : 0
+      case major_version
+      when 2
+        xsd_file = VAST_SCHEMA_XSD_FILE
+      when 3
+        xsd_file = VAST3_SCHEMA_XSD_FILE
+      else
+        return false
+      end
+      xsd = Nokogiri::XML::Schema(File.read(xsd_file))
+      xsd.valid?(self)
+    end
+    
+    # A single VAST response may include multiple Ads from multiple advertisers. It will be up to the 
+    # Video Player to determine the order, timing, placement, etc for the multiple ads. However, the 
+    # player should generally respect the sequential order of the Ad elements within the ad.
+    #
+    # If no ads of any type are available, it would be indicated by the absence of any ads.
+    def ads
+      self.root.xpath('.//Ad').to_a.collect do |node|
+        Ad.create(node)
+      end
+    end
+    
+    # All inline ads
+    def inline_ads
+      ads.select{ |ad| ad.kind_of?(VAST::InlineAd) }
+    end
+
+    def ad_pod_ads
+      ads.select{ |ad| ad.sequence.is_a? Numeric }.sort{|x, y| x.sequence <=> y.sequence }
+    end
+
+    def stand_alone_ads
+      ads.select{ |ad| !ad.sequence.is_a?(Numeric) }
+    end
+    
+    # All wrapper ads
+    def wrapper_ads
+      ads.select{ |ad| ad.kind_of?(VAST::WrapperAd) }
+    end
+  end
+end

data/lib/vast/element.rb

@@ -0,0 +1,9 @@
+module VAST
+  class Element
+    attr_reader :source_node
+
+    def initialize(node)
+      @source_node = node
+    end
+  end
+end

data/lib/vast/extension.rb

@@ -0,0 +1,18 @@
+module VAST
+  # The VAST allows any valid XML within the extensions element. Use of extensions will necessarily 
+  # require offline coordination between VAST sender and VAST receiver. 
+  class Extension < Element
+
+    # Extension type
+    def type
+      source_node[:type]
+    end
+    
+    # Access to the XML contents of this extension, as a Nokogiri::XML::Node
+    # http://nokogiri.rubyforge.org/nokogiri/Nokogiri/XML/Node.html. Alias of
+    # Extension#source_node
+    def xml
+      source_node
+    end
+  end
+end

data/lib/vast/icon.rb

@@ -0,0 +1,87 @@
+module VAST
+  # Any number of Mediafile objects can be provided for a single Ad, but it is assumed that all Mediafiles belongs
+  # to a single Ad object represent the same creative unit with the same  duration, Ad-ID (ISCI code), etc.
+  class Icon < Element
+    
+    def program
+      source_node[:program]
+    end
+    
+    def width
+      source_node[:width].to_i
+    end
+
+    def height
+      source_node[:height].to_i
+    end
+    
+    def xPosition
+      source_node[:xPosition].to_i
+    end
+
+    def yPosition
+      source_node[:yPosition].to_i
+    end
+    
+    def duration
+      source_node[:duration].to_i
+    end
+
+    def offset
+      source_node[:offset].to_i
+    end
+    
+    # Defines the method to use for communication with the companion
+    def api_framework
+      source_node[:apiFramework]
+    end
+
+    def resource_type
+      if source_node.at('StaticResource')
+        :static
+      elsif source_node.at('IFrameResource')
+        :iframe
+      elsif source_node.at('HTMLResource')
+        :html
+      end
+    end
+    
+    # Returns MIME type of static creative
+    def creative_type
+      if resource_type == :static
+        source_node.at('StaticResource')[:creativeType]
+      end
+    end
+
+    # Returns URI for static or iframe resource
+    def resource_url
+      case resource_type
+      when :static
+        URI.parse URI.escape(source_node.at('StaticResource').content.strip)
+      when :iframe
+        URI.parse URI.escape(source_node.at('IFrameResource').content.strip)
+      end
+    end
+    
+    # Returns HTML text for html resource
+    def resource_html
+      if resource_type == :html
+        source_node.at('HTMLResource').content
+      end
+    end
+
+    def click_through_url
+      URI.parse URI.escape(source_node.at('IconClickThrough').content.strip)
+    end
+
+    def click_tracking_url
+      URI.parse URI.escape(source_node.at('IconClickTracking').content.strip)
+    end
+
+    def view_tracking_url
+      URI.parse URI.escape(source_node.at('IconViewTracking').content.strip)
+    end
+    
+    # end of class
+  end
+end

data/lib/vast/inline_ad.rb

@@ -0,0 +1,22 @@
+module VAST
+  # Contains all the information necessary to display the visual experience of one complete ad.
+  class InlineAd < Ad
+    
+    # URI of request to survey vendor
+    def survey_url
+      URI.parse URI.escape(source_node.at('Survey').content.strip)
+    end
+
+    # Common name of ad
+    def ad_system
+      source_node.at('AdSystem').content
+    end
+    
+    # Common name of ad
+    def ad_title
+      source_node.at('AdTitle').content
+    end
+    
+  end
+end
+

data/lib/vast/linear_creative.rb

@@ -0,0 +1,57 @@
+module VAST
+  # LinearCreative is presented before, in the middle of, or after the video content is consumed by the user, 
+  # in very much the same way a TV commercial can play before, during or after the chosen program.
+  class LinearCreative < Creative
+    
+    # Duration of creative
+    def duration
+      source_node.at('Duration').content
+    end
+    
+    # VAST 3
+    def skipoffset
+      source_node[:skipoffset]
+    end
+    
+    # URI to open as destination page when user clicks on the video
+    def click_through_url
+      URI.parse URI.escape(source_node.at('ClickThrough').content.strip)
+    end
+    
+    # An array of URIs to request for tracking purposes when user clicks on the video
+    def click_tracking_urls
+      source_node.xpath('.//ClickTracking').to_a.collect do |node|
+        URI.parse URI.escape(node.content.strip)
+      end
+    end
+    
+    # A hash of URIs to request on custom events such as hotspotted video. This library
+    # required custom click urls to identify themselves with an `id` attribute, which is
+    # used as the key for this hash
+    def custom_click_urls
+      custom_click_urls = {}
+      source_node.xpath('.//CustomClick').to_a.collect do |node|
+        key = underscore(node[:id]).to_sym
+        custom_click_urls[key] = URI.parse(URI.escape(node.content.strip))
+      end
+      custom_click_urls
+    end
+    
+    # Returns mediafiles containing the information required to display the linear creative's media
+    # 
+    # It is assumed that all mediafiles accessible represent the same creative unit with the same 
+    # duration, Ad-ID (ISCI code), etc.
+    def mediafiles
+      source_node.xpath('.//MediaFile').to_a.collect do |node|
+        Mediafile.new(node)
+      end
+    end
+
+    def icons
+      source_node.xpath('.//Icon').to_a.collect do |node|
+        Icon.new(node)
+      end
+    end
+    
+  end
+end

data/lib/vast/mediafile.rb

@@ -0,0 +1,56 @@
+module VAST
+  # Any number of Mediafile objects can be provided for a single Ad, but it is assumed that all Mediafiles belongs
+  # to a single Ad object represent the same creative unit with the same  duration, Ad-ID (ISCI code), etc.
+  class Mediafile < Element
+    
+    # Location of linear file
+    def url
+      URI.parse URI.escape(source_node.content.strip)
+    end
+    
+    def id
+      source_node[:id]
+    end
+    
+    # Method of delivery of ad, either "streaming" or "progressive"
+    def delivery
+      source_node[:delivery]
+    end
+    
+    # MIME type. Popular MIME types include, but are not limited to “video/x-ms-wmv” for 
+    # Windows Media, and “video/x-flv” for Flash Video.
+    def type
+      source_node[:type]
+    end
+    
+    # Bitrate of encoded video in Kbps
+    def bitrate
+      source_node[:bitrate].to_i
+    end
+    
+    # Pixel dimensions of video width
+    def width
+      source_node[:width].to_i
+    end
+    
+    # Pixel dimensions of video height
+    def height
+      source_node[:height].to_i
+    end
+    
+    # Defines the method to use for communication with the companion
+    def api_framework
+      source_node[:apiFramework]
+    end
+    
+    # Whether it is acceptable to scale the mediafile.
+    def scalable?
+      source_node[:scalable]=="true"
+    end
+    
+    # Whether the mediafile must have its aspect ratio maintained when scaled
+    def maintain_aspect_ratio?
+      source_node[:maintainAspectRatio]=="true"
+    end
+  end
+end