Updating and Testing your Roku Channel

Updates are periodically released when new channel features are added to Instant TV Channel. Updates usually consist of new Brightscript code that is automatically built into your channel's Pkg file which you upload to your Roku Developer Account. After an update is applied to a channel, it's a good idea to test the updated channel before replacing the old channel. This is particularly important for channels in the public Roku Channel Store, and for monetized channels.

This Is Important - Please Read

This Instant TV Channel Help article is only applicable to Custom SDK Roku channels. These procedures do not apply to Direct Publisher Roku channels.

It is usually not a good idea to update a production channel until after you verify that the update will not affect the channel in any unexpected ways.

The directions below will walk you through the process of applying an update to a clone (a copy) of a channel, testing the updated clone, and then using the updated clone to publish to the production version of the channel.

If your Roku channel type is Unlimited or Commercial, this process will require that you temporarily purchase an Unlimited or Commercial upgrade for the clone. For the duration of this process you will have two channels, the original and the clone, upgraded to the same level. Within a day or two after the clone has been published it is safe to delete the original, and the unused portion of the original's monthly fee will be credited back to your Instant TV Channel account.

While waiting for your updated channel to be approved by Roku you will have two separate channels in your Instant TV Channel account: the pre-update version of the channel currently being used by your subscribers and the new updated version of the channel waiting to be approved. If these are "Unlimited" or "Commercial" channels then your Instant TV Channel account will be charged for both channels while waiting for Roku to approve the new update. In order to avoid the additional charges to your Instant TV Channel account, for minor updates you may wish to consider updating and re-submitting the production version of your channel instead of resubmitting the test clone.

When a new update is available for a channel, an Update button is present near the top of the Channels page. The following is a screenshot from the top section of the Channels page showing a selected channel with an update available. The channel is at update version 191 and the most recent update is version 194.

If no update is available for a channel, the Update button is not present on the Channels page. The following is a screenshot from the top section of the Channels page showing a selected channel with no update available. The channel is at update version 191.

If you have several channels, they do not have to all be at the same update version. If a channel does not require the new capabilities provided by an update, it is not necessary to update the channel to the newer version. Details about updates including descriptions of the new channel capabilities provided by each update are available on the Instant TV Channel News page.

Applying an update to a channel is very easy:

  1. Log into your Instant TV Channel account and click on the Channels link on the left side of the page.
  2. Click on the row containing the channel that you wish to update.
  3. Clone the channel by clicking the button in the channel's row, then click the Confirm button at the top of the page. This creates an identical copy of the channel that we will apply the update to.
  4. After the clone is complete, the row containing the clone should be highlighted.
  5. Click on the Update button near the top of the Channels page.
  6. A warning dialog appears and reminds you to clone the channel first. Since you have already done this, click Ok to proceed with the update.
  7. After the clone has been updated the Update button will disappear.
  8. Enter the Theme Editor by clicking on the Theme link on the left side of the Instant TV Channel page.
  9. Remove "(Clone)" from the end of the clone's Title.
  10. Because the original and the clone now have the same title, increment the clone's minor_version number so that you can distinguish between them.
  11. If the cloned channel's Type is "Clone requiring upgrade to Unlimited" or "Clone requiring upgrade to Commercial", click the button in the channel's row, then verify the credit card information and click the "UPGRADE TO UNLIMITED NOW" or "UPGRADE TO COMMERCIAL NOW" button. Unlimited and Commercial clones that are not upgraded are not packagable and will not be uploadable to your Roku Developer Account.

Before uploading the newly updated clone channel on top of the existing published channel, it should first be packaged and uploaded to your Roku Developer Account as a test channel. This will allow the update to be tested without affecting any existing subscribers of the channel.

To package the cloned channel:

  1. From the Channels page, package the clone by clicking the button in the clone's row.
  2. Click the Confirm Package button.
  3. After the clone has been packaged, a DOWNLOAD PKG link is displayed. Click on the DOWNLOAD PKG link and save the file somewhere on your computer. You will need to upload it to your Roku Developer Account in the next steps.

Before uploading the channel Pkg file to your Roku Developer Account, you'll need to have a Channel Store poster. This is the artwork that is displayed in the Roku "Home" screen that will be used to launch your test channel. The size of the Channel Store poster is exactly 540 pixels wide and 405 pixels high.

Use the following link to download a sample Channel Store poster from Instant TV Channel and save it to your computer:


Now we will upload the Pkg file to your Roku Developer Account as a Private channel in order to test it:

  1. Log into your Roku Account at http://my.roku.com
  2. Click the large purple Welcome (Your Name) box and then select Developer site.

Select the "Developer site" option.

  1. Under "My Channels", click the Manage My Channels link to advance to the "Manage Channels" page.

Select "Manage My Channels".

  1. Click the Add Channel button.

Click the "Add Channels" button.

  1. Select the Developer SDK option. This will create a Custom SDK channel.
  2. Select the Non-certified ("Private") option.
  3. Enter your test channel's name into the grey box.
  4. Click the Continue button to advance to the "Properties" page.

Select the "Developer SDK" & "Non-certified" options, and enter your channel's name.

  1. Select the Channel Store region in which you are located. Since this channel is only for testing you do not need to select all of the regions that the production version of the channel uses.

