Setting up your tools

The BlackBerry WebWorks SDK provides a set of tools that you can use to create apps using web technologies.

System requirements

Before downloading and using the BlackBerry 10 WebWorks SDK, make sure that your system meets the following requirements:

Runtime environment Java Runtime Environment 1.6 (32-bit)
Processor Intel Pentium or AMD Athlon desktop processor 2 GHz or faster
Virtual environment BlackBerry 10 Device Simulator requires VMware Player on Windows or VMware Fusion on Mac OS X
Storage space 1 GB or more available hard disk space
RAM 2 GB RAM or more
Monitor Resolution of 1024 x 768 or higher
OS
  • Windows XP SP3 32-bit
  • Windows 7 32-bit or 64-bit
  • Mac OS X 10.6.4 or Latest Version
  • Ubuntu 12.04

BlackBerry 10 WebWorks SDK browser requirements

Note the following requirements if you intend to use the BlackBerry 10 WebWorks SDK web tool to configure and build your projects:

Supported browsers

The BlackBerry 10 WebWorks SDK web tool has been tested against the following browsers:

  • Google Chrome
  • Mozilla Firefox
  • Safari (version 6 or later)
  • Internet Explorer (version 8 or later)

Cookie settings

To use the The BlackBerry 10 WebWorks SDK web tool, your browser must accept cookies. All WebWorks project content that appears in the tool is stored in browser cookies. Deleting these cookies removes the project data from the web tool, but leaves the project folders intact. No project information is lost, but you have to import your projects to work with them in the web tool.

For more information about importing projects, see Importing a WebWorks 2.0 project into the SDK web tool.

Set up the tools

To set up the BlackBerry 10 WebWorks SDK, follow these steps:

  1. Download and install the BlackBerry 10 WebWorks SDK.

    If you are installing to Mac OS X Mountain Lion (10.8) or later, you will need to change you system preferences to successfully install the SDK. To change your system settings:
    1. Go to System Preferences > Security & Privacy.
    2. Change Allow applications downloaded from to Anywhere.

    If you are installing to Ubuntu, after downloading the installer, you'll need to make it executable by running the following commands:
    $ chmod u+x ./ BB10-WebWorks-SDK_<version>.bin
    $ ./BB10-WebWorks-SDK_<version>.bin

  2. Download and install the BlackBerry 10 Device Simulator. If you have a BlackBerry 10 device available for testing, downloading a simulator isn't required.
  3. Set up your computer for testing and signing by creating your BlackBerry ID token and then creating your developer certificate.

    The BlackBerry ID token is used to create the debug token that allows you to install and test an unsigned app on a BlackBerry 10 device. If you don't have a BlackBerry ID token, you cannot test your app on a device.

Set up your computer for testing and signing

Before you can test your app on a BlackBerry 10 device or sign it for distribution through BlackBerry World, you need to set up your computer for signing. There are two tasks to complete this process:

Using the BlackBerry ID token is new in BlackBerry WebWorks 2.0. If you are updating an app created using an earlier version of WebWorks, you can link your legacy token (barsigner.csk) to your new BlackBerry ID token (bbidtoken.csk) to maintain continuity. For more information, see Linking your BlackBerry ID token to a signing authority account.

Request your BlackBerry ID token

  1. Go to https://developer.blackberry.com/codesigning and login using your BlackBerry ID credentials.
  2. Enter and confirm the password you want to use to secure your BlackBerry ID token, and then click Get Token. The password is also used to create your developer certificate. Provide this password whenever you want to sign a completed app, or test an unsigned app on a BlackBerry 10 device.

    If you forget this password, we can't retrieve or reset it for you. To recover from a forgotten password, you must create another BlackBerry ID token, then recreate your developer certificate.

  3. Accept the license agreement and click Get Token.
After you finish:

The BlackBerry ID token is included in the keystore file you downloaded. The Signing Authority Service uses this token for authentication when you sign your app using the associated developer certificate. Signing your app helps verify the integrity and authenticity of your app to users and to the BlackBerry 10 OS. The BlackBerry 10 WebWorks SDK also uses the BlackBerry ID token to allow you to test your unsigned apps on a BlackBerry 10 device.

Your BlackBerry ID token is valid for one year. When it expires, you need to create a new one.

Create your developer certificate

