- What You Will Accomplish
- Before You Begin
- Install the Tutorial, Gateway (optional), Android SDK, and Cordova 6.0
- Build the Hybrid Android App Using Cordova
- Configure and Run the Gateway and Apache ActiveMQ (optional)
- Test the Hybrid Android App
Note: For this walkthrough, you can use any JMS-compliant message broker. By default, the Gateway is configured to connect to the server on tcp://localhost:61613. You can configure the connect URL in the file GATEWAY_HOME/conf/gateway-config.xml. See About Integrating Kaazing WebSocket Gateway and JMS-Compliant Message Brokers for more information.
Before starting this walkthrough you need the following:
- Kaazing WebSocket Gateway (optional). See Setting Up Kaazing WebSocket Gateway. You can also use the publicly available Kaazing WebSocket Gateway and Apache ActiveMQ broker at the URL
- Android Studio and SDK.
- Apache Cordova 6.0 and its Command-Line Interface (CLI).
Learn about supported browsers, operating systems, and platform versions in Release Notes.
Note: Steps for installing and configuring Android Studio, Android SDK, and Cordova 6.0 are included in this walkthrough.
The following steps take you through the installation of the software required for deploying a hybrid Android app. If you have already have this software installed, you can simply note the locations of the installed software for later use.
- Install the Gateway as described in Setting Up Kaazing WebSocket Gateway (optional). There is also a publicly available Kaazing WebSocket Gateway and Apache ActiveMQ message broker available at the URL
wss://sandbox.kaazing.net/jms. You can use either option.
- Download and install Android Studio from http://developer.android.com/sdk/installing/index.html?pkg=studio.
- Launch Android Studio.
- In Welcome to Android Studio, click Configure, and then click SDK Manager.
- Select the Android 2.2 and the Android 4.1 packages and then click Install packages.
- Download and install Cordova 6.0 as described in Installing the Cordova CLI from Cordova.
Note: The general steps for creating an Android app using Cordova are documented in the Apache Cordova Documentation, Create the App.
- Open a Terminal at the folder where you want to save the app.
- In Terminal, navigate to the folder for your new app (
- To specify the target platform as Android, enter the following command:
cordova platform add android. Note: To see a list of the current platforms available, enter:
cordova platforms ls.
To build the project, enter the following command:
cordova build android. The build process might take some time. When it is finsihed, Cordova generates the platform-specific project within the project's platforms subdirectory that you can open with Android Studio (for example, myAndroidApp/platforms/android).
On Mac or Linux, if you receive the error
Error: Android SDK not foundthen open your .bash_profile file and enter the following (replace JohnSmith with your user name):
For more info, https://cordova.apache.org/docs/en/dev/guide/platforms/android/.
If you are going to use a local copy of Kaazing WebSocket Gateway, the following steps start the Apache ActiveMQ service that is included with the Gateway, configure the cross-site constraint for the jms service on the Gateway, and then run the Gateway.
- Start Apache ActiveMQ. For steps on starting Apache ActiveMQ, see the setup information for Apache ActiveMQ or Setting Up the Gateway and Clients.
- Open the GATEWAY_HOME/conf/gateway-config.xml file in a text editor. You need to modify this file to use the Android Emulator loopback IP address (10.0.2.2) and you need to change the cross site constraint to allow any origin in order to run the app locally. 10.0.2.2 is the special alias to your host loopback interface (127.0.0.1 on your development machine). For more information about Android Emulator networking, see Emulator Networking from Android.
jmsservice to use the Android loopback IP address and the cross site constraint to allow any origin:
<service> <name>JMS Service</name> <description>JMS Service</description> <accept>ws://10.0.2.2:8888/jms</accept> <type>jms</type> <properties> <connection.factory.name>ConnectionFactory</connection.factory.name> <context.lookup.topic.format>dynamicTopics/%s</context.lookup.topic.format> <context.lookup.queue.format>dynamicQueues/%s</context.lookup.queue.format> <env.java.naming.factory.initial>org.apache.activemq.jndi.ActiveMQInitialContextFactory</env.java.naming.factory.initial> <env.java.naming.provider.url>tcp://localhost:61616</env.java.naming.provider.url> </properties> <accept-options> <ws.bind>localhost:8888</ws.bind> </accept-options> <realm-name>demo</realm-name> <cross-site-constraint> <allow-origin>*</allow-origin> </cross-site-constraint> </service>
- Save the gateway-config.xml file.
Start the Gateway as described in Setting Up the Gateway and Clients.
The output from the command will display that the Gateway is listening on:
ws://10.0.2.2:8888/jms @ localhost:8888
The following steps use the Android Emulator to test the hybrid Android app that you created.Notes:
- If you are using a local Gateway and Apache ActiveMQ broker, then both the Gateway and Apache ActiveMQ must be running before testing the hybrid Android app.
- When testing on Android devices: In order to connect the hybrid Android app on the Android device to the Gateway and Apache ActiveMQ, the Android device must be able to resolve the host name of computer running the Gateway on the network. This is the host name that you will use in the Location field of the hybrid Android app. For example, ws://host_name:8001/jms. You can also configure the Android device to use the IP Address of the computer running the Gateway (for example, ws://192.168.4.86:8001/jms). Using the IP Address is often the easiest method during testing.
- In Terminal, ensure that you are in the root of the project directory (for example, myAndroidApp), and enter the following to see a list of all available Simulator targets:
cordova run android --list. For this walkthrough, we will use Nexus_5_API_22_x86.
- To run the app in the Android Simulator, enter the following:
cordova run android --target="Nexus_5_API_22_x86". The Android Simulator opens and displays the hybrid Android app. It might take several minutes for the Android Simulator to launch and display the app. The app icon might appear on the Android Simulator screen for a while before displaying the GUI of the app. You might need to relaunch the app within the Android Simulator.
In the hybrid app in the Android Simulator, click in the Location field. If you are using a local Gateway, enter the
ws://10.0.2.2:8888/jms. If you are using the publicly available Gateway and Apache ActiveMQ broker, enter
wss://sandbox.kaazing.net/jms. Click Connect.
The Log messages field reports a successful connection. If the app does not connect, ensure that you have the Gateway and Apache ActiveMQ running.
- Play with hybrid app to see the full functionality.
For information on testing your hybrid Android app on an Android device, see Setting up a Device for Development and OEM USB Drivers in the Android developer documentation (http://developer.android.com).