cortex-scheduler v2.10.4

Cortex Scheduler

Scheduler is a simple library for Cortex apps to view a set of pages in order.

Prior to Cortex Player v1.6, apps were required to ship with cortex-scheduler. With v1.6, cortex-scheduler is part of the Cortex api. Instead of using the scheduler directly, you should use window.Cortex.view API.

A slot is a bucket of similar views. Usually, Cortex apps will consist of multiple pages and each page is expected to register a slot to submit view requests.

A view is a single instance of a display request. A view can either be a video play request or HTML request. When the time comes, the scheduler will consume a view from a slot by either playing the video or rendering the HTML.

View Priorities

There are three priority levels that apps can submit view requests to.

• Normal (L1): This is the common level where apps should submit regular view requests.
• Fallback (L2): Views in this level will only get displayed when no L1 view is available.
• Default (L3): When both L1 and L2 fails, scheduler will display views in L3. When marked as default, cortex-scheduler will track submissions to a slot and automatically play them as L3 views. Alternatively, default view slot can be a separate slot from any L1 and L2 slots. It is user's responsibility to submit views to this slot.

View Order

You may define the view order of the slots by registering slots in the order you want. Take the following example:

scheduler.register 'ads'
scheduler.register 'editorial'
scheduler.register 'ads'
scheduler.register 'ads'

With this registration order, the scheduler will try to show an ad view, then an editorial view followed by two ad views. If at any time a slot doesn't have any views, scheduler will move on to the next slot in the given view order.

Usage

Registering slots

• register(slotName, fallbackSlotName): This will create a slot named slotName. If provided, it will also create a fallback slot named fallbackSlotName and show views from fallbackSlotName when there are no views to display.
• Multiple calls to register() with the same slot name is valid. It will modify the view order.

Setting a default view

• setDefaultView(slotName): Sets a default view slot to be used when everything else fails. There are two ways of setting a default view slot:
• When slotName is an existing slot (either primary or fallback, registered with register()), scheduler will track submissions to the slot slotName and use them when everything else fails. The callbacks passed with original views will not get called in this case.

• When slotName is not an existing slot, scheduler will set up a regular slot for default views. It is user's responsibility to submit default views to this slot using the submitView or submitVideo calls. The callbacks passed with the views will get called in this case.

  It is not mandatory to set a default view but it is a good practice to prevent black screens.

  Note that default views are the final line of defense against black screens. It is a good idea to not make default views rely on anything that can fail (e.g. network I/O). Ideally, default views should make use of content that is being shipped as part of the application.

Submitting views

• submitView(slotName, html, duration, callbacks, opts): Submit an HTML view to slotName. All resources (images, etc.) being used in html should already be cached.
• submitVideo(slotName, videoFile, callbacks, opts): Submit a video to slotName. Video file should already be cached.
• submit methods accept an optional callbacks object. callbacks can have begin, ready, end and error properties. Scheduler will call the callbacks.begin() right before it starts to process the view and call the callbacks.end() when the view finishes. callbacks.ready() will get called when the view is attached to the DOM. At anytime, when an error occurs, it will call the callbacks.error() function.
• submit methods accept an optional opts object. Currently opts has the following fields:
• opts.audio.enable: Enable audio in video playbacks.
• opts.audio.volume: A floating value in the range of 0, 1 for audio volume.
• opts.view.label: View label. This value will eventually get displayed to the user. Choose a short and descriptive label to inform users about the content of this view (e.g. Ad asset).

NOOP Views

A NOOP view forces the scheduler to render a view from a lower priorty level slot.

• submitNoop(slotName, callbacks): Submits a NOOP view to slotName.
• When rendering an L1 view, if the view is NOOP, the scheduler will try to render a view in L2 (and eventually an L3 view if L2 is not available).
• When rendering an L2 view, if the view is NOOP, the scheduler will try to render a view in L3.
• NOOP views are not allowed in L3 views.
• Before rendering the alternative view for a NOOP view, the scheduler will fire begin, ready and end callbacks of the NOOP view in that order.

Configuration options

• defaultViewQueueLen: Number of views to track for the default view.
• maxViewDuration: Max view duration in milliseconds. Views with longer duration will get rejected.

Sample usage

Following is a sample usage based on Cortex.view API.

CortexView = window?.Cortex.view
EditorialView = require '...'

class AdView
  run: ->
    onerror = (err) =>
      run = => @run()
      # Delay the next run a bit to prevent looping too fast in case of temporary problems. 
      setTimeout run, 1000
    callbacks =
      error: onerror
      begin: =>
        # this will make sure we prepare another ad while the current one is being displayed.
        @run()
      ready: ->
        # View is attached to the DOM. We can query the DOM and make modifications as necessary.
      end: -> console.log "AdView finished rendering an ad."
      
    ad = getSomeAd()
    cacheAd(ad).then =>
      if isVideo(ad)
        CortexView.submitVideo 'AdView', cachedVideoFile, callbacks
      else
        CortexView.submitView 'AdView', @render(ad), adDuration, callbacks
        
    .catch onerror
      
adView = new AdView()
editorialView = new EditorialView()

CortexView.register 'AdView', 'EditorialView'
CortexView.setDefaultView 'AdView'
# Alternatively, you can create a new slot for default views.
# CortexView.setDefaultView 'DefaultView'
# Set up a way to submit views to DefaultView.

adView.run()
editorialView.run()

CortexView.start()