Placing Advertisements in your Roku Channel


Instant TV Channel includes a built-in ad server with your Roku channel. This allows you to use video ads from multiple ad providers at the same time, in order to increase your fill-rate and maximize your ad revenue.

Several different types of advertisements can be included in your Roku channel:

  • Banner Ads - A 728x90 (HD) or 540x60 (SD) image that is displayed on the bottom half of a Horizontal List.
  • Selectable Banner Ads - A 728x90 (HD) or 540x60 (SD) image that is displayed on the bottom half of a Horizontal List and is selectable using the Roku remote control. When the Banner Ad is clicked a video ad is played. Selectable Banner Ad videos cannot be fast-fowarded or rewound, but they can be optionally paused if AllowPause is set to "True".
  • Preroll, Midroll and Postroll Video Ads - A video ad that is automatically played immediately before, in the middle of, or after a selected video content item. Preroll, Midroll and Postroll Video Ads cannot be fast-forwarded or rewound, but they can be optionally paused if AllowPause is set to "True". The position of Midroll ads is specified within each video content item. If the ad is not played through completely, the associated video content item cannot be viewed unless AllowSkip is set to "True".

    Per-Inquiry or "PI" ads are often used as Preroll, Midroll, and Postroll ads. Please contact Phil Autelitano at for information about using PI advertisements in your Roku channel.

  • LiveRail Video Ads - A video ad that is delivered from LiveRail, an advertising monetization platform. LiveRail Video Ads cannot be skipped, fast-forwarded, or rewound, but they can be paused. LiveRail Video Ads must be played through completely before the associated video content item can be viewed. LiveRail Video Ads are not supported on 1st-generation Roku players running firmware version 3.1 or earlier.
  • VAST Video Ads - A video ad that is delivered from a VAST-compatible ad provider. The ad provider supplies a special URL called a "Tag" that is used to select the video ad. VAST Video Ads cannot be skipped, fast-forwarded, or rewound, but they can be optionally paused if AllowPause is set to "True". VAST Video Ads must be played through completely before the associated video content item can be viewed.
  • Vidillion Video Ads - A video ad that is delivered from Vidillion, an advertising aggregator and CDN. Vidillion Video Ads cannot be skipped, paused, fast-forwarded, or rewound. Vidillion Video Ads must be played through completely in order for the associated video content item to be viewed.

    Please contact Instant TV Channel at or 717-441-4386 for information about using Vidillion advertisements in your Roku channel.

  • Roku Channel Linking Ads - Banner, preroll, midroll and postroll video ads can be used to advertise a Roku channel by linking the video ad to a target channel. See this sample Linking Ad hosted on Vimeo: http://vimeo.com/103862296. If the remote control OK or Star key is pressed while a Linking Ad is playing, then the current channel is exited and control is transferred to an installation screen for the target channel. If the target channel is already installed on the player, then the current channel is exited and the target channel is launched.

The videos used for advertisements are typically commercial content that is 10 to 60 seconds in length, however there are no restrictions as to the actual content type or length that can be used.

Several different video ad positions (sometimes referred to as "slots") are available, including preroll, postroll, and an unlimited number of midroll positions. The following diagram illustrates a video with preroll ads, postroll ads, and 3 separate midroll ad positions.



How to include a Banner Ad in a channel:

  1. Click the Content link on the left side of the page to enter the Content Editor.
  2. From the Content Editor, right-click the Horizontal List that will contain the Banner Ad. The Horizontal List must have its ListStyle parameter set to "arced-landscape" or "flat-category" or the Banner will not be displayed. This is a limitation of the Roku player firmware.
  3. Select New Ad from the pop-up context menu. A new Ad item will appear under the selected Horizontal List.
  4. In the lower portion of the screen, change the AdType parameter to "banner" or "selectable banner". If multiple Banner Ads are included in a single Horizontal List, one will be selected at random whenever the Horizontal List containing the ads is displayed by a player.
  5. If this is a "Commercial" channel, change the SDPosterUrl and HDPosterUrl parameters to point to your own Banner artwork. The Banner sizes should be 728x90 for HD and 540x60 for SD. If this is a "Free" or "Unlimited" channel, the Banner's poster URLs are not editable.
  6. Set the AdBuffering parameter to the message to be briefly displayed while the ad video is buffering. If AdBuffering is blank, then the text from the Title parameter is displayed instead.
  7. If this is a Selectable Banner for a "Commercial" channel, change the Stream 1 Url parameter to point to your own video ad stream. If this is a "Free" or "Unlimited" channel, the video URL is not editable.
  8. If available, multiple bitrate streams can be used the same way as with a regular video content item. If only a single ad video bitrate is available, the Bitrate parameter can be left at "0".

