Introduction to Developing Companion Apps

This page provides an introduction to the development of Intel XDK companion apps; detailed instructions for each tab in a companion app project can be found by referring to the links in the Intel XDK Companion App Tabs Overview. The mobile companion app project tabs are directed at different aspects of the mobile app development process. There is no requirement that you use the tabs in the order presented, or that you use all of the tabs; you can jump between the tabs as your development process requires.

IMPORTANT: Intel XDK mobile IoT companion apps are Apache* Cordova* (aka PhoneGap*) hybrid HTML5 mobile web apps. Mobile apps you create using the Intel XDK that run on Android*, Apple iOS*, Microsoft Windows mobile devices run in a WebView (embedded browser) and are limited to the features provided by that platform's native WebView. WebViews typically have less capability than a browser; their advantage over browsers is extendibility via native-code Cordova plugins. Therefore, you can extend the features of the platform WebView by adding Cordova plugins as a way to access platform features that, otherwise, might not be available to your application.

If you are not yet familiar with the concept of using HTML5 to build cross-platform hybrid apps, you can read Building Cross-Platform Apps with HTML5 and Five Useful Tips on Getting Started Building Cordova Mobile Apps with the Intel XDK (blog) before you begin creating Intel XDK mobile IoT companion apps. Additionally, a short tutorial is available to walk you through a typical end-to-end workflow with Intel XDK companion app projects. Finally, you should also read the Cordova Best Practices documentation provided by the Cordova project.

Managing Companion App Projects

An Intel XDK mobile IoT companion app project is an HTML5 app. You can create an HTML5 project from scratch, by importing existing HTML5 apps or by modifying any of the included templates or sample apps. The Intel XDK requires that a project conform to the following rules:

  • All files are contained within a hierarchical set of folders emanating from one root: the project folder.

  • An index.html file is located in the project directory's source folder (which is named www by default) and is located within the project folder.

  • The <project-name>.xdk and <project-name>.xdke project configuration files are located within the root of the project folder.

When a project is created or imported, the special <project-name>.xdk file is created and located in the project's root directory and is named to match the name of your project. This special <project-name>.xdk file is used by the Intel XDK to manage your project; it does not contain any application code and is not needed by your application to execute on a real device. If you delete, relocate or corrupt this file you can recover it by importing your project into the Intel XDK; this action will create a new <project-name>.xdk file (though you will have to reconfigure your app's build settings using the Projects tab if this happens).

Occasionally, updates to the Intel XDK may update the format and information that is stored inside the <project-name>.xdk file; when such upgrades happen, your project can no longer be opened by previous versions of the Intel XDK. In the case of such an upgrade, a backup copy of the <project-name>.xdk file is made and stored in the root of your project folder so that you can "go back" to an older version of the Intel XDK, if necessary.

The currently-active project is always highlighted on the Project tab and is the project on which all other tabs operate. The Intel XDK operates on only one project at a time. You cannot run multiple instances of the Intel XDK simultaneously; only one copy of the Intel XDK can run at any moment, regardless of the number of Intel XDK versions or editions you have installed on your machine.

Editing Your Companion App's Code

Within the Develop tab of a companion app you will find the Brackets* code editor. The Brackets built-in editor is an open-source text editor with features optimized for editing HTML5 files (JavaScript*, HTML and CSS).

The App Designer UI layout editor, which was formerly available in the Develop tab, has been retired and is no longer supported. You can use most standard HTML5 UI frameworks (e.g., Twitter Bootstrap) to create your app's layout. Or, you can create your layout directly using standard CSS and HTML of your own design.

Using the built-in Brackets code editor is optional. You can edit your application source files with your favorite code editor (including standalone Brackets) while the Intel XDK is open. All of your Intel XDK project files are stored locally on your development system in the folder you specified when you created the application project.

Debugging and Testing Your Companion App

Companion mobile apps that use only standard HTML5 APIs and interfaces can be debugged in a standard desktop or mobile browser; however, apps that use Cordova APIs, which go beyond the reach of a standard browser, require more than a browser. Debugging hybrid HTML5 apps is complicated by the fact that hybrid apps have access to device sensors and other features that are typically "off limits" to standard browsers.

There are a variety of tools available for debugging your app:

  • The Simulate tab for quickly debugging much of your app logic.
  • The Test tab for debugging your app behavior on a real device.
  • A variety of free debug and test tools for debugging your built app on a real device.

It is important to understand that when your companion app is built and installed on a mobile device, it does not run in the mobile browser installed on that device. Instead, it runs in a WebView on that device. Think of a WebView as an embedded browser, as explained in When is an HTML5 Web App a WebView App?

See the Debug and Test Overview for a list of the options available to debug and test mobile Cordova apps.

Simulating Your Companion App with the Simulate Tab

The mobile device simulator presented by the Simulate tab gives you the ability to debug more of your app's functionality than you could in a standard browser. It includes simulations of some of the popular core Cordova device APIs and provides a simple preview of your app's layout on virtual mobile devices that span the range from phones to tablets. Use the Simulate tab panels to configure the virtual environment for the application under test. For example, the GeoLocation panel lets you select the latitude and longitude returned to your app when it calls the Cordova Geolocation API.

The Simulate tab approximates the behavior of your app by running it in a desktop browser that appears to be a mobile device. There are many limitations to what this simulator can do! Use it to quickly debug and test your companion app logic before you test and debug your companion app behavior on a real mobile device. For more details, see Device Simulator Limitations.

