BlackBerry
HTML5/WebWorks
Applications for the
BlackBerry® PlayBook™
Tablet
BlackBerry Academic Program
Module 4 - Testing, signing and deploying an application
v0.1
© 2012 Research In Motion Limited
Overview
© 2012 Research In Motion Limited
Overview of BlackBerry
WebWorks
3
Objectives
In this module, the learner will be introduced to:
-Why is signing an application important?
-Configuring a computer to sign an application
-Importance of backing up files
-How to sign an application
-How to deploy an unsigned application to a Tablet
- Creating and installing debug tokens
-Packaging and deploying an unsigned application to a Tablet
-Debugging an application on a Tablet using the Web Inspector™ tool on
the PlayBook browser
© 2012 Research In Motion Limited
Course Code
Prerequisites
For this module, the recommended prerequisite skills and areas of
knowledge are:
•Creation of the “Hello World” lab from Module 3
•Download and installation of the BlackBerry WebWorks SDK and
BlackBerry PlayBook Tablet Simulator (from Module 2)
•Experience using the Windows Command Prompt tool
4
© 2012 Research In Motion Limited
Why Sign Your Application?
© 2012 Research In Motion Limited
Course Code
Why Sign your Application?
• So you can distribute your application on BlackBerry AppWorld
•Allows RIM to issue your app’s unique identifiers and validate its
capabilities
•Binds a developer’s identity to the application as proof of authorship
•To help verify the authorship of the application to users and to the OS
6
© 2012 Research In Motion Limited
Course Code
Configuring a Computer to Sign
an Application
7
© 2012 Research In Motion Limited
Course Code
8
Configuring your Computer to Sign
an Application
•Before deploying an application on the BlackBerry PlayBook Tablet, a
developer’s computer may need to be configured
•Configuration allows the developer to request and install a debug token
•The configuration tasks are for first-time set-up and only need to be
performed once
© 2012 Research In Motion Limited
Course Code
Steps to Configure a Computer to
Sign Applications
•Request permission to sign your tablet application by completing the
web form at http://developer.blackberry.com/html5/signingkey.
Remember the PIN number you provided. The PIN protects
against usage of your Code Signing Keys by unauthorized
parties, so keep it safe.
9
© 2012 Research In Motion Limited
Course Code
10
Steps to Configure a Computer to
Sign Applications
•After the application is accepted, two .csj registration files will be sent by
email. Save these files to a location on your computer:
– client-RDK-xxxxxx.csj - This is the file that you use to sign your
applications and publish to the BlackBerry App World storefront
and load the application onto a physical device
– client-PBDT-xxxxx.csj - This file is used to generate a debug
token that you can use to test your application on a tablet. PBDT
stands for "PlayBook Debug Token“
•These files are used to install code signing keys. They can only be used
once
© 2012 Research In Motion Limited
Course Code
11
Steps to Configure a Computer to
Sign Applications
•Register with the RIM Signing Authority using the .csj registration file for
application signing.
•From the \bbwp\blackberry-tablet-sdk\bin folder located in the
BlackBerry WebWorks SDK installation folder, run the .bar signing tool to
enroll with the signing authority server.
© 2012 Research In Motion Limited
Course Code
Steps to Configure a Computer to
Sign Applications
•From the Command Prompt, type:
blackberry-signer -register -csjpin <csj pin>
-storepass <KeystorePassword> <client-RDKxxxxxx.csj file>
<client-PBDT-xxxxx.csj file>
This command creates the following files:
•author.p12
•barsigner.csk
•barsigner.db.
Please see Presenter Notes section for explanation of syntax
used above.
12
© 2012 Research In Motion Limited
Course Code
13
Importance of Backing up your Files
•The .csj files that were used to install the code signing keys can only be
used once.
•.csj files are disabled after a successful installation.
•Be sure to back up the code signing keys after they have been installed.
•Code signing keys can be restored to the original computer that they
were installed to or restored to another computer
© 2012 Research In Motion Limited
Course Code
14
Importance of Backing up your Files
•The files that need to be backed up are: author.p12, barsigner.csk and
barsigner.db. The barsigner files are located in the directories outlined
below:
• Windows® XP: %HOMEPATH%\Local Settings\Application
Data\Research In Motion
• Windows Vista® and Windows® 7:
%HOMEPATH%\AppData\Local\Research In Motion
•By default, %HOMEPATH% is C:\Documents and Settings on Windows
XP and C:\Users on Windows Vista and Windows 7
•To restore your code signing keys, copy the files back to the directory
outlined above
© 2012 Research In Motion Limited
Signing the Application
© 2012 Research In Motion Limited
Course Code
16
Signing the Application
•A developer can sign their BlackBerry HTML5/WebWorks application at
the same time it is compiled by using the following syntax with the
BlackBerry WebWorks Packager:
bbwp <archive_file> -g <KeystorePassword> -buildId <num> -o
<output_location>
For Example:
bbwp C:\myarchive.zip -g myKeystorePassword -buildId 10 -o
C:\myoutputdir
•Please see Presenter Notes section for explanation of syntax used
above.
© 2012 Research In Motion Limited
Course Code
Signing the Application
After an application is signed, a developer can publish it to the
BlackBerry App World storefront
Visit www.blackberry.com/appworld for more details
17
© 2012 Research In Motion Limited
Deploying an Unsigned
Application to the BlackBerry
PlayBook Tablet
© 2012 Research In Motion Limited
Course Code
19
Deploying an Unsigned Application
to a Tablet – Using Debug Tokens
•An unsigned application can be deployed to a BlackBerry tablet by using
a debug token.
•Debug tokens allow a developer to separate the process of application
creation and publication
•A developer can create and test an application then deliver the
application to their client/customer for signing and publication
•Running an unsigned application using a debug token allows developers
to avoid:
• changing the version number of the application
• accessing the internet
• exporting a release build of the application
© 2012 Research In Motion Limited
Course Code
20
Deploying an Unsigned Application
to a Tablet – Using Debug Tokens
•Debug token must be created by an individual or organization that has
permission to sign BlackBerry Tablet OS applications.
•To request permission to sign applications, complete the web form
•After a request to sign applications is approved, you will receive two csj
files via email
• One file allows you to configure your computer to sign apps
• One file allows you to create debug tokens
•When creating a debug token, you must specify a PIN for each tablet on
which tokens will be used
•A developer is limited to a total of 100 tablet PINs and each debug token
is valid for 30 days
© 2012 Research In Motion Limited
Course Code
Before Creating a Debug Token
Note: The developer’s computer must be configured to request debug
tokens before starting to test an unsigned application on a tablet.
For more information, see Signing your tablet application
21
© 2012 Research In Motion Limited
Course Code
22
Creating a Debug Token
•At a command prompt, navigate to the bin subfolder where you installed
the BlackBerry WebWorks SDK (C:\Program Files\Research In
Motion\....)
•Create a debug token for your device by using the following syntax and
values for the command line options:
blackberry-debugtokenrequest -storepass
<KeystorePassword> -devicepin <PIN tablet>
<debug_token_file_name.bar>
•For explanation of the syntax used, please see descriptors in Presenter
Notes below.
© 2012 Research In Motion Limited
Course Code
23
Installing a Debug Token
1.
On the BlackBerry PlayBook Tablet hardware, open the BlackBerry
Tablet options. (In the upper-right corner of the Home screen on
your BlackBerry tablet, press the gear icon )
2.
In the list of options, press Security
3.
In the list of security options, press Development Mode
4.
Press Upload Debug Token
5.
At a command prompt, enter the following command
blackberry-deploy -installDebugToken <path to
debug token> -device <IP address of tablet> password <tablet password>
© 2012 Research In Motion Limited
Course Code
24
Setting the Debug Token
After installing the debug token, edit the bbwp.properties file and
include the debug token path using <debug_token> tags. This file is
located in the bbwp\bin folder
<?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>
•A developer can now load their debug-enabled application on a
BlackBerry tablet device without having to sign it
© 2012 Research In Motion Limited
Course Code
25
Packaging an Application with a
Debug Token
•To run unsigned applications using a debug token, include the -d
parameter when compiling and packaging the application
•This parameter sets the developer mode for the debug token
•Debug token information is used only if both of the following are true:
• There is a <debug_token> element in “bbwp.properties” file and it
contains the full pathname of a valid debug token file
• Signing is not specified when you packaged your application
© 2012 Research In Motion Limited
Course Code
26
Packaging an Application with a
Debug Token
1. At a command prompt, navigate to the installation folder for the
BlackBerry WebWorks Packager. The file path may vary based on
where you installed the BlackBerry WebWorks Packager.
cd C:\Program Files\Research In Motion\BlackBerry
WebWorks SDK for TabletOS<x.x.x.x>\bbwp
2.
Compile the application by using the following syntax:
bbwp [drive:][path]archive -d [-o dir]
Example: bbwp C:\myapp\myarchive.zip -d -o C:\myapp\output
© 2012 Research In Motion Limited
Course Code
27
Packaging an Application with a
Debug Token
3. If successful, this process creates a .bar file in the folder
specified by the -o parameter.
4. The .bar file can now be deployed to the BlackBerry
PlayBook Tablet
© 2012 Research In Motion Limited
Course Code
28
Deploying an Application to the
Tablet
1.
Turn on Development Mode on the BlackBerry PlayBook tablet
2.
Obtain the IP address of the BlackBerry PlayBook tablet
3.
At a command prompt, navigate to the bin folder of the BlackBerry
WebWorks Packager installation folder.
4.
Deploy the application using the following syntax:
blackberry-deploy -installApp -password <tablet password> -device
<IP_address> -package <BAR file path>
Example:
blackberry-deploy -installApp -password playbook -device
111.111.111.11 –package C:\myapp\output\hw.bar
© 2012 Research In Motion Limited
Debugging Using the Web
Inspector Tool
© 2012 Research In Motion Limited
Course Code
30
Debugging using the Web Inspector
Tool
•The Web Inspector tool is a debugging and profiling development tool
for web content that is included as part of the WebKit rendering engine
•It includes a variety of features and capabilities, such as inspection,
profiling, console integration and more
•The Web Inspector tool is easily accessible for use with content loaded
directly within WebKit-powered desktop browsers, but not necessarily for
content loaded on a mobile device
•Developers can now use the Web Inspector tool to debug and profile
live web content and/or HTML 5/WebWorks applications running on a
BlackBerry PlayBook tablet or simulator
© 2012 Research In Motion Limited
Course Code
31
Enabling the Web Inspector Tool for
the BlackBerry Tablet OS Browser
1.
Select the “Privacy & Security” tab from the “browser options” screen
on your BlackBerry PlayBook tablet. (Look for the
icon in the
browser)
2.
Switch the “Enable Web Inspector” to “ON”
3. When prompted, enter your BlackBerry PlayBook tablet device
password
4. After entering you PlayBook password, the Web Inspector Tool will
be enabled
© 2012 Research In Motion Limited
Course Code
32
Enabling the Web Inspector Tool for
the BlackBerry Tablet OS Browser
© 2012 Research In Motion Limited
Course Code
33
Using the Web Inspector tool to load live
content from the BlackBerry Tablet OS
1.
Open a desktop web browser such as Chrome, Firefox, Safari or
Internet Explorer
2.
In the address bar, enter the IP address of the target BlackBerry
PlayBook tablet and port 1337 (e.g. http://198.168.1.7:1337).
3.
You will be prompted with a list of page titles for content that has
been loaded into memory by the Web Inspector tool (such as
browser content or a BlackBerry HTML5/WebWorks application).
4.
Click on any of the page titles to begin using the Web Inspector tool
to debug and profile your Web content.
© 2012 Research In Motion Limited
Summary and Next Steps
© 2012 Research In Motion Limited
Course Code
Summary
In this module the following topics were covered:
- Why is signing an application important?
- Configuring a computer to sign an application
- Importance of backing up files
- How to sign an application
- How to deploy an unsigned application to a Tablet
- Creating and installing debug tokens
- Packaging and deploying an unsigned application to a Tablet
- Using the Web Inspector tool in the PlayBook browser to debug
35
© 2012 Research In Motion Limited
Course Code
36
Additional Resources
Next steps include:
-Integrating additional features into the application such as:
- Geolocation, monetization and payment, advanced User Interface
(UI) elements
- Information on integrating these features into an app can be found
at the BlackBerry Jam website
Distributing an application via BlackBerry AppWorld
© 2012 Research In Motion Limited
Course Code
37
Legal Disclaimer
© 2012 Research In Motion Limited. All rights reserved. BlackBerry®, RIM®,
Research In Motion® and related trademarks, names and logos are the property
of Research In Motion Limited and are registered and/or used in the U.S. and
countries around the world. Adobe and AIR are trademarks of Adobe Systems
Incorporated.; Ripple is a trademark of tinyHippos, Inc.; VMware is a trademark
of VMware, Inc. ; Intel and Pentium are trademarks of Intel Corporation; AMD
Athlon is a trademark of Advanced Micro Devices, Inc; Windows is a trademark
of Microsoft Corporation.; Java is a trademark of Oracle America, Inc.; Ripple is a
trademark of tinyHippos, Inc.; Mac OS is a trademark of Apple Inc.; Web
Inspector is a trademark of Wintriss Engineering Corporation.; PhoneGap is a
trademark of Adobe Systems Incorporated .All other trademarks are the property
of their respective owners. This documentation is provided "AS IS" and without
condition, endorsement, guarantee, representation or warranty, or liability of any
kind by Research In Motion Limited and its affiliated companies, all of which are
expressly disclaimed to the maximum extent permitted by applicable law in your
jurisdiction.
37