Roku Developer Help - Advertisements

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".
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.
Please contact for information about using VAST Ads with 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:

Click the Content link on the left side of the page to enter the Content Editor.
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.
Select New Ad from the pop-up context menu. A new Ad item will appear under the selected Horizontal List.
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.
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.
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.
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.
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:

Click the Content link on the left side of the page to enter the Content Editor.
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.
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.
In the lower portion of the screen, change the AdType parameter to one of the following options:
- "preroll", or "vast preroll" - The ad is played immediately after selecting a video content item from a menu, before the video content item is played.
- "preroll2", or "vast preroll2" - The ad is played immediately after the Preroll ad, before the selected video content item is played.
- "midroll", or "vast 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", or "vast midroll2" - The ad is played in the position(s) immediately after the Midroll ad.
- "postroll", or "vast postroll" - The ad is played in the position immediately after the selected content item is completely played.
- "postroll2", or "vast 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.
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.
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.
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 "3" and set the Weight parameter for the 70% ad to "7". Alternatively you could use "6" and "14", or any other combination where the ratio between the weights is 3:7. (See the warning below about weights and noticeable delays.)
- 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 "6" and set the Weight parameter for the other two ads to "7".
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.
If set to "True", the ad's AllowPause parameter will allow the viewer to pause the video ad.
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.
Set the ad's AdBuffering parameter to the message to be displayed while the video ad's stream is buffering.
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.
Change the Stream 1 Url parameter to point to your ad's video stream or to the VAST 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.
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".
Click the Theme link on the left side of the page to enter the Theme Editor.
Set the Theme Editor AdRepeatLimit parameter to specify the minimum amount of time between ad plays of each particular type (preroll, preroll2, midroll, etc).
Set the Theme Editor AdStartTime parameter to delay all ads from playing for a specified number of minutes after the channel is started.
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.
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:

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 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 Account. For example, the App ID for the Clutch Cargo Roku channel is 41985.
Insert the channel's App ID into the ad's ChannelAppId parameter.
Make sure that the Linking Ad contains instructions similar to "Press OK to install the channel."
If the remote control OK button 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.
The target channel can be installed (if not already installed) and launched from the intallation screen.
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 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, vast preroll, midroll, vast midroll, postroll, vast 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, vast preroll2, midroll2, vast midroll2, postroll2, vast postroll2,
AdMidrollInterval - If non-zero, this parameter is the interval in minutes before the beginning of the video and the first midroll, and between each subsequent midroll. This parameter is ignored if a video item contains its own non-zero midroll Position parameters.
AdMidrollStop - This parameter is the number of minutes remaining in a video after which no further midrolls may be played. This parameter can be used to prevent midrolls that would normally be played due to AdMidrollInterval from interrupting the closing credits of a video. If the video Length is 0 (is not set) then this parameter is ignored.
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 or VAST 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, vast preroll, midroll, vast midroll, postroll, vast postroll
AdStackingLimit DOES NOT affect following ad types, which always have a stacking limit of 1:
- selectable banner, preroll2, vast preroll2, midroll2, vast midroll2, postroll2, vast postroll2,
AdStackingLimitMidroll - This parameter is the maximum number of ads that will be played consecutively for a single midroll ad position. It applies only to 'midroll' AdTypes and has no effect on other AdTypes including 'midroll2'. If AdStackingLimitMidroll is 0 then AdStackingLimit will be used for 'midroll' AdTypes instead. AdPods containing multiple ads may cause AdStackingLimitMidroll to be exceeded.
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.
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.
The default value of AutomaticPlayErrorEnabled is "True".
If set to "False" and your CDN experiences an error that prevents videos from playing in an AutomaticPlay-enabled list, your channel might play 100% ads. This may cause Roku to suspend your channel for violating its policy regarding excessive video ads.
ShowDebugAdCid - This parameter is usually used in conjunction with ShowDebugIfSerialNumber to display ad-related information on the TV screen as an ad is playing. The information is displayed in the lower-right corner of the screen. The format of the ad-related information is:
ContentId: Ad's Content Id
AdType: Ad's AdType (X/Y:Z)
Key: Tag X of Y tags total, current tag adpod has size Z.

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 .