Using debug tokens

You can run unsigned applications on a BlackBerry 10 device or BlackBerry PlayBook tablet by using a debug token. Debug tokens allow an organization to separate the process of application creation and publication. A developer can create and test an application using a debug token, then deliver the application to their supervisor or their client for signing and publication.

When you run an unsigned application using a debug token, you can avoid:

changing the version number of your application
accessing the internet
exporting a release build of your application

A debug token must be created by an individual or organization that has permission to sign BlackBerry 10 OS or BlackBerry PlayBook OS applications. To request permission to sign applications, complete the web form at http://developer.blackberry.com/html5/signingkey. After your request is approved, you receive two CSJ registration files by email. One file allows you to configure your computer to sign applications; the other file allows you to create debug tokens. Each file arrives in a separate email with information about the purpose of the file attached.

After you receive your CSJ registration files, you can configure your computer to create debug tokens. When you create a debug token, you specify the PIN for each device on which the token can be used. You can distribute the debug tokens you create to developers to install on those devices, or install them yourself. You are limited to a total of 100 device PINs across all of your debug tokens that are currently active. If you create debug tokens that address 100 PINs, you must wait for some of your debug tokens to expire before you create more.

Debug tokens are valid for 30 days. When a debug token expires, the BlackBerry 10 OS or BlackBerry PlayBook OS no longer allows unsigned apps that rely on that token to run.

Create a debug token

Before you begin: Make sure you requested a debug token signing file (client-PBDT-xxxxx.csj) and registered it. If you haven’t requested and registered code signing keys, see Set up for signing BlackBerry 10 apps (if you’re testing a BlackBerry 10 app) and Set up for signing tablet apps (if you are testing a BlackBerry PlayBook app).

At a command prompt, navigate to one of the following folders:
- dependencies\tools\bin in BlackBerry 10 WebWorks SDK
- blackberry-tablet-sdk\bin in BlackBerry WebWorks SDK for BlackBerry Tablet OS
Create a debug token for your device by using the following syntax and values for the command line options:
```
blackberry-debugtokenrequest -storepass <KeystorePassword> 
    -devicepin <device PIN> <debug_token_file_name.bar>
```

Option	Value
`KeystorePassword`	The password you defined when you created your developer certificate
`device PIN`	The PIN of the BlackBerry device on which you want to install this debug token.
debug_token_file_name.bar	The file name of the debug token you want to create. The debug token file must end with .bar. If you specify the name of an existing file, the `blackberry-debugtokenrequest` tool deletes the file before the tool creates the debug token. If you specify a path that does not include a file name, the `blackberry-debugtokenrequest` tool deletes the directory you specify and does not create a debug token.

Option

Value

KeystorePassword

The password you defined when you created your developer certificate

device PIN

The PIN of the BlackBerry device on which you want to install this debug token.

debug_token_file_name.bar

The file name of the debug token you want to create. The debug token file must end with .bar. If you specify the name of an existing file, the blackberry-debugtokenrequest tool deletes the file before the tool creates the debug token.

If you specify a path that does not include a file name, the blackberry-debugtokenrequest tool deletes the directory you specify and does not create a debug token.

You can now distribute or install the debug token you created.

Install a debug token

On the home screen of the BlackBerry device, tap the settings icon to open the Options screen.
In the list of options, select Security.
In the list of security options, select Development Mode.
At a command prompt, navigate to one of the following folders:
- dependencies\tools\bin in BlackBerry 10 WebWorks SDK
- blackberry-tablet-sdk\bin in BlackBerry WebWorks SDK for BlackBerry Tablet OS
Type the following command:
```
blackberry-deploy -installDebugToken <path to debug token> 
    -device <IP address of device> -password <device password>
```
After the command executes, the result::success message displays indicating that you successfully installed the debug token.

Set the debug token

For BlackBerry 10 OS apps

Create a copy of your debug token .bar file and name it debugtoken.bar.
Move the debugtoken.bar file to the root of the BlackBerry 10 WebWorks SDK installation folder. The installation folder location varies based on your operating system:
- Windows XP: C:\Program Files\Research In Motion\BlackBerry 10 WebWorks SDK <version>
- Windows 7: C:\Program Files (x86)\Research In Motion\BlackBerry 10 WebWorks SDK <version>
- Mac OS: /Developer/SDKs/Research In Motion/BlackBerry 10 WebWorks SDK <version>
Once you've moved and renamed the debug token file, you do not have to do anything else to set the debug token.

For PlayBook OS apps

In the BlackBerry WebWorks SDK for BlackBerry Tablet OS installation folder, navigate to the bbwp\bin folder.
Using a text editor, open the bbwp.properties file.
Add the path to the debug token file by using <debug_token> tags.
```
<debug_token>path to debug token file</debug_token>
```

Example: bbwp.properties file with path to debug token file

<?xml version="1.0" encoding="UTF-8"?>
<wcp>
<additional>-quiet</additional>
<java>C:\Program Files\Research In Motion\BlackBerry WebWorks SDK for TabletOS 2.1.0\jre</java>
<wcp_template>AirAppTemplates</wcp_template>
<air_template>AirAppTemplates</air_template>
<tablet_sdk>C:\Program Files\Research In Motion\BlackBerry WebWorks SDK for TabletOS 2.1.0\bbwp\blackberry-tablet-sdk</tablet_sdk>
<extension_repository>ext</extension_repository>
<debug_token>C:\my_debug_token.bar</debug_token>
</wcp>

You can now load your debug-enabled application on a BlackBerry device without having to sign it.

Packaging your application with a debug token

To run unsigned applications using a debug token, include the -d parameter when you compile and package your application. This parameter sets the developer mode for the debug token.

At a command prompt, navigate to the installation folder for the BlackBerry WebWorks Packager.
Compile the application by using the following syntax:
```
bbwp [drive:][path]archive -d [-o dir]
```
Windows example:
```
bbwp C:\myapp\myarchive.zip -d -o C:\myapp\output
```
Mac OS example:
```
./bbwp ~/myapp/myarchive.zip -d -o ~/myapp/output
```
During the compilation process, the BlackBerry WebWorks Packager displays multiple messages, and indicates a successful compile if the application archive contains no errors.
If successful, this process creates a .bar file in the folder specified by the -o parameter. If no -o parameter is specified, the .bar file is created in a subfolder named "bin" that's located in the same folder location as the archive file.

You can now deploy your application .bar file to a BlackBerry device.

Deploying your application to the BlackBerry device

Turn on Development Mode on your device.
Obtain the IP address of your device.
At a command prompt, navigate to the dependencies\tools\bin folder for the BlackBerry 10 WebWorks SDK, or to the blackberry-tablet-sdk\bin folder for the BlackBerry WebWorks SDK for BlackBerry Tablet OS.

Deploy the application using the following syntax:

blackberry-deploy -installApp -password <device password> -device <IP address of device> -package <BAR file path>

Example:

blackberry-deploy -installApp -password bbdevpw -device 192.0.2.1 -package myApp.bar

where bbdevpw is the password, 192.0.2.1 is the IP address, and myApp.bar is the .bar file.