How to include a Video Ad in a channel:

  1. Click the Content link on the left side of the page to enter the Content Editor.
  2. From the Content Editor, right-click the List or Grid that will contain the video ad. The ad will also be played for any videos within a child List or Grid beneath the one containing the ad, as long as there are no other video ads in the child List or Grid.

    Video ads in Grids are not recommended for channels installed on older player models such as the Roku XDS (2100) and earlier. When ads are used on older players the Grid will need to be re-loaded after each video is played, which causes a noticeable delay and resets the position within the Grid Row.

  3. Select New Ad from the pop-up context menu. A new Ad item will appear under the selected List or Grid. Multiple ads can be contained in a single List or Grid.
  4. In the lower portion of the screen, change the AdType parameter to one of the following options:

    • "preroll", "liverail preroll", "vast preroll" or "vidillion preroll" - The ad is played immediately after selecting a video content item from a menu, before the video content item is played.
    • "preroll2", "liverail preroll2" "vast preroll2" or "vidillion preroll2" - The ad is played immediately after the Preroll ad, before the selected video content item is played.
    • "midroll", "liverail midroll", "vast midroll" or"vidillion midroll" - The ad is played in one or more positions in the middle of a video content item.
      • The Midroll Position parameter in each video content item is used to specify where the Midroll is positioned.
      • Click the Midroll New button in a video content item in order to specify additional midroll positions.
      • After a Midroll or Midroll2 ad has completed, playback will resume at the nearest key-frame or I-frame at or before the specified Midroll or Midroll2 position.
    • "midroll2", "liverail midroll2" "vast midroll2" or "vidillion midroll2" - The ad is played in the position(s) immediately after the Midroll ad.
    • "postroll", "liverail postroll", "vast postroll" or "vidillion postroll" - The ad is played in the position immediately after the selected content item is completely played.
    • "postroll2", "liverail postroll2" "vast postroll2" or "vidillion postroll2" - The ad is played in the position immediately after the Postroll ad.

    If more than one ad is available for the same position, then one will be selected based on the setting of the AdOptimize parameter described below.

  5. Set the ad's RepeatLimit parameter to the minimum number of minutes that you want to wait after this ad is played until it can be played again. This parameter can be particularly useful if there are several ads available for the same position, as it can prevent the same ad from being played twice in a row. The RepeatLimit parameter has no effect if it is less than the Theme Editor's global AdRepeatLimit parameter.

    The default value of RepeatLimit is "5" minutes, and the minimum value is "1" minute.

    Vidillion video ads will ignore RepeatLimit if it is set to less than "5" minutes, and will use the default value of "5" minutes instead.

  6. Set the ad's StartTime parameter to the number of minutes that you want to wait after the channel is started before the ad is played for the first time. For example, setting StartTime to 5 or 10 minutes will allow subscribers to become engaged in the channel's content before the first ad is presented to them. The StartTime parameter has no effect if it is less than the Theme Editor's global AdStartTime parameter.

    The default and minimum value of StartTime is "0" minutes.

  7. The ad's Weight parameter determines how often the ad will play relative to other ads. This allows you to provide a certain percentage of your ad inventory to a specific ad provider. The Weight parameter is a value from 1 to 99, with a default value of 1. The Theme Editor AdOptimize parameter must be set to "off" or "random" in order for ad weights to be effective. Examples:
    • Several ads, play all ads equally - Set the Weight parameter for each ad to "1".
    • Two ads, play one ad 30% of the time and play the other ad 70% of the time - Set the Weight parameter for the 30% ad to "30" and set the Weight parameter for the 70% ad to "70". Alternatively you could use "3" and "7", or any other combination where the ratio between the weights is 3:7.
    • Three ads, play one ad 30% of the time and the other two ads 35% of the time each - Set the Weight parameter for the 30% ad to "30" and set the Weight parameter for the other two ads to "35".
  8. If set to "True", the ad's AllowSearch parameter (not available for all ad types) will allow the viewer to display the Search screen using the remote STAR key while the ad is playing within an AutomaticPlay-enabled list. The Theme SearchScope parameter must be set to something other than "off" for the Search screen to be available.
  9. If set to "True", the ad's AllowPause parameter will allow the viewer to pause the video ad. This parameter is not available to LiveRail ads which always allow pausing.
  10. If set to "True", the ad's AllowSkip parameter (not available for all ad types) will allow the viewer to skip the video ad and continue watching the video content item. The AllowSkip parameter is usually set to "False" so that the video ad must be viewed in order to continue watching the video content item.
  11. Set the ad's AdBuffering parameter to the message to be displayed while the video ad's stream is buffering.
  12. In lieu of a text message, an entire 1280x720 (HD) or 720x480 (SD) picture may be displayed while the ad is buffering by specifying the ad's SDBufferPictureUrl, HDBufferPictureUrl and BufferPictureTimer parameters. If a picture is displayed it will hide any text specified by the AdBuffering parameter. The BufferPicture parameters are ignored on early Roku players with version 3.1 firmware.
  13. If this is not a LiveRail ad, change the Stream 1 Url parameter to point to your ad's video stream or to the VAST or Vidillion URL or "Tag" supplied by your ad provider or delivery network. If this is a "Free" or "Unlimited" channel, the Stream 1 Url parameter is not editable.
  14. If this is a LiveRail ad, insert your Publisher ID into the AdPublisherId parameter. If this is a "Free" or "Unlimited" channel, then AdPublisherID is not editable.
  15. If available, multiple bitrate ad streams can be used the same way as with a regular video content item. If only a single bitrate is available, the Bitrate parameter can be left at "0".
  16. Click the Theme link on the left side of the page to enter the Theme Editor.
  17. Set the Theme Editor AdRepeatLimit parameter to specify the minimum amount of time between ad plays of each particular type (preroll, preroll2, midroll, etc).
  18. Set the Theme Editor AdStartTime parameter to delay all ads from playing for a specified number of minutes after the channel is started.
  19. The transport keys on the Roku remote control are disabled during ad playback. The ad video can still be exited with the remote control BACK or UP keys; however, if a preroll, preroll2, midroll, or midroll2 ad is not played completely through, then the selected video that would normally follow the ad will not be played.
  20. VAST ad playback statistics are automatically sent to your VAST ad provider or ad delivery network.

