When BBM™ Connected applications instantiate BBMPlatformApplication, they must supply a UUID. The UUID is a 128-bit universally unique identifier for the application that must be 36 characters long and comply with the Microsoft® 8-4-4-4-12 format. Those numbers represent the number of characters in each sequence, separated by a dash. Here is an example of a UUID in the correct format: 4995d07c-13ee-42d1-92bb-90ba6ed33e1d. You can manually create a UUID or use an online UUID generator.

Using a UUID that doesn’t comply with the Microsoft 8-4-4-4-12 format can prevent your application from connecting to the BBM test/pre-production environment. If you do use an incorrect UUID format, you could receive an error of “Unable to connect to BBM. [App name] disconnected by RIM” when trying to connect. This only affects developers using the test/pre-production environment. Consumers who have purchased the application from the BlackBerry App World™ storefront will remain unaffected because BlackBerry App World will assign unique identifies to applications when they are put up for sale.

The UUID is used to uniquely identify an application in the test/pre-production environment. Once you upload the application to BlackBerry App World, it is no longer used. Changing your UUID allows you to perform tests of your application in isolation of one another.

BlackBerry® Widgets can be written entirely using web technologies like HTML and JavaScript®. However, a compiled BlackBerry Widget is simply a regular Java®-based BlackBerry® application. BlackBerry Widget developers must therefore be aware of an important requirement for deploying an application onto an actual BlackBerry® smartphone – code signing.

Has the following scenario happened to you?

After working tirelessly to create a beautiful looking BlackBerry Widget application, and having used a BlackBerry Smartphone Simulator to perform extensive testing on the many application features you have created, you eagerly load your application for the first time onto a real device. Anticipating a surreal and mind-blowing experience, you quickly search for your application’s icon to open it for the first time…

…and you get this:

Figure 1: Secure API prompt

I never saw that message during testing, what does this mean?

Don’t worry, you didn’t do anything wrong. This message simply means your application has not yet been assigned a RIM authorized code signature. The BlackBerry® Device Software has recognized that your application needs to use core BlackBerry® application program interfaces (APIs), but has not been granted the appropriate permission from RIM to do so, and therefore prevents your application from starting.

The reason you didn’t receive this message when loading your application onto the BlackBerry Smartphone Simulator is that the simulator does not perform this security check (this enables efficient deployment for testing purposes).

Why do BlackBerry Widgets need to be signed?

RIM must track the use of some BlackBerry APIs for security and export control reasons. If you use these controlled classes in your BlackBerry applications, your application must be signed using a signature key (provided by RIM) before you can load the application .cod files onto the BlackBerry smartphone.

APIs requiring signing are used during the compilation of BlackBerry Widget applications. If you have ever looked at the BlackBerry API reference document, you can see that any APIs requiring signing are indicated by a lock icon, or are otherwise noted as “signed”. Here is an example of one of the secured APIs used in packaging a BlackBerry Widget:

Figure 2: BlackBerry API Java Docs definition of secure API

How do I sign my BlackBerry Widget?

Setting up and signing a BlackBerry Widget application involves three steps:

1. Purchase your code signing keys online (available at no additional charge to Alliance members).
2. You will receive an email containing attached code signing keys, as well as instructions on where to save and how to configure them to be used on your developer machine.
3. Sign your application using the BlackBerry Signature Tool.

BlackBerry code signing keys must be purchased from and registered with RIM. These keys are uniquely assigned to a developer and are good for life. During the registration process, you will set a password that you provide each time you make a code signing request.

The identity of the registered user is recognized each time any of the signature keys are used to sign an application. As such, it is very important that they are not shared among developers, as the registered user assumes responsibility for the implementation and use of the application that is signed. Never publish these keys online, as you have no way of knowing how they may be used if downloaded.

Finally, through the use of the BlackBerry Signature Tool, you can sign your BlackBerry Widget using any of the following development tools:

• BlackBerry Widget Packager 1.0
• BlackBerry Web Plug-in for Microsoft Visual Studio 2.0
• BlackBerry Web Plug-in for Eclipse 2.0

Code signing using the BlackBerry Widget Packager:

If you are using the BlackBerry Widget Packager, this can be performed by providing the /g command line argument along with your signing password while you are packaging your widget:

Figure 3: Packaging and Signing a BlackBerry Widget

Code signing using BlackBerry Web Plug-in for Microsoft Visual Studio 2.0:

Your application can automatically be signed each time you build it using the BlackBerry® Web Plug-in for Microsoft® Visual Studio® 2.0 by changing the active solution configuration from ‘debug’ to ‘release signed’. You can change this configuration through the Configuration Manager menu item, found in Microsoft Visual Studio’s Build menu.

Figure 4: Changing active configuration through Configuration Manager

After making this configuration change, the next time you build your Widget, you will be prompted to enter your signing password:

Figure 5: Prompt to enter signing password

Code signing using BlackBerry Web Plug-in for Eclipse 2.0:

When building your BlackBerry Widget project using the BlackBerry® Web Plug-in for Eclipse® 2.0, you can right click on your project name in the Package Explorer window to open a contextual menu. At the bottom of the menu are two options for building, including one that will apply code signatures to your COD file(s).

Figure 6: Menu item for signing a BlackBerry Widget

After selecting this menu option, you will be prompted to enter your signing password, after which your application will be built, and signed.

Figure 7: Prompt to enter signing password

BlackBerry Signature Tool

When the BlackBerry Signature Tool signs your Widget application, you will see the following screen open. This screen displays the list of APIs requiring signing that are used by your application. Each required signature will be applied, and you will see the value in the “Status” column change from “Not Signed” to “Signed”:

Figure 8: BlackBerry Signing Authority Tool

This is great! Now what?

Take a deep breath and smile. Your BlackBerry Widget is now ready to be used and can now be deployed to your users through venues like BlackBerry App World™. Congratulations! In the comments, tell us about the latest BlackBerry Widget you developed.

Eclipse is a trademark of Eclipse Foundation, Inc. Microsoft and Visual Studio are trademarks of Microsoft Corporation. Java and JavaScript are trademarks of Sun Microsystems, Inc.

Figure 1 – Debug controls for Visual Studio

Figure 2 – Debug Controls for Eclipse

The plug-ins allow developers to set breakpoints and step through code just as with normal backend code.  The look and feel of the IDE’s when debugging your JavaScript is identical to stepping through .net or Java code.

Figure 3 – Debugging in Visual Studio

Figure 4 – Debugging in Eclipse

The plug-ins also enable developers to profile web applications.  There are a number of windows and tools that really maximize and optimize the web application performance.  They offer various tools to find out where any bottlenecks may be occurring when loading content and images, as well as displaying XML HTTP Response objects when you’re using AJAX on your website.

Another really cool feature of the plug-ins is that they enable remote website debugging, as if it were your own site running locally.  Web content is pulled down from a server (the Visual Studio internal server or the server running in Eclipse for local content), with the debugger then attached to those files.  This really helps when building web applications in teams, as you can easily pull down the content from someone else’s web page and debug.

More information on the plug-ins can be found on the BlackBerry® Developer Zone, with some videos and tutorials to help get started using the plug-ins.

This will definitely be an area of the BlackBerry web development toolset you’ll want to keep an eye on in the near future!

Download BlackBerry Plug-in for Microsoft Visual Studio v1.2

Download BlackBerry Web Development Plug-in for Eclipse 1.0

]]>