Introduction to Developing Companion Apps with the Intel® XDK

The Intel® XDK provides a robust development environment for developing, testing, previewing, and deploying HTML5 web and hybrid companion apps on multiple mobile platforms. To get started, download and install the Intel XDK application onto your Linux*, Microsoft Windows* or Apple OS X* development system.

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.

The videos below show a quick introductory overview for using the Intel XDK to develop mobile IoT companion apps. Please view one or both before reading the pages in this book. Doing so should help make the concepts described easier to follow and understand:

IMPORTANT: Intel XDK mobile IoT companion apps are Apache* Cordova* (aka PhoneGap*) hybrid HTML5 mobile web apps. Apps you build with 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 (note that page describes the use of Cordova CLI, which is not installed as part of nor necessary to use the Intel XDK).

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 and Designing a Companion App's User Interface (UI) Layout

Within the Develop tab of a companion app, you will find two primary tools: the Brackets* code editor and the App Designer* UI layout editor. The Brackets built-in editor is an open-source text editor with features optimized for editing HTML5 files (JavaScript*, HTML and CSS). App Designer is a drag-n-drop HTML layout editor for building user interface (UI) layouts.

Use of App Designer to create your companion app UI layout is optional. If you prefer to build your UI layout by hand, you should and can continue to do so when using the Intel XDK. TheApp Designerlayout tool is useful for those who are uncomfortable creating their own UI layout using HTML and CSS.App Designeris not meant to be a replacement for the layout tools you are already familiar with, so you can continue to build HTML and CSS layouts with your existing layout tools within the Intel XDK.

Similarly, using the built-in Brackets code editor is optional. You can edit your application source files by using 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.

App Designer includes an emphasis on responsive layout design through the use of a custom grid system and media queries, and is especially suited to designing layouts for different screen sizes and orientations.App Designersupports a collection of popular UI widget libraries. Some of these widget libraries also have their own layout frameworks; however, when used with App Designer, only the widgets within those frameworks are used, the layout grids associated with those frameworks are not used by App Designer.

You can switch between the code editor andApp Designerlayout editor at any time (only when viewing those files that are supported byApp Designer– normally your index.html file).App Designeris only available if you started your project from anApp Designertemplate or sample project. If you did not initially create your application in this manner, you will only have access to the Brackets code editor from the Develop tab.

For a summary ofApp Designerfeatures and its generated code, see the App Designer Overview.

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 two primary tools provided by the Intel XDK for debugging your app:

  • The Simulate tab for quickly debugging much of your app logic.
  • The Debug tab for debugging your app behavior 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 to become aware of all 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 approximately simulates your app running on 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. You can always perform an ad hoc build of your app and load it onto a real mobile device, but your ability to debug using this approach is limited. In addition, the time and effort required to make changes to your app, rebuild your app and then reload your app onto a real device may limit your willingness to take this approach for debugging. Fortunately, there are some alternatives, shown in order or preference.

  • Use the Debug tab to remotely debug your companion app on a USB-connected Android device without a build and install step. Remote debugging is provided by the Google Chrome* Developer Tools (CDT). The CDT debugger includes full JavaScript* debugging with breakpoints and profiling, which are not possible when using the weinre debug tools. This process is very similar to debugging with CDT in the Chrome browser.

  • 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.

The Android version of App Preview supports remote debugging with Chrome DevTools (CDT) , which means you debug the code running on a real mobile device using a debugger that runs on your development system. 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 CDT; 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. 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 / 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 associated Cordova plugins into a format that can be submitted to a mobile app store and, ultimately, downloaded and installed onto a mobile device. All of the popular mobile platforms (Android, iOS and Windows) are supported by the Intel XDK. Builds are performed in the cloud, so you do not need to install and configure an SDK or native development system for each target platform on your development system, as you must do if you are building a Cordova CLI (aka PhoneGap*) app.

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. For instances where you want to use the Intel XDK to package your app for submission to a store, you will have the opportunity to include your developer credentials in the package, thus minimizing the effort required to go from the build step to the submission step.

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.