Packaging Roku apps

Publishing an app on the Streaming Store requires several items for the app, such as its source code, images, and fonts, to be "packaged" into a bundle that gets encrypted. This enables developers to publish apps while keeping all intellectual property safely encrypted. The process of “packaging an app” uses cryptographic hardware built into Roku devices and creates a package that can be safely distributed on Roku devices.

To package an app, you can use the Development Application Installer on your development device.

Since Roku OS 9.4, your development device must be both linked (to your Roku developer account), and connected to the internet, in order for package generation to succeed.

Key management overview

When you "sideload" your app to a Roku device during development, you have the option of packaging that app for distribution. Part of the packaging process is to encrypt the source code and data; the Roku device does this using its cryptographic hardware and a signing key stored on the device. The options for storing the key are either to generate a new key, or to "rekey" the device from an existing package.

Generating a signing key. You create a new signing key with the built-in genkey firmware utility that runs on the Roku device (accessible only through a Telnet session to a hardware port). In fact, you'll need to do that at least once before the Development Application (the developer Web page generated by the hardware) makes its Packager link clickable. genkey also generates a password that you'll need to keep safely recorded.

When to keep the same signing key. Let's say you end up submitting the package you created, and successfully publish it. Roku users start installing your app. If you need to make changes to your app, you simply follow the same packaging process again, this time being careful NOT to generate a new signing key, and submit the updated package. When your users intall the updated package but with the same signing key, it allows their Roku device to keep any existing registry data related to your app.

When to use a new signing key. If you are developing multiple apps, you would typically generate a new key for every app. If the key for each app is different, each will have its own registry on the user device. You could, instead, choose to use the same key for multiple apps you develop -- in this case, the registry information for all same-keyed apps is shared on the Roku user's device when they install more than one of your apps.

When to "rekey" from a previous signing key. What happens when you need to make changes to your app, but you have since generated a new key and your Roku development device no longer has the key associated with the app you packaged previously? You simply upload the previous package, enter its password, and select the Rekey operation (all on the Utilities page). The Roku device is now keyed to that package, so when you sideload the updated app, you can again package it using the original key.

Using the Rekey feature is also the way to share your work with another trusted developer. Providing them the package and its password lets them recreate the correct development environment on a different Roku device.

Before attempting to package an app

As noted in the Key management overview, an appropriate key must be stored on your Roku device before using it to package an app.

If you are

• Starting a new app development project: Follow the New key generation instructions.

• Modifying an existing app: Follow the Rekey instructions.

• Adding a new app to your lineup, but want user installations to share registry information among all of your existing apps: Follow the Rekey instructions.

• Setting up a new Roku device that has not yet been used for development: Follow the New key generation instructions to store an initial key on the device. Otherwise, the Packager link will not be active.

New key generation

Follow this procedure to generate a new key on your Roku development device. You generally need to do this when you

• set up a new Roku device for development use
• create a new app.

When you run genkey, you'll get the password and also its associated Developer ID (Dev ID). Save both, and keep the Dev ID associated with each package you generate so you can easily determine the correct password to enter when called for.

If you are modifying and repackaging source code for an existing app, follow the Rekey procedure.

Generate key using Windows

Windows developers will use a Telnet client such as PuTTY. Download and install PuTTY and then follow this procedure.

1. Open a Telnet session.

   a. Enter the IP address of your Roku player.

   b. Use "8080" for the Port.

   c. Click the Telnet radio button for the Connection Type.

   d. Click Open.

   

2. Run the genkey utility to create a signing key. Enter genkey at the command prompt and wait for the process to complete. If the prompt says “Command not recognized”, type it again.

   

Upon completion, a key has been successfully generated to sign packages.

Make note of the developer ID and password as it will be required anytime the code is updated and needs to be repackaged. It is a good practice to generate a new signing key for each app created unless you explicitly want to share registry information between apps.

3. Verify that the Packager link is active. On the Development Application, refresh the browser. If an app has been sideloaded, the Packager option should be available (refer to Packager Troubleshooting if not).

Generate key using Mac OSX / Linux

To generate a key to sign your package, OSX/Linux developers can use the built-in client through Terminal.

1. Open a Telnet session. Open Terminal and type: telnet <Roku-IP-address> 8080

   

2. Run the genkey utility to create a signing key. Enter genkey at the command prompt and wait for the process to complete. If the prompt says “Command not recognized”, type it again. Upon completion, a key has been successfully generated to sign packages.

   

Make note of the developer ID and password as it will be required anytime the code is updated and needs to be repackaged. It is a good practice to generate a new signing key for each app created unless you explicitly want to share registry information between apps.

3. Verify that the Packager link is active. On the Development Application, refresh the browser. If an app has been sideloaded, the Packager option should be available (refer to Packager Troubleshooting if not).

Packaging with the Development Application Installer

The steps below allow you to package your app for submission and eventual distribution.

First-time users: You must first enable its Packager utility option using the New key generation instructions.

1. Store the appropriate signing key on the Roku device. Either generate a new key (genkey) or retrieve a previously generated key from an existing package (Rekey). If the correct key is already stored, no action is needed. (Don't remember whether it's the correct key? Just look at the Dev ID on the Packager page to see if it matches the one associated with the package and password.)

2. Install (or “sideload”) the app on the Roku device. Use the Installer page of the Development Application to "sideload" the app to your Roku device. Refer to Developer environment setup about how to sideload apps.

   

3. Compress the sideloaded app using Cramfs or Squashfs. Compression is optional.

   • Cramfs is a file system format that loads faster than zip. Use cramfs for Roku OS versions 7.7 and lower. ?

   • Squashfs is a file format that saves flash storage space and it decompresses faster. Note that squashfs works only for Roku OS 8.0 and above. Make sure you set a minFirmware dependency of v8.0 or higher when uploading a squashfs pkg to the Streaming Store.

   

4. Package the sideloaded app.

   a. Click the Packager link on the upper right side of the screen to go to the Application Packager screen. (Not clickable? Refer to Packager Troubleshooting.)

   

   b. Check that the Dev ID matches the same developer ID that was generated with genkey.

   c. Enter an App Name/Version, and enter the Password created from the genkey utility.

   d. Click Package.

   e. Under Currently Packaged Application, a purple downloadable link for the signed package (.pkg file) is displayed. Click the link to download the package.

   

Rekeying from an existing package

When developing multiple applications, each might be signed with a different key. Rekeying is the process of retrieving an existing key from a package you previously generated (for which you have the password), and storing that key on a Roku development device.

To sign different differently keyed packages using a single Roku device, the device will have to be rekeyed appropriately for each package.

Start on the Development Application screen, and click Utilities to open the Package Utilities window.

1. Click Upload to select the signed package you would like to use to rekey the player.

2. Enter the password you originally got from genkey that matches the key used for the signed package.

3. Click Rekey.

   

4. A success message will be displayed when the process is complete as seen in the following window.

   

Packager Troubleshooting

Packager option not visible at all on upper right corner of Development Application Web page?

• You must sideload an app before Packager appears.

Packager option visible, but not clickable?

• You must use genkey to generate and store an initial signing key on a Roku device not previously used for development. Refer to New key generation for details.