Selecting a virtual device determines the size of the visual frame that renders your app and helps you see how your app reacts to orientation changes (from portrait to landscape mode). Testing your app this way, with different virtual devices and orientations, lets you quickly determine how well your companion app will work with a variety of mobile screen sizes and aspect ratios.

Debugging in the Simulate tab is similar to debugging in a desktop browser. The "bug" icon located in the toolbar opens a built-in copy of Chrome DevTools* for direct debugging of your app's JavaScript code, CSS rules and DOM elements.

The runtime engine that renders your companion app's HTML5 code within the mobile device simulator is based on the Chromium open source browser; it is not an emulation of a real device. What you are debugging when using the Simulate tab is a simulation of the core Cordova API running on the Chromium desktop engine.

Using Chrome DevTools (CDT), you can set breakpoints, single-step and display variables in your JavaScript code. You can also do full Document Object Model (DOM) debugging; that is, you can:

  • display the HTML elements that are being rendered,
  • see their relationship to the display, and
  • set breakpoints on DOM events.

You can also see the effects of CSS on the DOM. And you have access to the CDT JavaScript console, where you can view your application's console.log messages and interact with your app's JavaScript by manually inspecting properties and executing methods.

Debugging and Previewing Your Companion App on a Real Mobile Device

The device simulator (Simulate tab) is a very useful "quick debug" tool, but ultimately you need to see how your companion app looks and performs on a real device. Some on-device debugging options are listed below:

  • From the Test tab you can push your companion app remotely to a real mobile device into a special container app called Intel® App Preview, without having to perform a build, to quickly evaluate how your app looks and behaves on a real mobile device. You push your app to App Preview wirelessly via the Internet or via your local WiFi. This technique can be used with Android, iOS, and Windows devices. Debugging your app with Intel App Preview and the Test tab is limited, so this technique is best used for previewing and functional testing.

  • Build an app and install it onto a real device and use the weinre* remote JavaScript console to debug your companion app on an Android, iOS or Windows mobile device. Using weinre is detailed on the Debugging and Test Overview documentation page. This approach is more flexible than using remote CDT or remote Web Inspector (see the following bullet) but does not include a full JavaScript* debugging tool. The weinre remote JavaScript console can also be used in conjunction with the Test tab, described in the preceding bullet.

  • Build an app and install it onto an Android or iOS device and then use remote Chrome DevTools (Android) or remote Web Inspector (iOS) to debug your companion app on a USB-connected Android or iOS device. Remote debugging is detailed on the Debugging and Test Overview documentation page. This approach includes full JavaScript* debugging with breakpoints and profiling, which are not possible when using the weinre debug tools.

The Android version of App Preview supports remote debugging with Chrome DevTools (CDT) , which means you can debug the code running on a real mobile device using a debugger that runs on your laptop. Remote debugging allows the debug user interface to not be confined by the display limitations of the mobile device under test. Remote CDT debugging offers many of the same capabilities as debugging in a standard desktop browser or when using the Simulate tab.

Remote debugging with the weinre open source tool provides a subset of the features in Chrome DevTools; weinre does not support JavaScript debugging (setting breakpoints, single stepping, etc.). It can, however, access the DOM rendered in the target system and capture console output. If you have a USB-connected Android (or iOS device and a Mac development system), you are encouraged to use remote CDT (remote Safari Web Inspector on a Mac) to debug your built app on-device. With Windows devices weinre is your only debug option.

Before you use any debug and test features of the Intel XDK, be sure to first download and install the special Intel App Preview container app onto your mobile test devices. This application can be downloaded from the primary store for your device (Apple Store*, Google Play* and the Windows App Store*). For more information please read Intel App Preview Introduction.

Packaging Your Companion App for Distribution

HTML5 apps are not limited to execution in a desktop or mobile browser. By packaging your HTML5 web app as a Cordova (aka PhoneGap) app, you can deploy it as a locally-installed hybrid mobile app. This enables the use of the same distribution channels as native mobile apps, as well as the same app installation and launch experience.

Before deploying your companion app as a hybrid mobile app, you must build it. The build process packages your app and its Cordova plugins into a format that can be submitted to a mobile app store and downloaded and installed onto a mobile device. Mobile apps developed using the Intel XDK can be built using a Cordova compatible build system.

Like a native app, in order to submit your hybrid app to a store you must obtain the proper developer credentials for that store. The procedures and costs associated with becoming a developer for each store vary and are not facilitated by the Intel XDK.

A Note About App Store Submissions: Submission of your packaged app to the respective app stores is not a feature of the Intel XDK. Submission must be performed manually, outside of the Intel XDK development environment.

Including Third-Party APIs and Web-Service APIs in your Companion App

Just as in the case of a web app designed to be hosted by a server and viewed in a desktop or mobile browser, you can use third-party cloud services (web services) and JavaScript libraries within your packaged hybrid mobile companion app.

The same Cross-Origin Resource Sharing (CORS) restrictions (if any) that apply to server-hosted web based HTML5 apps also apply to packaged hybrid mobile apps.

Under the Develop tab of the Intel XDK, you will find a third-party web services widget that makes it easy to discover and add common services to your application. You are under no obligation to use any of the services presented in this tab. Likewise, you may use any web services that are appropriate for your app, even if they are not presented within the Develop tab's web services widget. Please contact the third-party web services provider for information regarding web service costs, licensing and technical help.

For More Information:

For more complete information about compiler optimizations, see our Optimization Notice.