Mindon.IDEA

Air off, Mind on ~ / Javascript+Golang, Sci, Health… /

Make a Blackberry 10 WebWorks Application

BlackBerry 10 from RIM ( Research In Motion ) is comming.

BlackBerry Developer, we could see the bb10 provides a variety of options to develop an app: C/C++ Native SDK, HTML5 WebWorks, Action Script with Adobe AIR, Java in Android Runtime, or with Blackberry Java.

What a platform! ( How’s its performance? )

Here I will focus on the HTML5 WebWorks app, what kind of problems you need to face. ( All base on windows env. )

Prepareations

Following SDK and tools you could find here.

  • Ripple emulator

It’s a Chrome Extension to help you previewing the webworks app UI.

  • WebWorks SDK

Remember to append the path %WebWorksSDK_HOME%\dependencies\tools\bin to the Env variable PATH.

Here the %WebWorksSDK_HOME% is the root folder you installed your WebWorks SDK. you could set it as an Env. Variable.

  • BlackBerry 10 Dev Alpha Simulator

You need VMWare Player to run the Simulator.

  • Native SDK (Optional: You will need this for an Native WebWorks Extension )

http://developer.blackberry.com/native/beta/download/

  • Android App Verify and Repackage tools (Optional: Try repackage some android app you like into bb10 )

http://developer.blackberry.com/android/tools/

Ripple Emulator

  • Remember to “Start Ripple Services” first

  • You need to serve your html5 webworks app folder as website - simplest as localhost. ( you make choose Nginx or some simple green web servers )

  • Visit http://localhost/, and “Enable” the Ripple Mission. ( It will crashes your Chome sometimes ).

WebWorks SDK

  • It contains a node.exe for the SDK: *%WebWorksSDK_HOME%\dependencies\node*, you could get the latest node.exe from http://nodejs.org/ :-)

  • The package tool bbwp is %WebWorksSDK_HOME%\bbwp.bat, which content is: “%~dp0dependencies\node\node.exe” “%~dp0lib\bbwp.js” %*

    full command will be like: %WebWorksSDK_HOME%\dependencies\node\node.exe %WebWorksSDK_HOME%\lib\bbwp.js mydemo-app.zip

  • WebWorks App use JNEXT to run the HTML5 as an app ( JNEXT: http://jnext.org )

BlackBerry 10 Dev Alpha Simulator

  • At first, you will be drived crazy by its full size screen in VMWare Player.

  • A “Controller” tool installed with the simulator could help you manage the screen size in the vmware player:

1) Find the menu “Connection / connect”, you need the IP left bottom of the bb10 simulator, some like “192.168.111.128”, NOT the 169.254.0.1 which is for device not the simulator.

2) After success connect, find the menu “Device / Change Zoom Level” – It could help you to resize the simulator screen to fit your host screen size.

  • Other interest controll options could be found in the “Controller” tool. ( find it in your windows’ shortcut from Start / All Programs / BlackBerry 10 Simulator , or in the VM folder directly )

  • Want to install your app into the simulator? You need to turn on “Development Mode” in BB10 “Settings / Security and Privacy / Development Mode”

  • The IP setting in the “Development Mode” is for device only

  • Each time the device restart, you need to turn on the “Development Mode” again ( You won’t face this problem in a simulator )

BB10 Device Software Update

Before Updating the BlackBerry 10 Dev Alpha Device Software, you need to

Start the WebWorks App Development

You could find more sample and details from blackberry’s github project

config.xml

Chose those permisions and features your app needs:

Permissions

  <rim:permissions>
    <rim:permit>read_device_identifying_information</rim:permit>
    <rim:permit>record_audio</rim:permit>
    <rim:permit>access_location_services</rim:permit>
    <rim:permit>bbm_connect</rim:permit>
    <rim:permit>access_pimdomain_messages</rim:permit>
    <rim:permit>access_pimdomain_contacts</rim:permit>
    <rim:permit>access_pimdomain_calendars</rim:permit>
    <rim:permit>access_pimdomain_notebooks</rim:permit>
    <rim:permit>post_notifications</rim:permit>
    <rim:permit>access_sms_mms</rim:permit>
    <rim:permit>access_shared</rim:permit>
    <rim:permit>access_internet</rim:permit>
    <rim:permit>read_geolocation</rim:permit>
    <rim:permit>use_camera</rim:permit>  
    <rim:permit>run_native</rim:permit>
    <rim:permit>run_when_backgrounded</rim:permit>
  </rim:permissions>

Orientation

  <rim:orientation mode="auto"/>

Splash

  <rim:splash src="splash.jpg" />

Features

  <feature id="blackberry.app.orientation">
    <param name="mode" value="portrait" />
  </feature>

  <feature id="blackberry.app">
    <param name="backgroundColor" value="0xFFFFFF00" />
  </feature>

  <feature id="blackberry.app.event"/>
  <feature id="blackberry.invoke"/>
  <feature id="blackberry.app" />
  <feature id="blackberry.ui.dialog" />
  <feature id="blackberry.ui.Spinner" />
  <feature id="blackberry.push" />
  <feature id="blackberry.message.sms" />
  <feature id="blackberry.ui.menu" />
  <feature id="blackberry.identity" />

Access

   <access uri="*" subdomains="true" />

webworks.js