Select the Channel Store regions.

  1. Enter a Vanity Access Code. This is usually one or two words, with no spaces, that identifies your test channel. Write down this code, you'll need it to install the test channel later on.

Enter a "Vanity Access Code".

  1. For most channels the remaining settings on this page should be unchanged. If present, do not check any of the Required Features checkboxes, as this may prevent your channel from being available for certain models of Roku devices.
  2. Click the Continue button to advance to the "Channel Store Info" page.
  3. Provide a Description and Web Description.

    For example:
       Channel Description - Test Channel
       Web Description - Test Channel

  4. Click Add a poster and then locate and select the previously saved sample Channel Store poster. If you are using your own poster instead of the sample, the poster must be exactly 540 pixels wide and 405 pixels high.

Upload a Channel Store Poster.

  1. Select a "Preferred Category" for the Channel Store geographic region. This is the on-screen Channel Store category in which your channel would appear, if it was submitted and approved as a public channel. Since this is a private test channel, the selection made here has no effect (but is still required).

Select a Preferred Category.

  1. Click the Continue button to advance to the "Monetization" page.

    If your Roku Developer Account is not enrolled in Roku Billing Services then the "Monetization" page will not be available, and the "Package Upload" page will be displayed next.
  1. For most test channels you should leave "None of the above" selected and just click the Continue button to advance to the "Package Upload" page.

No Monetization

  1. Change the Minimum Firmware to "v7.7.2". Usually this will never need to be adjusted again. If Minimum Firmware is set too high, your channel will not be available on older model Roku devices.

    In the future, if you need to upload a new Pkg file, you must remember to always increment the Channel Version number shown above the Minimum Firmware setting. Channel Version is what all Roku devices use to determine whether or not a newer Pkg file containing an updated version of your test channel is available. If Channel Version is not incremented when you upload a new Pkg file, then Roku devices that already have your test channel installed will not be able to receive the updated version. If this is the first Pkg file, then Channel Version remains at "1.0" and cannot be changed.
  2. Click Upload a package and then locate and select the previously saved Pkg file.

Before Pkg Upload

After Pkg Upload

  1. Click the Continue button to advance to the "Preview and Publish" page.
  2. Click the blue Publish or Submit for Publishing button.


  1. Click on the Vanity Access Code link to advance to the "Add Channel" page.
  2. Click Add Channel to confirm that the test channel is to be added to your account and installed on your Roku device.
  3. If a "you must have at least one device" error message appears at this point, it means that you do not have any Roku devices associated with this Roku account.

    You can use the Vanity Access Code in any other Roku account to install the test channel.

Your test channel is now in your Roku account. If the channel is not automatically installed onto your Roku device, you can force your Roku device to install your channel immediately using your Roku remote control:

  1. Press the remote control HOME key.
  2. Use the remote control UP and DOWN keys and the OK key to select Settings from the on-screen menu.
  3. Select System from the on-screen menu.
  4. Select System update from the on-screen menu.
  5. Select Check now from the on-screen menu
  6. You should see a brief message flash on the screen about installing your new channel.
  7. Press the remote control HOME key again.

If your new channel installed successfully, it will be located directly above the dividing line in your Roku home-screen channel list.

You can temporarily set the test channel's ShowDebugVersion parameter on the Theme page to Yes in order to verify that you are viewing the test version of the channel instead of the production version. Remember to set the parameter back to No when testing is completed. Changing the ShowDebugVersion parameter does not require you to re-package the channel.

If you are not using a clone, changing the ShowDebugVersion parameter (or any other parameter!) will also affect the production version of your channel, and may be visible to your subscribers.

After thoroughly testing your Roku channel and verifying that it operates as expected, upload the same Pkg file to your Developer Account again, except this time overwrite the production channel:

  1. Log into your Roku Developer Account again.
  2. Click Manage My Channels.
  3. Locate and click the large icon for the channel you are updating.
  4. Click the Preview and Publish pull-down list and select Package Upload.
  5. Increment the Channel Version number, otherwise the updated channel will not be published.
  6. Click the Upload a package button, then locate and click on the recently updated channel's Pkg file. The name of your Pkg file should appear in the box where the Upload a package button was.
  7. Check the I'm not a robot box.
  8. Click the blue Save button.
  9. Click the blue Submit for Publishing button.
  10. If this is a public channel in the on-screen Roku Channel Store, it will not be published immediately. Instead, the channel must go through a shortened version of the Roku approval process again. To speed up the approval process, be prepared to briefly explain to Roku the changes that were made to the channel. For example: "Updated from Legacy SDK to SceneGraph. No content was changed."
  11. If you used a clone, do not delete the original version of the channel until at least 24 hours after Roku approves and publishes the updated version of the channel. This allows time for all subscribers to automatically receive the updated channel. After publication, the updated clone version of the channel becomes the production version of the channel and the old original version of the channel can be deleted.
  12. If you used a clone and the channel type is "Unlimited" or "Commercial", a pro-rated credit is issued to your Instant TV Channel account when the old original version of the channel is deleted.

- o -

Please see this Quick 5-Minute Guide for information about how to get started with Instant TV 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.

Access Code: ID1
Check out Instant TV Channel by adding our latest 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.

Please visit www.roku.com for assistance.

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