Roku Developer Help - Programmable Buttons

Programmable Buttons for Roku App Automation

Important Notice

Many Programmable Button functions no longer work as documented. Unfortunately, Roku has been gradually removing functionality within the device operating system, apparently to retain more control over advertising and app promotion. While we understand Roku's business considerations, this decision has been disappointing for developers who relied on these features to provide useful functionality to their users.

For example, it is no longer possible to install or jump to one app from within another app to advertise or promote it. Developers must now purchase advertising contracts with Roku to direct traffic to their apps, where previously they could cross-promote their own content freely.

Other Programmable Button functions may also be restricted or non-functional on current Roku OS versions. We regret that these limitations are outside our control. Please test thoroughly on current devices before relying on any Programmable Button functionality.

Instant TV Channel supplies Programmable Buttons that can be used in a Roku app to provide automated capabilities beyond what is possible with standard poster 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	May not behave as expected due to changes in Roku OS 14.0 The current app exits completely and a launch screen for the target app specified by the AppId parameter is displayed, or the user is provided with the opportunity to install the target app 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 app. The target app must have deep-linking enabled, and you must provide the Content UID of a location or item in the target app. For target apps 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 app. The target may be any item in the app, 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 app 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 SKU 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 app 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 app'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 app (the app being installed or jumped to) is already installed on the Roku player, and whether the AppSetupUrl parameter is provided.

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

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

The In-App Purchase (Roku Pay) Programmable Button

performs the same function as a Springboard Purchase button and is used to allow a user to make a Roku Pay Purchase from within the Roku app.

An app's App Id, usually a 5-digit number, can be found in the URL displayed in your browser's address bar while viewing the app 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 AppId parameter for the Channel Programmable Button. The App Id allows the original app to determine whether the target app is already installed on the player and to locate the target app in the on-screen Roku Streaming Store.

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

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

The AppSetupUrl parameter is intended to contain a URL that points to a 1280x720 JPG image that describes the app being installed by a Channel Programmable Button or upgraded to by an In-App Upgrade Programmable Button. If the image is not full screen (1280x720), then the image is centered over a solid background color specified by the AppSetupColor parameter. PNG transparency is supported.

The AppSetupTimer 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-App Upgrade feature? See Upgrading a Roku App with the In-App Upgrade Feature for a quick walk-through!

Comments, suggestions, or questions about this Roku developer guide can be sent to .