Programmable Buttons for Roku Channel Automation


This Instant TV Channel Help article is only applicable to Developer SDK Roku channels.

Instant TV Channel supplies Programmable Buttons that can be used in a Roku channel to provide automated capabilities beyond what is possible with standard poster and and menu buttons.

Programmable Buttons can be used anywhere in a List that content items like video streams or picture screens can be used. If the List has its AutomaticPlay parameter set to "once", "repeat", or "schedule", then the Programmable Button will be executed automatically when the Button's position in the List is reached during automatic playback or scheduling.

Programmable Buttons
Function Content Editor Icon Remote Control Button Description
back Identical to the BACK button found on newer Roku remote controls. Exits from the current List and displays the previous (parent) List. When used in a List that has AutomaticPlay set to "once", "repeat", or "schedule", this Button will exit from multiple nested AutoPlay or Schedule levels and return control back to the user.
channel None The current channel exits completely and the target channel specified by the ChannelAppId parameter is launched, or the user is provided with the opportunity to install the target channel if it is not already installed.
deeplink None Transfers control to a specific video or item in a different channel. The target channel must have deep-linking enabled, and you must provide the Content UID of a location or item in the target channel. For target channels developed using Instant TV Channel, see the three DeepLinking Theme parameters.
exit level None Exits from the current List to the previous (parent) List. When used in a List that has AutomaticPlay set to "once", "repeat", or "schedule", this Button will only exit a single level.
goto None Transfers control to a different part of the current channel. The target may be any item in the channel, for example a video, list, or grid. The target may be specified by copying and pasting its UID into the ContentUID parameter, or by dragging and dropping its icon from the content tree into the ContentName area.
home Identical to the HOME button found on the Roku remote control. The channel exits completely and the main Roku Home screen is displayed.
in-channel purchase None The user is prompted to enter their PIN number to purchase the product or video content item specified by the Identifier parameter. The price for the item is configured in the Roku Developer Account. If non-zero, the Expiration and Bitrate parameters determine how long the item purchase is valid for (a rental), and what the maximum allowed bitrate for the item will be.
in-channel upgrade None The user is prompted to enter their PIN number to upgrade to the channel specified by the "In-Channel Upgrade" setting in the Roku Developer Account. If the target channel specified by the ChannelAppId parameter is already installed then the target channel is launched instead. Usually the target channel is the same as the "In-Channel Upgrade" channel specified in the Roku Developer Account.
restart None The channel is exited and then restarted. Useful in the context of AutomaticPlay-enabled lists or Schedules to allow new content to be periodically reloaded.
search None The Search screen is displayed, allowing the user to search for a particular video. Requires the Theme SearchScope parameter to be set to something other than "off".
top None The current List is exited and the channel's top-level List is displayed.

The Channel Programmable Button performs several different functions depending on whether the button is in an AutomaticPlay-enabled List, whether the target channel (the channel being installed or jumped to) is already installed on the Roku player, and whether the HDChannelSetupUrl and SDChannelSetupUrl parameters are provided.

Multiple Channel Programmable Buttons can be included in a single channel, with each button installing or jumping to a different target channel. The Channel programmable button does not automatically delete the original channel from the Roku device when the target channel installation is successful.

Function = "channel"
  Not AutomaticPlay AutomaticPlay
  No ChannelSetupURL ChannelSetup URL No ChannelSetup URL ChannelSetup URL
 
Target Channel Already Installed
 
Jump to the target channel specified by ChannelAppId. Jump to the target channel specified by ChannelAppId. Jump to the target channel specified by ChannelAppId. Playback continues with the next content item in the AutoPlay List.
 
Target Channel Not Installed
 
Go to the Channel Store. Display the Setup image. If OK is pressed while the setup image is displayed, go to the Channel Store screen for the target channel specified by ChannelAppId. Go to the Channel Store. Display the Setup image. If OK is pressed while the Setup image is displayed, go to the Channel Store screen for the target channel specified by ChannelAppId.

