Programmable Buttons for Roku Channel Automation


This Instant TV Channel Help article is only applicable to Custom 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 May not behave as expected due to changes in Roku OS 12.0 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 a launch screen for the target channel specified by the ChannelAppId parameter is displayed, or the user is provided with the opportunity to install the target channel if it is not already installed.
deeplink None May not behave as expected due to changes in Roku OS 12.0 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 May not behave as expected due to changes in Roku OS 12.0 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.
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.

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. 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.


Subtitles

If you are considering subtitles for your Roku video content, our sister-site InstantSubtitles.com provides an easy-to-use and inexpensive solution. Click here for more information.




Access Code: ID1
Check out Instant TV Channel by adding our latest demonstration channel to your Roku player.



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