How to Link an Ad to a Roku Channel:

  1. Determine the App ID of the target Roku channel. The target channel is the channel that you want to jump to when the remote control OK or Star button is pressed while the ad is playing. A channel's App ID, usually a 5-digit number, can be found in the URL displayed in your browser's address bar while viewing the channel in your Roku Developer or Owner Account. For example, the App ID for the Clutch Cargo Roku channel is 41985.
  2. Insert the channel's App ID into the ad's ChannelAppId parameter. This parameter is not available for LiveRail ads.
  3. If the remote control OK or Star key is pressed while a Linking Ad is playing, then the current channel is exited and control is transferred to an installation screen for the target channel.
  4. If the target channel is already installed on the player, then the current channel is exited and the target channel is launched.
  5. If the ChannelAppId parameter does not contain a valid App ID of a target channel, then instead of displaying an installation screen, the channel exits and the main Roku home screen is displayed.

Theme Editor parameters affecting Video Ad playback:

  • AdOptimize - If multiple ads are available for a single ad position, this parameter determines the order in which the ad providers are used to fill the ads.

    If multiple ads for the same position are available and AdOptimize is set to "off" then a single ad is selected at random to fill the ad request. If the ad provider cannot fill the ad request then no other ad provider is tried and no ad is played.

    If multiple ads for the same position are available and AdOptimize is set to "random" then an ad is selected at random to fill the ad request. If the ad provider cannot fill the ad request then another ad of the same type is randomly selected to fill the request. This process continues until either the ad request is filled or until all available ads have been tried.

    If multiple ads for the same position are available and AdOptimize is set to "ordered" then the top-most ad in the Content Editor tree is selected to fill the ad request. If the ad provider cannot fill the ad request then the next lower ad of the same type in the tree is selected to fill the request. This process continues until the either the ad request is filled or until all available ads in the tree have been tried.

    Important - When the AdOptimize parameter is set to "ordered" then the ad Weight parameter is ignored.

    The highest level of monetization can usually be achieved by setting AdOptimize to "ordered" while arranging the ads in the Content Editor tree in order from highest CPM to lowest CPM. This will cause the higher CPM ads to be tried before the lower CPM ads.

    The default value of AdOptimize is "random".

    AdOptimize only affects the following ad types:

      preroll, liverail preroll, vast preroll, vidillion preroll, midroll, liverail midroll, vast midroll, vidillion midroll, postroll, liverail postroll, vast postroll, vidillion postroll

    AdOptimize DOES NOT affect following ad types, which are always selected at random if multiple ads are available for a single position:

      banner, selectable banner, preroll2, liverail preroll2, vast preroll2, vidillion preroll2, midroll2, liverail midroll2, vast midroll2, vidillion midroll2, postroll2, liverail postroll2, vast postroll2, vidillion postroll2

  • AdRepeatLimit - This parameter determines how frequently ads in each of the 6 positions (preroll, preroll2, midroll, midroll2, postroll, postroll2) are played. For example, if AdRepeatLimit is set to 10 minutes and a Preroll ad has just finished playing, then no other Preroll, LiveRail Preroll, VAST Preroll or Vidillion Preroll ads will be played for at least 10 minutes. A separate timer is maintained by the player for each of the 6 ad positions. This parameter is useful if your video content is extremely short, in order to prevent your viewers from seeing more ads than content.

    If the AdRepeatLimit setting is different than an individual ad's Content Editor RepeatLimit setting, then the greater of the two values is used.

    The default value of AdRepeatLimit is "0" minutes.

  • AdStackingLimit - This parameter allows multiple ads to fill a single ad position.

    If multiple ad providers are available for an ad position, then the Roku device will attempt to fill the ad position with as many ads as are specified by AdStackingLimit.

    The default value of AdStackingLimit is "1" which causes the Roku device to stop ad processing after an ad position has been successfully filled by a single ad provider.

    Using a value of AdStackingLimit greater the "1" with an ad Weight greater than "1" may result in the same ad provider being called consecutively for the same ad slot.

    AdStackingLimit only affects the following ad types:

      preroll, liverail preroll, vast preroll, vidillion preroll, midroll, liverail midroll, vast midroll, vidillion midroll, postroll, liverail postroll, vast postroll, vidillion postroll

    AdStackingLimit DOES NOT affect following ad types, which always have a stacking limit of 1:

      selectable banner, preroll2, liverail preroll2, vast preroll2, vidillion preroll2, midroll2, liverail midroll2, vast midroll2, vidillion midroll2, postroll2, liverail postroll2, vast postroll2, vidillion postroll2

  • AdStartTime - This parameter determines the minimum number of minutes to wait after the channel is started before playing the first video ad. For example, setting AdStartTime to 5 or 10 minutes will allow subscribers to become engaged in the channel's content before the first ad is presented to them.

    If the AdStartTime setting is different than an individual ad's Content Editor StartTime setting, then the greater of the two values is used.

    The default value of AdStartTime is "0" minutes.

  • IncludeRAF - This parameter must be set to "True" in order to use the Roku Advertising Framework (RAF) to display video ads in your Roku channel. If this parameter is changed you must repackage the channel and then re-upload the Pkg file to your Roku Developer Account. RAF is not compatible with legacy (2011 and earlier) Roku devices which are no longer supported by Roku.
  • RAFNielsenEnabled - Set to "True" to enable Nielsen Digital Ad Ratings. By enabling the RAF Nielsen feature of Instant TV Channel you agree to the following terms & conditions provided by Roku. Please contact before enabling the RAF Nielsen features of Instant TV Channel.
  • RAFNielsenAppId - The unique application ID for accurate campaign measurement. Do not change the default value unless you have your own App ID assigned by Nielsen.
  • RAFNielsenGenreDefault - This is the default genre used for ad reporting if an individual video item does not have a value set for its NielsenGenre parameter, or if an video item created in an older version of Instant TV Channel does not have a NielsenGenre parameter. This should be set to the most specific genre applicable to the video content.
  • VASTMode - Specifies the VAST (Video Ad Serving Template) processing mode. Currently available VAST modes are Roku Advertising Framework "RAF-Partial" and "RAF-Complete".

    "RAF-Partial" allows the use of Instant TV Channel's AdBuffering, SDBufferPictureUrl, HDBufferPictureUrl, and BufferPictureTimer parameters for custom ad buffering screens.

    "RAF-Complete" uses RAF's built-in ad buffering screens and "Ad X of Y" ad progress overlay, but does not allow the use of Instant TV Channel's custom ad buffering screens.

  • VideoAdsEnabled - This parameter can be used two different ways to create a "Premium" version of a channel.
    • To create separate ad-supported and ad-free versions of a channel:
      1. Create two different Pkg files for a channel, one with VideoAdsEnabled set to "yes", and one with VideoAdsEnabled set to "no".
      2. Publish each Pkg file as a separate channel. The version with VideoAdsEnabled set to "yes" is the ad-supported version, and the version with VideoAdsEnabled set to "no" is the ad-free "Premium" version.
      3. Optionally use a video ad with its ChannelAppId parameter set to the App ID of the ad-free version channel in order to link to the ad-free version of the channel from within the ad-supported version of the channel.
      4. Optionally use a Programmable Button with Function set to "channel" in order to link to the ad-free version of the channel from within the ad-supported version of the channel.
      5. Use Roku's Billing Services or Instant TV Channel's Registration & Linking process to charge a subscription fee for the ad-free version.
      6. Both versions of the channel are maintained from the same Instant TV Channel instance. Only a single Instant TV Channel monthly fee is paid, even though there are two separate Roku channels.
    • To create a combined ad-supported and ad-free channel:
      1. Create a channel with VideoAdsEnabled set to "if not linked".
      2. Use Registration & Linking to protect a Programmable Button located somewhere conspicuous in the channel, for example in the top row of a Grid or near the beginning of a Horizontal List. Don't forget to set the button's RegistrationEnabled parameter to "True".
      3. Set the button's Function parameter to "back" or "top".
      4. Configure the Programmable Button's ListPosterUrl and ShortDescriptionLine parameters to indicate that the channel will be upgraded to a "Premium" ad-free version of the channel if the Button is selected.
      5. Configure the Registration & Linking Success parameters (found on the Instant TV Channel Registration page) to indicate to the subscriber that the channel has been upgraded and that video ads will no longer be displayed.
      6. When a subscriber first installs the channel onto a player, any video ads specified in the Content Editor will be displayed normally.
      7. When the subscriber completes the Registration & Linking process for the Programmable Button, then the channel is upgraded to a "Premium" ad-free version, and no video ads will be displayed.
  • AutomaticPlayErrorEnabled - This parameter determines whether or not an error message will be displayed if a problem is encountered when playing a video in an AutomaticPlay-enabled list. When set to "True", the UnavailableContent error message will be displayed and the viewer will need to click OK on the remote control if a video content item cannot be played, for example if the Stream Url is incorrect.

    If using Vidillion video ads in your channel, this parameter should be set to "True" in order to conform to Vidillion policy.

    The default value of AutomaticPlayErrorEnabled is "True".


Please see this Google Analytics for Roku Channels walk-through for information about how to monitor ad activity within your Roku channel.

Suggestions, comments, or questions about this Roku tutorial can be sent to .

Instant TV Channel is a cloud-based tool for Roku developers and content providers that shortens development time and eases maintenance after deployment.



Private Channel Code: ITVC
Check out Instant TV Channel by adding our demonstration channel to your Roku player, or watch the YouTube video.

Need help with your Roku?

We are unable to provide technical support for your Roku device or for channels not created using Instant TV Channel.

Please visit www.roku.com for assistance.



Instant TV Channel is not affiliated with nor endorsed by Roku Inc.