< Table of Contents

Walkthrough: Deploy a JavaScript JMS App as a Hybrid iOS App

In this walkthrough, you will learn how to deploy an existing JavaScript JMS web app as a hybrid iOS app for iOS. This topic walks you through the following subjects:

  1. What You Will Accomplish
  2. Before You Begin
  3. Install the Gateway (optional), Xcode 6.2, and Cordova 6.0
  4. Build the Hybrid Mobile App Using Cordova
  5. Run the Gateway and Apache ActiveMQ (optional)
  6. Run and Test the Hybrid Mobile App in iOS Simulator
  7. Test the Hybrid iOS app on an iOS device
  8. Troubleshooting
  9. Summary

Notes:

What You Will Accomplish

At the end of this walkthrough, a JavaScript JMS demo created using the Kaazing JavaScript JMS SDK libraries runs as a hybrid iOS app on iOS, connects to a publicly available (or a local) Apache ActiveMQ broker via the Gateway, and sends and receives JMS messages using a native or emulated WebSocket connection. Users can run the hybrid iOS app on any iOS device and connect via the Gateway to the Apache ActiveMQ broker.

This walkthrough uses the out of the JavaScript JMS tutorial app that is available on Github at https://github.com/kaazing/javascript.client.tutorials, but the steps outlined in this walkthrough are the same for other JavaScript JMS client applications built with the Gateway.

Note: For this walkthrough, you can use any local JMS-compliant message broker or the publicly available Gateway and Apache ActiveMQ message broker available at the URL wss://sandbox.kaazing.net/jms. By default, the local Gateway is configured to connect to the message broker 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 You Begin

Before starting this walkthrough you need the following:

Learn about supported browsers, operating systems, and platform versions in Release Notes.

Note: Steps for installing and configuring Xcode 6.2 and Cordova 6.0 are included in this walkthrough.

Install the Gateway (optional), Xcode 6.2, and Cordova 6.0

The following steps take you through the installation of the software required for deploying a hybrid iOS app. If you already have this software installed, you can simply note the locations of the installed software for later use with the shell script.

  1. Download or clone the Kaazing JavaScript JMS Tutorial, available on Github at https://github.com/kaazing/javascript.client.tutorials. Build the project using the instructions here https://github.com/kaazing/javascript.client.tutorials/blob/develop/README.md.
  2. 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.
  3. Install Xcode 6.2 from http://developer.apple.com/devcenter/download.action?path=/Developer_Tools/Xcode_6.2/Xcode_6.2.dmg (requires Apple ID to log in). You can also install Xcode 6.2 from https://developer.apple.com/downloads/ by searching for Xcode 6.2. Once Xcode is installed, install the iOS Simulator.

    1. In Xcode, click Xcode, and then click Preferences.
    2. Click Downloads, and then click Components.
    3. Click the download link next to iOS 8.2 Simulator. You can choose to use different simulators, but iPad 2 / iOS 8.2 Simulator is used for this walkthrough.
  4. Quit Xcode. Xcode should not be running when you are installing Cordova.
  5. Download Cordova 6.0 by following the step in Installing the Cordova CLI.

Build the Hybrid Mobile App Using Cordova

The following steps build the hybrid iOS app using the Xcode project you created.

  1. Note the location of the Kaazing JavaScript JMS Tutorial you downloaded and built, for example /Users/johndoe/Desktop/github/javascript.client.tutorials/jms. When you create your Cordova project you will reference the jms folder in order for Cordova to build the hybrid iOS app using the tutorial files.
  2. Open a Terminal at the folder where you want to store your app.
  3. In Terminal, enter the following command: cordova create myApp com.example.myapp myApp --template /Users/johndoe/Desktop/github/javascript.client.tutorials/jms.

    The /Users/johndoe/Desktop/github/javascript.client.tutorials/jms points to the JavaScript demo files you downloaded and built.

    Note: This walkthrough uses the JavaScript JMS tutorial app as an example web app, but when you create your own JavaScript JMS app, you can create it in your favorite IDE and then copy it to this www directory. You must name the HTML file for your app index.html and you must ensure that links in index.html point to the JavaScript WebSocket library and the JavaScript JMS library (see Setting Up the Gateway and Clients), for example:

           <script src="WebSocket.js" type="text/javascript" language="javascript"></script>
           <script src="JmsClient.js" type="text/javascript" language="javascript"></script>
           

    For details on the command parameters, see Create the App from Cordova.

  4. Press Enter. Cordova will create the MyApp app.
  5. In Terminal, go to the myApp folder created by the Cordova command to see the files created by Cordova (cd myApp).
  6. To specify the target platform as iOS, in Terminal, enter the following command: cordova platform add ios. Note: To see a list of the current platforms available, enter: cordova platforms ls.
  7. To build the project, enter the following command: cordova build ios. The build process might take some time. When it is finsihed, Cordova generates platform-specific code within the project's platforms subdirectory (for example, myApp/platforms/ios/myApp.xcodeproj).