The In-Channel Purchase Programmable Button performs the same function as a Springboard Purchase button and is used to allow a user to make an In-Channel Purchase from within the Roku channel.

The In-Channel Upgrade Programmable Button performs several different functions depending on whether the button is in an AutomaticPlay-enabled List, whether the target channel (usually the channel being upgraded to) is already installed on the Roku player, and whether the HDChannelSetupUrl and SDChannelSetupUrl parameters are provided.

Multiple In-Channel Upgrade Programmable Buttons can be included in a single channel, however all buttons must upgrade to the same target channel. The In-Channel Upgrade programmable button automatically deletes the original channel from the Roku device if the target channel installation is successful.

Function = "in-channel upgrade"
  Not AutomaticPlay AutomaticPlay
  No ChannelSetupURL ChannelSetup URL No ChannelSetup URL ChannelSetup URL
 
Target Channel Already Installed
 
Jump to the target channel specified by ChannelAppId. Jump to the target channel specified by ChannelAppId. Jump to the target channel specified by ChannelAppId. Playback continues with the next content item in the AutoPlay List.
 
Target Channel Not Installed
 
Go to the Upgrade PIN screen. If the PIN is correctly entered, delete the original channel, install the upgraded channel, and jump to the channel specified by ChannelAppId. Display the Setup image, then go to the Upgrade PIN screen. If the PIN is correctly entered, delete the original channel, install the upgraded channel, and jump to the channel specified by ChannelAppId. Go to the Upgrade PIN screen. If the PIN is correctly entered, delete the original channel, install the upgraded channel, and jump to the channel specified by ChannelAppId. Display the Setup image, then go to the Upgrade PIN screen. If the PIN is correctly entered, delete the original channel, install the upgraded channel, and jump to the channel specified by ChannelAppId.

For the In-Channel Upgrade to work correctly, the upgraded channel must be specified on the original channel's Roku Developer Account "Properties" page and the ChannelAppId parameter must be set to the App Id of the upgraded channel. During the upgrade process a PIN screen is displayed, permitting the subscriber to enter their Roku pin number to authorize their Roku account to be charged for the upgraded channel. When an upgrade is successful, then the upgraded channel is installed onto the Roku device and the original is simultaneously deleted from the Roku device.

A channel's App Id, usually a 5-digit number, can be found in the URL displayed your browser's address bar while viewing the channel in your Roku Developer or Owner Account. The App Id is not the same as the Vanity Access Code or the automatically generated Access Code. The App Id is placed in the ChannelAppId parameter for the Channel Programmable Button. The App Id allows the original channel to determine whether the target channel is already installed on the player and to locate the target channel in the on-screen Roku Channel Store.

Invalid or Missing ChannelAppId parameter When the Function parameter is "channel" and the ChannelAppId parameter does not contain a valid App Id of a target channel, then instead of displaying a channel store installation screen or jumping to a new channel, the current channel exits and the main Roku home screen is displayed.

When the Function parameter is "in-channel upgrade" and the ChannelAppId parameter does not contain a valid App Id of a target channel, then the upgrade PIN screen may still be displayed, even if the channel to be upgraded to is already installed. If the upgrade is successful, then the current channel will exit and the main Roku home screen is displayed.

The HDChannelSetupUrl and SDChannelSetupUrl parameters are intended to contain URLs that point HD (1280x720) and SD (720x480) versions of JPG images that describe the channel being installed by a Channel Programmable Button or upgraded to by an In-Channel Upgrade Programmable Button. If the image is not full screen (1280x720 or 720x480), then the image is centered over a solid background color specified by the ChannelSetupColor parameter. PNG transparency is supported.

The ChannelSetupTimer parameter determines how many seconds the HD or SD Setup image is displayed. It is usually set to 10 to 30 seconds if the Programmable Button is used within an AutomaticPlay List. When set to 0 seconds the Setup image is displayed until a remote key is pressed.



Need more help with the In-Channel Upgrade feature? See Upgrading a Roku Channel with the In-Channel Upgrade Feature for a quick walk-through!

Comments, suggestions, or questions about this Roku developer guide 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.