This article provides a walkthrough of the required steps necessary to get started using the sample BlackBerry® WebWorks™ application distributed as part of the BlackBerry® Messenger Social Platform SDK for BlackBerry WebWorks. This sample application demonstrates the various capabilities of the BBM™ SDK that you can use within your own BlackBerry smartphone application development.
- BlackBerry WebWorks SDK for Smartphones installed
- BlackBerry Messenger SDK for BlackBerry WebWorks Installed
- For Windows® only - due to use of BlackBerr Smartphone Simulators
- Recommended 2GB RAM - necessary to run two instances of the BlackBerry Smartphone simulators
Development Environment Setup
1. Download and extract the BBM SDK for BlackBerry WebWorks to your local development machine.
2. Follow the the BlackBerry WebWorks SDK for Smartphones Getting Started Guide to ensure that the following installation requirements are complete and in place on your development machine:
- An installed version of the MDS-CS simulator with BBM support and unlimited strength encryption enabled
- An installed version of the BlackBerry Smartphone Simulator (model 9300 or 9800) with BBM support enabled
- A copy of the blackberry.bbm.platform folder installed in the <bbwp>/ext folder of your BlackBerry WebWorks SDK installation
3. Using the BlackBerry WebWorks SDK for smartphones, build the BBMPlatformDemoWW sample app using the BBMPlatformDemoWW.zip archive.
Runtime Environment Setup
4. Start the instance of the MDS-CS simulator that was installed during step 2. If successful, you should not see any <ERROR> elements displayed in the terminal window.
Troubleshooting: A common error that may occur is the MDS-CS simulator may not start properly if multiple versions of the Java® runtime environment (JRE or JDK) are installed on your system. In this scenario, the version recognized by the system may be different than the version that has unlimited strength encryption enabled and you may see this error: "Cannot initialize AES-256: Did you install Unlimited Strength Jurisdiction Policy Files?". If this is the case, either correct the JRE defined in your system PATH variable, or enable unlimited strength encryption for the system instance of the JRE.
5. Using the sim1.bat and sim2.bat batch files installed in step 2, start two instances of the same BlackBerry Smartphone simulator. Once loaded, accept the end-user license agreement (EULA), and exit the Setup wizard for both simulators.
Note: Each instance of the Smartphone simulator uses 600+ Mb of RAM. Ensure that you have enough available free or virtual memory to start both instances.
Troubleshooting: Only BlackBerry Smartphone device software that includes version 6 of the BlackBerry Messenger client can run BBM Social platform enabled applications. The versions of the BlackBerry Smartphone simulator distributed as part of the BBM SDK can be used for BBM Social platform development.
6. Test the connectivity of the two BlackBerry smartphone simulators, and the instance of MDS-CS that are currently running:
- Start the BlackBerry Messenger client on both simualtors and accept each EULA.
- When prompted, enter a display name for each sim as "sim1" and "sim2", respectively. You can verify which simulator is correct by looking at the simulator window title bar (e.g. "9800-1" vs. "9800-2").
- Click okay and hit cancel when prompted to select existing contacts.
- From sim1, invite sim2 to BBM using pin "2100000B".
- Send a test message between simulators. You should see the conversation in each window.
Setting up the BBMPlatformDemoWW sample application
7. Install and run the BBMPlatformDemoWW.cod file that was previously generated in step 3:
- Open the File menu from the sim1 window, and select "Load BlackBerry application or theme".
- Navigate to the bin folder of the BBMPlatformDemoWW sample application, generated in step 3, and select BBMPlatformDemoWW.cod file.
- Once installed, start the application from the home screen.
8. Once the BBMPlatformDemoWW application is started and loaded, you will be prompted to connect it to the BlackBerry Messenger client. This is a necessary step to ensure that the APIs used by the BBM SDK can successfully communicate with BlackBerry Messenger. Hit okay and proceed through the steps of the connection wizard.
Note: BlackBerry ID (BBID) is a requirement for use of the BlackBerry Messenger Social Platform. As part of the BBM connection wizard, you will be prompted to complete a BBID update step, and then asked to restart the device software.
Troubleshooting: Some instances of the BlackBerry Smartphone simulator may raise NullPointerException or IllegalArgumentException error messages. If you encounter these errors, hit 'Continue' to close the error message and proceed with the setup.
9. Start simulator 1 again using the sim1.bat file. Once started, you should see a prompt that indicates that "Changes have taken effect". Repeat step 7 to load and start the BBMPlatformDemoWW sample application.
10. You will be prompted again to connect the BBMPlatformDemoWW sample application to BBM, however this time there will no further BBM setup or BBID updates.
- Click "OK" to begin the connection process again.
- When prompted to sign up to BlackBerry ID to continue, click "Sign In".
- Sign in using your BlackBerry ID.
Tip: You are required to use a valid BBID to enable the BlackBerry Messenger Social platform, however it does not necessarily need to be your personal, or "live" BBID. You can create a test account that you can use for your own development purposes.
Using the BBMPlatformDemoWW sample application
11. The features of the BBMPlatformDemoWW sample application can now be used. This application demonstrates the various capabilities of the BBM SDK that you can use within your own application development. Developers are encouraged to explore and use the various features of this sample application.
Example: sending an invite to download application.
Example: sending an chat from the application.