Run the Gateway and Apache ActiveMQ (optional)

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.

  1. Start Apache ActiveMQ. For steps on starting Apache ActiveMQ, see the setup information for Apache ActiveMQ or Setting Up the Gateway and Clients.
  2. Open the GATEWAY_HOME/conf/gateway-config.xml file in a text editor. Modify the jms service cross-site-constraint setting to allow all cross-origin site access to the service. For example:

      <service>
        <name>JMS Service</name>
        <description>JMS Service</description>
        <accept>ws://${gateway.hostname}:${gateway.extras.port}/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://${gateway.hostname}:61616</env.java.naming.provider.url>
        </properties>
    
        <realm-name>demo</realm-name>
    
        <!--
        <authorization-constraint>
          <require-role>AUTHORIZED</require-role>
        </authorization-constraint>
        -->
    
        <cross-site-constraint>
          <allow-origin>*</allow-origin>
        </cross-site-constraint>
      </service>
      

    Note: This step is necessary because the hybrid iOS app in the iOS Simulator connects to the Gateway from the local file system.

  3. Save gateway-config.xml, and then start the Gateway as described in Setting Up the Gateway and Clients.

Run and Test the Hybrid Mobile App in iOS Simulator

The following steps run the hybrid iOS app and test the connection to the Gateway and Apache ActiveMQ.

  1. In Terminal, ensure that you are in the root of project directory (for example, myApp), and enter the following to see a list of all available Simulator targets:
    cordova run ios --list. For this walkthrough, we will use iPad-2.
  2. To run the app in the iOS Simulator, enter the following: cordova run ios --target="iPad-2". The iOS Simulator opens and displays the hybrid iOS app. It might take several minutes for the iOS Simulator to launch and display the app. The app icon might appear on the iOS Simulator screen for a while before displaying the GUI of the app. You might need to relaunch the app within the iOS Simulator.

    Note: You can also use Xcode to launch the app in the iOS Simulator:
    1. In Xcode, open your project, located in myApp/platforms/ios/myApp.xcodeproj.

    2. In the scheme selector, select iPad 2.
    3. Click the name of your project in Xcode and click Run. If you are prompted to confirm developer mode, click OK.

      The iOS Simulator opens and displays the hybrid iOS app.

  3. In the hybrid app in the iOS Simulator, click in the Location field. If you are using a local Gateway, enter the jms service URI (ws://localhost:8001/jms), and click Connect. If you are using the publicly available Gateway and Apache ActiveMQ broker, enter wss://sandbox.kaazing.net/jms and click Connect.

    The Log messages field reports a successful connection. If the app does not connect to your local Gateway or broker, ensure that you have the Gateway and Apache ActiveMQ running.

  4. Play with hybrid app to see the full functionality.
Notes:

Test the Hybrid iOS app on an iOS device

The following steps build a hybrid iOS app that you can copy and test on an iOS device (iPhone, iPad, iPod Touch).

Note: To build a hybrid iOS app for use on an iOS device you must be a member of the Apple iOS Developer Program, you must code sign your app using a Mac Submission Certificate, and you must have a Provisioned Device to install your app onto. The following steps assume that you have met these requirements.

  1. In Xcode, click the stop button to stop running your hybrid iOS app in the iOS Simulator.
  2. Quit the iOS Simulator.
  3. In the Xcode, click Project, and then click Edit Scheme.
  4. In the Run scheme, and in the Build Configuration menu, select Release, and click OK.
  5. Click Project, click Build For, and then click Running.
  6. When the build is completed, expand your project folder in the left pane in order to see the Products folder. The completed product is listed in this folder.

    Note: To see the app file, right-click your product and click Show in Finder.

  7. Connect your iOS device to your development computer.
  8. In the toolbar, change iPad 2 to iOS Device.

    Note: In order to connect the hybrid iOS app on the iOS device to the locally running Gateway and Apache ActiveMQ, the iOS 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 iOS app. For example, ws://host_name:8001/jms. You can also configure the Gateway 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.

  9. Click Run to run the hybrid iOS app on your iOS device, enter the jms service URI in the Location field, and click Connect.

    The Log messages field reports a successful connection.

Troubleshooting

For errors that occur when trying to use your hybrid iOS app on an iOS device, see iOS Development: Troubleshooting in the iOS Developer Library and the stackoverflow forum.

Summary

As you have seen in this walkthrough, building a hybrid iOS app using the JavaScript JMS Tutorial is easy to accomplish. Building your own custom JavaScript JMS hybrid iOS app simply requires that you substitute your web app in the www folder in the Xcode project and then link the Kaazing WebSocket and JavaScript JMS libraries in the index.html file correctly. For information about building a hybrid Android app, see the documentation.

Notes

Clients built using Kaazing WebSocket Gateway 3.x libraries will work against the Kaazing 4.x JavaScript SDK. If you wish to upgrade your 3.x client to the 4.x libraries, please note that the 3.x clients used a single JMS library and 4.x clients include and use separate WebSocket and JMS libraries. Update your client library file and code references to include both the WebSocket and JMS libraries, as described in the 5.x documentation. For more migration information, see Migrate JavaScript Applications to Kaazing WebSocket Gateway 4.x.