You need this js in your HTML5 code!

  • Latest version of webworks.js could be found in *%WebWorksSDK_HOME%\Framework\clientFiles*

  • DO REMEMBER copy and include it as your HTML5 webworks app resources before calling any Blackberry API from your javascript code.

bbUI.js

https://github.com/blackberry/bbui.js

The objective of the bbUI toolkit is to provide a BlackBerry® User Experience and Design Language for HTML5 applications using the BlackBerry WebWorks framework.

  • Try to use this for your demo. But sure you could use your own code to do these things.

  • bbUI.js is using iScroll for its scroller effect from http://cubiq.org/iscroll-4

Shell Script help to Package and Install your webwoks app to BB10 simulator

Requirement NOTICE:

1) you need install 7z and append its 7z.exe path to Env. variable PATH.

2) set the WebWorksSDK_HOME env. variable for your webworks sdk installed real path.

3) change the -device 192.168.111.128 to your simulator IP

4) Update the device password, if you don’t have one, remove the -password your-device-password

Then save following code as bb-pack-install.cmd, then drag-drop your app folder on on it.

@call :reverse "%*"

FOR /F "tokens=1 delims=\" %%G IN ("%reverse.result%") DO @set adir=%%G

@call :reverse "%adir%"

echo ## Package and Install ## -- %reverse.result%
echo -----------------------------------

@if exist simulator\%reverse.result%.bar (
  del simulator\%reverse.result%.bar
)
@if exist device\%reverse.result%.bar (
  del device\%reverse.result%.bar
)

@if not exist %~dp0%reverse.result%.zip (
  cd %reverse.result%
  7z.exe a -tzip %~dp0%reverse.result%.zip ".\*" -r
  cd %~dp0
)

@%WebWorksSDK_HOME%\dependencies\node\node.exe %WebWorksSDK_HOME%\lib\bbwp.js %~dp0%reverse.result%.zip

echo -----------------------------------

@blackberry-deploy -installApp -password your-device-password -device 192.168.111.128 -package simulator\%reverse.result%.bar

pause

:reverse
  @echo off
  set reverse.tmp=%~1
  set reverse.result=
  :reverse.loop
    set reverse.result=%reverse.tmp:~0,1%%reverse.Result%
    set reverse.tmp=%reverse.tmp:~1,999%
    if not "%reverse.tmp%"=="" goto:reverse.loop
goto:eof
eof:

Signed your App for device

Apply Signed Keys

https://www.blackberry.com/SignedKeys/codesigning.html

Apply and get two key files: client-PBDT-#######.csj, client-RDK-#######.csj

DO REMEMBER the password you use to apply the key files ( as -csjpin value later )

Signer Tool

After you got the two files, download them and run following commend to sign the key files

blackberry-signer -proxyhost 123.45.67.89 -proxyport 8080 -register -csjpin csj-apply-password -cskpass my-store-password client-RDK-#######.csj client-PBDT-#######.csj

If you don’t need proxy, remove the relative parameters. DO REMEMBER the proxy arguments MUST BE THE FIRST PARAMETER for blackberry-signer, if you put the somewhere else, it won’t work.

The -cskpass you choose here will be the -storepass value for generate the debug token.

You could backup the 3 result files for other machine

author.p12, barsigner.csk and barsigner.db

  • Windows XP: %HOMEPATH%\Local Settings\Application Data\Research In Motion\

  • Windows Vista and Windows 7: %HOMEPATH%\AppData\Local\Research In Motion\

  • Mac OS: ~/Library/Research In Motion/

  • UNIX or Linux: ~/.rim/

By default, %HOMEPATH% is C:\Documents and Settings on Windows XP and C:\Users on Windows Vista and Windows 7.

More detail on this topic

BTW: batchbar-signer for repackage android app DOES NOT support -proxyhost parameter when I write this blog. ( got this info by decompile the java class file used by this tool )

Debug Token

You need a debug token, the name of the debug token bar file could be chosen as you will.

blackberry-debugtokenrequest -proxyhost 123.45.67.89 -proxyport 8080 -storepass my-store-password -devicepin MY-DEVICE-PIN mindon_token.bar

DO REMEMBER the proxy arguments MUST BE THE FIRST PARAMETER

Install the token bar file into your simulater (IP 192.168.111.###) or device (IP 169.254.0.1).

blackberry-deploy -installApp -password my-device-password -device 192.168.111.128 -package %*

Package and Signed your App

@%WebWorksSDK_HOME%\dependencies\node\node.exe %WebWorksSDK_HOME%\lib\bbwp.js -g my-store-password mydemo-app.zip

If you need to debug, add -d parameter before -g.

How to signed an repackage of android app?

batchbar-signer myandroid-app.bar author.p12 my-store-password -t product\

The myandroid-app.bar is generated by command tool: apk2bar (It’s not included in webworks sdk, and could fetch from http://developer.blackberry.com/android/tools/ )

Another Issue when working an WebWorks Native Extension

If you got an error “Require Error Can’t find /usr/lib/webplatform/plugins/jnext/***.so Libary cannot be found”.

Try telnet 192.168.111.128 with devuser/devuser as account and password, you could never find your .so file there in the path even it works.

The error may comes from some other error - dependency missing or something else, who knows?

Most problems you met during the development, few you could get the right and directly answer in the development documents from BB website or forum. Google helps sometimes, but not the right solution. Most casese, maybe you need to try or find the right develop guy in RIM.

Wish this could be helpful.

God bless you, dear BB10 developers :-)

blackberry 10;webworks

Comments