Introduction

A Client Package is an installer that is specifically designed to fit in for a given target handset.

For a BlackBerry device one will obtain a .jar and a .jad files.

Client package creation is a 3-step process:

• Configuration
• Packaging
• Signing

Prerequisites

Application configuration can be accessed from the Service > Service Settings > Application configuration tab in Workbench Developer.

In order to customize an application one will need to specify:

• Standard settings, i.e. application name, application version, application icon (see requirements below)...
• (optional) Advanced settings, i.e. SMS Listener activation and any other .jad parameters
• (optional) Signature (see procedure below), i.e. all parameters (keys, password...) to get the application signed

Icon

The icons can be in either GIF or PNG format. Depending on the device firmware version and default theme, the size of the icon may change. Depending on the firmware version the icon will be resized or cropped. The Icon Design Guide lines can be found here . From our experience a 45x45 PNG image is suitable for most devices.

Signing

On BlackBerry devices, the signing procedure requires a signature key and a certificate obtained from BlackBerry (20 USD).

Obtaining the keys

The first step is to register to BlackBerry website and purchase the keys. Registration page can be found here: https://www.blackberry.com/SignedKeys.one  will have to pay a one time fee (20 USD). Follow the instructions and take care to remember important information, such as the PIN code which is requested.
Once one has purchased the keys, he will receive by email 3 files with .csi extension (client-RBB-xxxx.csi, client-RRT-xxxx.csi, client-RCR-xxxx.csi).

Setting up the environment

[Download] and install the BlackBerry JDE, then install the .csi files:

• Save the 3 .csi files to the BlackBerry JDEbin directory, where the signature tool is located.
• Open a DOS prompt and execute from that directory the following command (replace "client-RRT-000000000.csi" to match one of the .csi file names): javaw -jar SignatureTool.jar client-RRT-000000000.csi
• This will generate the "yes I want to register" prompt described in the developers guide. Follow the procedure to register.
• Execute the same command for the remaining 2 files to register them as well. One will be prompted for the new password and the PIN either requested or assigned by RIM at the time one applied for the keys.

Finally, to check if the keys have been installed, one should now have the sigtool.db, sigtool.set and sigtool.csk files in the /bin folder.

Packaging

Wizard

Application packaging can be accessed from the Service > Create Client Packages menu option in Workbench Developer.

In order to package an application one will need to specify:

• Targeted device(s), i.e. select all devices the application is supposed to support
• Application configurations, i.e. all defined configurations (as defined in the Prequisites section above) can be set / updated here
• Rich Media Server information, i.e. required parameters to access Streamezzo Rich Media Server instance if any (i.e. if the application contains server-side scenes)
• Output, i.e. output folder and pattern (this last parameter is mandatory in case multiple devices are selected for packaging, as each application installer will need to be dumped in a separated and identified folder, inside the output folder)

Once the "Finish" button is pressed, all requested client packages will be generated for each selected device.

If specified in the configuration, the application will be automatically signed.

The progression of the client packages creation can be followed in the Client packages creation view.

Once a client package has been created, its output folder can also be accessed from here.

Ant task

Some operations as accomplished above with the wizard can be performed relying on an Ant task, which is usually comfortable to reiterate a client package creation in a given configuration (i.e. selected devices, configuration, output...) in a 1-click operation.

In order to do this one can follow those steps:

• Create an Ant build file
• Open it in the Workbench Developer editor
• Right-click in the editor area and select Wizards > Create client package target
• Follow the same wizard steps as detailed above; once the "Finish" button is pressed, the Ant build file will be automatically filled accordingly (instead of really creating the client package(s))

The obtained Ant task looks like this:

<?xml version="1.0" encoding="UTF-8"?> My description

The Ant build file can then be dumped in the Ant view and executed from here.

The progression of the running Ant task can be followed as successive logs in the Console, ending with message "BUILD SUCCESSFUL" in case it succeeded.

In addition to this one may need to add the signing procedure, which can also be operated relying on Ant.

In order to be installed on a BlackBerry device, the jar file will be split into multiple .cod files. This is done with the rapc.exe tool (see documentation here). Then the signature can be applied.

Such Ant script looks like this:

Distribution

Once properly packaged and signed, a BlackBerry application can be distributed OTA by any applicable mean, i.e. FTP, Provisioning Server... or via the BlackBerry App World.

The application shall be installed via the .jad file in order to have all specified jad parameters taken into account and for the singature to be checked.