To sign apps and create debug tokens, you must use your BlackBerry ID token to create a developer certificate. Each time you request a new BlackBerry ID token, you must create a new developer certificate.

  • Create your developer certificate using the SDK web tool

    1. On the Start menu, click BlackBerry >BlackBerry WebWorks <version>. A new browser window opens, displaying the BlackBerry 10 WebWorks SDK web tool.
    2. In the navigation panel, click Certificate.
    3. In the Location field, enter the full path to your bbidtoken.csk file.
    4. Click Add Signing Key. The signing key (bbidtoken.csk) is installed to the following location:
      • Windows XP: %HOMEPATH%\Local Settings\Application Data\Research In Motion
      • Windows Vista, Windows 7, and Windows 8: %HOMEPATH%\AppData\Local\Research In Motion
      • Mac OS: ~/Library/Research In Motion
      • Ubuntu: ~/.rim
      When the signing key has been installed, the Developer Certificate fields appear.
    5. In the Keystore Password field, enter your BlackBerry ID token password.
    6. In the Company name field, type the name of the organization you want to associate with the developer certificate.
    7. Click Create Certificate. The developer certificate (the author.p12 file) is created in the same location as your signing key.
  • Create your developer certificate from the command line

    1. Copy your BlackBerry ID token (bbidtoken.csk) to the following directory:
      • Windows XP: %HOMEPATH%\Local Settings\Application Data\Research In Motion
      • Windows Vista, Windows 7, and Windows 8: %HOMEPATH%\AppData\Local\Research In Motion
      • Mac OS: ~/Library/Research In Motion
      • Ubuntu: ~/.rim
    2. From the command line, navigate to the cordova-blackberry/bin/dependencies/bb-tools/bin subfolder of your BlackBerry 10 WebWorks SDK installation folder.
    3. Run the blackberry-keytool command to create your developer certificate (author.p12 file).
      blackberry-keytool -genkeypair -storepass <keystore_pw> -dname "cn=<company_name>"

      When you run this command, the author.p12 file is created in the same folder where you installed the bbidtoken.csk in Step 1.

      Check the table below for parameter details:

      Parameters Description
      -genkeypair

      Generates a key pair that consists of a private key and a public key.

      -storepass <keystore_pw>

      Specifies the password that is used to control access to the keystore, which is your BlackBerry ID token password.

      -dname

      Specifies the name to associate with the certificate that the tool creates.

Using a proxy server from the command line

During the creation of a debug token or during the signing process, your computer needs connects to the Signing Authority Service. If your computer connects to the Internet through a proxy server, you may need to add some additional options to your commands to allow the tools to communicate with the Signing Authority Service. These options are appended to the blackberry-signer or blackberry-debugtokenrequest commands.

The following table describes the proxy options available:

Options

Description

-proxyhost <host>

The network server that provides the proxy service. The value can be an IP address or a fully qualified domain name.

-proxyport <port>

The port number on your proxy server through which blackberry-signer or blackberry-debugtokenrequest should communicate with the Signing Authority Service.

-proxyusername

<user name>

Your username on the proxy server, if your proxy server requires authentication.

-proxypassword

<password>

Your password on the proxy server, if your proxy server requires authentication.

Signing an app with a proxy server

To sign your app with a proxy server:

  1. From the command line, navigate to the cordova-blackberry/bin/dependencies/bb-tools/bin subfolder of your BlackBerry 10 WebWorks SDK installation folder.
  2. Run the blackberry-signer command, and append the proxy options to the standard blackberry-signer options. You would use the following syntax:
    blackberry-signer -proxyhost <host> -proxyport <port> -bbidtoken <bbid_token_file> 
          –storepass <keystore_pw> <BAR_filename>

    The following table describes the standard blackberry-signer options used above:

    option

    Description

    -bbidtoken <bbid_token_file>

    Your BlackBerry ID token .csk file. For information on how to request this file, see Request your BlackBerry ID token.

    -storepass <keystore_pw>

    The keystore password. You define this password when you request your BlackBerry ID token.

    <BAR_filename>

    The file name of the signed .bar file.

For example:

blackberry-signer -proxyhost 192.168.1.1 -proxyport 80 -bbidtoken bbidtoken.csk 
      –storepass MySecretPassword1 MyApp.bar

Creating a debug token with a proxy server

To create a debug token with a proxy server:

  1. From the command line, navigate to the cordova-blackberry/bin/dependencies/bb-tools/bin subfolder of your BlackBerry 10 WebWorks SDK installation folder.
  2. Run the blackberry-debugtokenrequest command, and append the proxy options to the standard blackberry-debugtokenrequest options. You would use the following syntax:
    blackberry-debugtokenrequest -proxyhost <host> -proxyport <port>  
        -storepass <keystore_pw> -devicepin <device PIN> 
        <debug_token_file_name.bar>

    If you have multiple devices you want to test on, list their PINs in a file, and use the following command:

    blackberry-debugtokenrequest -proxyhost <host> -proxyport <port>  
        -storepass <keystore_pw> -devicepinlist <device_PIN_list_file> 
        <debug_token_file_name.bar>

    The following table describes the standard blackberry-debugtokenrequest options used above:

    option

    Description

    -storepass <keystore_pw>

    The keystore password. You define this password when you request your BlackBerry ID token.

    -devicepin <device PIN>

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

    -devicepinlist <device_PIN_list_file>

    The name of a file containing the PINs of the BlackBerry 10 devices on which you want to install this debug token. For example, the contents of a file called device_PINs.txt might appear as follows:

    12G34H56 2K672HVP 221Q2958

    You would specify it like using the following syntax:

    -devicepinlist device_PINs.txt
    <debug_token_file_name.bar>

    The file name of the debug token .bar file.

    The debug token file must end with .bar. If you specify the name of an existing file, blackberry-debugtokenrequest deletes the existing file before creating the debug token.

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

  3. Install the debug token on a BlackBerry 10 device:
    1. Determine the development IP address. You can view the development IP address on your device by opening Settings>Security and Privacy>Development Mode.
    2. From the command line, navigate to the cordova-blackberry/bin/dependencies/bb-tools/bin subfolder of your BlackBerry 10 WebWorks SDK installation folder.
    3. Run the blackberry-deploy command to install the debug token on your device:
      blackberry-deploy -installDebugToken <path_to_debug_token> 
          -device <development_IP_Address> -password <device_pw>

Last modified: 2014-04-10

comments powered by Disqus