ruby-vast 1.0.6

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: fb2a018e9a3eda6638792161504845821368d184
+  data.tar.gz: 527f23f4e0e39ca8e6602397d06ff25ef78e6417
+SHA512:
+  metadata.gz: f1801bc2fa08103fea3b347e69d6961c174c3da0af92198678bf72cf5d6e84859a573e266d09cc5268a1f495080187ca931e4ad0117791312c840f324a634645
+  data.tar.gz: c4e662b14472de98ed5184189d025d25d49aea95e63256525c19b4bcfc6ff70a18fcc4757c55c8961a94ec3c7f2f31c0dcae14c69f77ee01180257d87b09f0cd

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Chris Dinn, 2017 Mike Mulev
+
+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,55 @@
+= 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.
+
+== Running Tests
+
+  bundle exec rake
+
+== 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/ruby-vast.rb

@@ -0,0 +1 @@
+require 'vast'

data/lib/vast.rb

@@ -0,0 +1,33 @@
+require 'nokogiri'
+
+require 'vast/document'
+require 'vast/element'
+require 'vast/ad'
+require 'vast/inline_ad'
+require 'vast/wrapper_ad'
+require 'vast/creative'
+require 'vast/linear_creative'
+require 'vast/mediafile'
+require 'vast/icon'
+require 'vast/companion_creative'
+require 'vast/non_linear_creative'
+require 'vast/extension'
+
+# This module wraps VAST documents, as outlined by the IAB at http://www.iab.net/media/file/VAST-2_0-FINAL.pdf
+module VAST
+  VAST_VERSION = 2.0
+  VAST_SCHEMA_XSD_FILE = File.expand_path(File.join(File.dirname(__FILE__), 'vast_2.0.1.xsd'))
+  VAST3_SCHEMA_XSD_FILE = File.expand_path(File.join(File.dirname(__FILE__), 'vast3_draft.xsd'))
+
+  class VASTError < StandardError; end
+  
+  # Raised when parsing a VAST document that does not conform to the VAST spec XSD
+  class InvalidDocumentError < VASTError; end
+  
+  # Raised when parsing a VAST ad node that is not complete
+  class InvalidAdError < VASTError; end
+  
+  # Raised when parsing a VAST creative node that is not complete
+  class InvalidCreativeError < VASTError; end
+  
+end

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(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(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(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 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 source_node.at('StaticResource').content.strip
+      when :iframe
+        URI.parse 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(node.content.strip)
+        else
+           tracking_urls[underscored_name.to_sym] = [URI.parse(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