Merge Chromium + Blink git repositories

[chromium-blink-merge.git] / chrome / common / extensions / docs / templates / articles / chrome_apps_on_mobile.html

<meta name="doc-family" content="apps"> 

 <!-- 
   Warning: This document is auto-generated and should not be edited by hand. 
   Please see https://github.com/MobileChromeApps/mobile-chrome-apps/tree/master/docs/htmlConvert.js 
 --> 

 <h1>Run Chrome Apps on Mobile Using Apache Cordova</h1>

<p><em><strong>The toolchain for running Chrome Apps on mobile is in early developer preview. Feel free to give us your feedback using the <a href="https://github.com/MobileChromeApps/mobile-chrome-apps/issues">Github issue tracker</a>, our <a href="http://groups.google.com/a/chromium.org/group/chromium-apps/topics">Chrome Apps developer forum</a>, on <a href="http://stackoverflow.com/questions/tagged/google-chrome-app">Stack Overflow</a>, or our <a href="https://plus.google.com/+GoogleChromeDevelopers/">G+ Developers page</a>.</strong></em></p>

<p><img alt="A Chrome App running on both desktop and mobile" src="{{static}}/images/cca-desktop-and-mobile.jpg" /></p>

<h2 id="overview">Overview</h2>

<p>You can run your <a href="http://developer.chrome.com/apps">Chrome Apps</a> on Android and iOS via a <a href="https://github.com/MobileChromeApps/mobile-chrome-apps">toolchain</a> based on <a href="http://cordova.apache.org">Apache Cordova</a>, an open source mobile development framework for building mobile apps with native capabilities using HTML, CSS and JavaScript.</p>

<p>Apache Cordova wraps your application's web code with a native application shell and allows you to distribute your hybrid web app via Google Play and/or the Apple App Store. To use Apache Cordova with an existing Chrome App, you use the <code>cca</code> (<strong>c</strong> ordova <strong>c</strong> hrome <strong>a</strong> pp) command-line tool.</p>





<h2 id="additional-resources">Additional resources</h2>

<ul><li><p>There are a few special considerations that you should keep in mind when developing with Cordova; we've listed them in the <a href="#special-considerations-when-developing-with-cordova">considerations section</a>.</p></li><li><p>To view which Chrome APIs are supported on mobile, visit the <a href="https://github.com/MobileChromeApps/mobile-chrome-apps/blob/master/docs/APIStatus.md">API Status</a> page.</p></li><li><p>To preview your Chrome App on an Android device without the toolchain, use the <a href="#chrome-apps-developer-tool-adt-for-android">Chrome Apps Developer Tool (ADT)</a>.</p></li></ul>



<p>Let's get started.</p>

<h2 id="step-1-install-your-development-tools">Step 1: Install your development tools</h2>

<p>The Chrome Apps for mobile toolchain can target iOS 6+ and Android 4.x+.</p>

<h3 id="development-dependencies-for-all-platforms">Development dependencies for all platforms</h3>

<ul><li><p><a href="http://nodejs.org">Node.js</a> version 0.10.0 (or higher) with <code>npm</code> is required:</p><ul><li><strong>Windows</strong>: Install Node.js using the installation executables downloadable from <a href="http://nodejs.org">nodejs.org</a>.</li><li><p><strong>OS X</strong> or <strong>Linux</strong>: Installation executables are also available from <a href="http://nodejs.org">nodejs.org</a>. If you wish to avoid the need for root access, it may be more convenient to install via <a href="https://github.com/creationix/nvm">nvm</a>. Example:</p><pre><code>curl https://raw.github.com/creationix/nvm/master/install.sh | sh
source ~/.bash_profile || source ~/.profile || source ~/.bashrc
nvm install 0.10
nvm alias default 0.10</code></pre></li></ul></li></ul>

<h3 id="targeting-android">Targeting Android</h3>

<p>When developing an application for Android, you will also need to install:</p>

<ul><li><a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">Java JDK</a> 7 (or higher)</li><li><a href="http://developer.android.com/sdk/index.html">Android SDK</a> version 4.4.2 (or higher)<ul><li>Install the Android SDK and Android Developer Tools which come bundled with Android ADT Bundle.</li><li>Add <code>sdk/tools</code> and <code>sdk/platform-tools</code> <a href="https://www.google.com/search?q=how+to+add+sdktools+to+path">to your PATH</a> environment variable. </li><li><strong>OS X</strong>: The version of Eclipse that comes with the Android SDK requires JRE 6. If opening Eclipse.app does not prompt you to install JRE 6, get it through the Mac App Store.</li><li><strong>Linux</strong>: The Android SDK requires 32 bit support libraries. On Ubuntu, get these via: <code>apt-get install ia32-libs</code>.</li></ul></li><li><a href="http://ant.apache.org/bindownload.cgi">Apache Ant</a><ul><li>Add <code>apache-ant-x.x.x/bin</code> <a href="https://www.google.com/search?q=how+to+add+sdktools+to+path">to your PATH</a> environment variable.</li></ul></li></ul>

<h3 id="targeting-ios">Targeting iOS</h3>

<p>Please note that iOS development can only be done on OS X. In addition, you will need to install:</p>

<ul><li><a href="https://developer.apple.com/xcode/">Xcode</a> 5 (or higher) which includes the Xcode command line tools</li><li><a href="https://github.com/phonegap/ios-deploy">ios-deploy</a> (needed to deploy to an iOS device)<ul><li><code>npm install -g ios-deploy</code></li></ul></li><li><a href="https://github.com/phonegap/ios-sim">ios-sim</a> (needed to deploy to iOS Simulator)<ul><li><code>npm install -g ios-sim</code></li></ul></li><li>Optional: Register as an iOS developer<ul><li>This is necessary for testing on real devices and for submitting to the app store.</li><li>You can skip registration if you only plan to use the iPhone/iPad simulators.</li></ul></li></ul>

<h3 id="install-the-cca-command-line-tool">Install the <code>cca</code> command-line tool</h3>

<p>Install <code>cca</code> via npm:</p>

<pre><code>npm install -g cca</code></pre>

<p>To update the toolchain later with new releases: <code>npm update -g cca</code>.</p>

<p>Confirm that everything is installed correctly by running this command from the command line:</p>

<pre><code>cca checkenv</code></pre>

<p>You will see the version number of <code>cca</code> outputted and confirmation about your Android or iOS SDK installation.</p>



<h2 id="step-2-create-a-project">Step 2: Create a project</h2>

<p>To create a default mobile Chrome App project in a directory named <code>YourApp</code> run:</p>

<pre><code>cca create YourApp</code></pre>

<p>If you have already built a Chrome App and wish to port it to a mobile platform, you can use the <code>--link-to</code> flag to create a <em>symlink</em> to it:</p>

<pre><code>cca create YourApp --link-to=path/to/manifest.json</code></pre>

<p>If you instead wish to <em>copy</em> your existing Chrome App files, you can use the <code>--copy-from</code> flag:</p>

<pre><code>cca create YourApp --copy-from=path/to/manifest.json</code></pre>

<p>Don't have your own Chrome App yet? Try one of the many <a href="https://github.com/GoogleChrome/chrome-app-samples#mobile-support">sample Chrome Apps with mobile support</a>.</p>



<h2 id="step-3-develop">Step 3: Develop</h2>

<p>You can build and run your application in two ways:</p>

<ul><li>Option A: From the command line, using the <code>cca</code> tool, or</li><li>Option B: By using an IDE, like Eclipse or Xcode. The use of an IDE is entirely optional (but often useful) to assist with launching, configuring, and debugging your hybrid mobile application.</li></ul>

<h3 id="option-a-develop-and-build-using-the-command-line">Option A: Develop and build using the command line</h3>

<p>From the root of your <code>cca</code>-generated project folder:</p>

<h4>Android</h4>

<ul><li>To run your app on the Android Emulator: <code>cca emulate android</code><ul><li>Note: This requires that you've set up an emulator. You can run <code>android avd</code> to set this up. Download additional emulator images by running <code>android</code>. To make the intel images run faster, install <a href="http://software.intel.com/en-us/articles/intel-hardware-accelerated-execution-manager/">Intel's HAXM</a>.</li></ul></li><li>To run your app on a connected Android device: <code>cca run android</code></li></ul>

<h4>iOS</h4>

<ul><li>To run your app on the iOS Simulator: <code>cca emulate ios</code></li><li>To run your app on a connected iOS device: <code>cca run ios</code><ul><li>Note: This requires that you've set up a <a href="http://stackoverflow.com/questions/3362652/what-is-a-provisioning-profile-used-for-when-developing-iphone-applications">Provisioning Profile</a> for your device.</li></ul></li></ul>

<h3 id="option-b-develop-and-build-using-an-ide">Option B: Develop and build using an IDE</h3>

<h4>Android</h4>

<ol><li>In Eclipse, select <code>File</code> -&gt; <code>Import</code>.</li><li>Choose <code>Android</code> &gt; <code>Existing Android Code Into Workspace</code>.</li><li>Import from the path you just created with <code>cca</code>.<ul><li>You should expect to have two projects to import, one of which is <code>*-CordovaLib</code>.</li></ul></li><li>Click the Play button to run your app.<ul><li>You will need to create a Run Configuration (as with all Java applications).  You <em>usually</em> get prompted for this the first time automatically.</li><li>You will need to manage your devices/emulators the first time as well.</li></ul></li></ol>

<h4>iOS</h4>

<ol><li><p>Open the project in Xcode by typing the following in a terminal window:</p><pre><code>cd YourApp
open platforms/ios/*.xcodeproj</code></pre></li><li><p>Make sure you are building the right target.</p><p>In the top left (beside Run and Stop buttons), there is a dropdown to select target project and device. Ensure that <code>YourApp</code> is selected and not <code>CordovaLib</code>. </p></li><li><p>Click the Play button.</p></li></ol>

<h3 id="making-changes-to-your-app-source-code">Making changes to your app source code</h3>

<p>Your HTML, CSS, and JavaScript files live within the <code>www</code> directory of your cca project folder.</p>

<p><strong>Important</strong>: After making changes to <code>www/</code>, you must run <code>cca prepare</code> before deploying your application.  If you are running <code>cca build</code>, <code>cca run</code>, or <code>cca emulate</code> from the command line, the prepare step is done automatically.  If you are developing using Eclipse/XCode, you must run <code>cca prepare</code> manually.</p>

<h3 id="debugging">Debugging</h3>

<p>You can debug your Chrome App on mobile the same way that you <a href="https://github.com/phonegap/phonegap/wiki/Debugging-in-PhoneGap">debug Cordova applications</a>.</p>



<h2 id="step-4-next-steps">Step 4: Next Steps</h2>

<p>Now that you have a working mobile Chrome App, there are lots of ways to improve the experience on mobile devices.</p>

<h3 id="mobile-manifest">Mobile Manifest</h3>

<p>There are certain Chrome App settings that only apply to mobile platforms.  We have created a <code>www/manifest.mobile.json</code> file to contain these, and the specific values are referenced throughout the plugin documentation and this guide.</p>

<p>You should adjust the values here accordingly.</p>

<h3 id="icons">Icons</h3>

<p>Mobile apps need a few more icon resolutions than desktop Chrome Apps.</p>

<p>For Android, these sizes are needed:</p>

<ul><li>36px, 48px, 78px, 96px</li></ul>

<p>For iOS apps, the required sizes differ depending on whether you support 
<a href="https://developer.apple.com/library/ios/qa/qa1686/_index.html">iOS 6</a> vs 
<a href="https://developer.apple.com/library/ios/documentation/userexperience/conceptual/mobilehig/IconMatrix.html">iOS 7</a>. The minimum number of icons required are:</p>

<ul><li><strong>iOS 6</strong>: 57px, 72px, 114px, 144px</li><li><strong>iOS 7</strong>: 72px, 120px, 152px</li></ul>

<p>A complete icon list would look like this in your <code>manifest.json</code> file:</p>

<pre><code>"icons": {
  "16": "assets/icons/icon16.png",
  "36": "assets/icons/icon36.png",
  "48": "assets/icons/icon48.png",
  "57": "assets/icons/icon57.png",
  "72": "assets/icons/icon72.png",
  "78": "assets/icons/icon78.png",
  "96": "assets/icons/icon96.png",
  "114": "assets/icons/icon114.png",
  "120": "assets/icons/icon120.png",
  "128": "assets/icons/icon128.png",
  "144": "assets/icons/icon144.png",
  "152": "assets/icons/icon152.png"
}</code></pre>

<p>The icons will be copied to the appropriate places for each platform every time you run <code>cca prepare</code>.</p>

<h3 id="splash-screens">Splash Screens</h3>

<p>Apps on iOS show a brief splash screen as the app is loading. A set of default Cordova splash screens are included in <code>platforms/ios/[AppName]/Resources/splash</code>.  </p>

<p>The sizes needed are:</p>

<ul><li>320px x 480px + 2x</li><li>768px x 1024px + 2x (iPad portrait)</li><li>1024px x 768px + 2x (iPad landscape)</li><li>640px x 1146px</li></ul>

<p>Splash screen images are not currently modified by <code>cca</code>.</p>



<h2 id="step-5-publish">Step 5: Publish</h2>

<p>In your project's <code>platforms</code> directory, you have two complete native projects: one for Android, and one for iOS. You can build release versions of these projects and publish them to Google Play or to the iOS App Store.</p>

<h3 id="publish-to-the-play-store">Publish to the Play Store</h3>

<p>To publish your Android application to the Play Store:</p>

<ol><li><p>Update the two Android version ids, then run <code>cca prepare</code>:</p><ul><li><code>android:versionName</code> is set using the <code>version</code> key in <code>www/manifest.json</code> (this sets the version of your desktop packaged app, too).</li><li><p><code>android:versionCode</code> is set using the <code>versionCode</code> key in <code>www/manifest.mobile.js</code>.</p></li></ul></li><li><p>Edit (or create) <code>platforms/android/ant.properties</code> and set the <code>key.store</code> and <code>key.alias</code> properties (as explained <a href="http://developer.android.com/tools/building/building-cmdline.html#ReleaseMode">in the Android developer docs</a>).</p></li><li><p>Build your project:</p><pre><code>./platforms/android/cordova/build --release</code></pre></li><li><p>Find your signed .apk located inside <code>platforms/android/ant-build/</code>.</p></li><li><p>Upload your signed application to the <a href="https://play.google.com/apps/publish">Google Play developer console</a>.</p></li></ol>

<h3 id="publish-to-the-ios-app-store">Publish to the iOS App Store</h3>

<ol><li><p>Update the app version by setting the <code>CFBundleVersion</code> key in <code>www/manifest.mobile.js</code>, then run <code>cca prepare</code>.</p></li><li><p>Open the Xcode project file found under your <code>platforms/ios</code> directory:</p><p>open platforms/ios/*.xcodeproj</p></li><li><p>Follow Apple's <a href="https://developer.apple.com/library/ios/documentation/IDEs/Conceptual/AppDistributionGuide/Introduction/Introduction.html">App Distribution Guide</a>.</p></li></ol>

<h2 id="special-considerations">Special considerations</h2>

<p>If you're new to Chrome Apps, the biggest gotcha is that some <a href="http://developer.chrome.com/apps/app_deprecated">web features are disabled</a>. However, several of these do currently work within Cordova.</p>

<p>A Chrome App may not work out of the box on mobile. Some common problems with porting to mobile:</p>

<ul><li>Layout issues with small screens, especially while in a portrait orientation.<ul><li><em>Suggested fix:</em> Use <a href="http://www.html5rocks.com/en/mobile/mobifying/#toc-mediaqueries">CSS media queries</a> to optimize your content for smaller screens.</li></ul></li><li>Chrome App window sizes set via <a href="http://developer.chrome.com/apps/app_window.html">chrome.app.window</a> will be ignored, instead using the device's native dimensions.<ul><li><em>Suggested fix:</em> Remove hard-coded window dimensions; design your app with different sizes in mind.</li></ul></li><li>Small buttons and links will be hard to tap with a finger.<ul><li><em>Suggested fix:</em> Adjust your touch targets to be at least 44 x 44 points. </li></ul></li><li>Unexpected behavior when relying on mouse hover which does not exist on touch screens.<ul><li><em>Suggested fix:</em> In addition to hover, activate UI elements such as dropdowns and tooltips on tap.</li></ul></li><li>A 300ms tap delay.<ul><li><em>Suggested fix:</em> Use the <a href="https://github.com/ftlabs/fastclick">FastClick by FT Labs</a> JavaScript polyfill.</li><li>Read this <a href="http://updates.html5rocks.com/2013/12/300ms-tap-delay-gone-away">HTML5Rocks article</a> for some background info.</li></ul></li></ul>

<h3 id="supported-chrome-apis">Supported Chrome APIs</h3>

<p>We've made many of the core Chrome APIs available to Chrome Apps for Mobile, including:</p>

<ul><li><a href="http://developer.chrome.com/apps/identity.html">identity</a> - sign-in users using OAuth2</li><li><a href="https://github.com/MobileChromeApps/mobile-chrome-apps/blob/master/chrome-cordova/plugins/google.payments/README.md">payments</a> - sell virtual goods within your mobile app</li><li><a href="http://developer.chrome.com/apps/pushMessaging.html">pushMessaging</a> - push messages to your app from your server</li><li><a href="http://developer.chrome.com/apps/sockets.html">sockets</a> - send and receive data over the network using TCP and UDP</li><li><a href="http://developer.chrome.com/apps/notifications.html">notifications</a> (Android only) - send rich notifications from your mobile app</li><li><a href="http://developer.chrome.com/apps/storage.html">storage</a> - store and retrieve key-value data locally</li><li><a href="http://developer.chrome.com/apps/syncFileSystem.html">syncFileSystem</a> - store and retrieve files backed by Google Drive</li><li><a href="http://developer.chrome.com/apps/alarms.html">alarms</a> - run tasks periodically</li><li><a href="http://developer.chrome.com/apps/idle.html">idle</a> -  detect when the machine's idle state changes</li><li><a href="http://developer.chrome.com/apps/power.html">power</a> - override the system's power management features</li></ul>

<p>However, not all Chrome JavaScript APIs are implemented. And not all Chrome Desktop features are available on mobile:</p>

<ul><li>no <code>&lt;webview&gt;</code> tag</li><li>no IndexedDB</li><li>no getUserMedia()</li><li>no NaCl</li></ul>

<p>You can track progress from our <a href="https://github.com/MobileChromeApps/mobile-chrome-apps/blob/master/docs/APIStatus.md">API Status</a> page.</p>



<h2 id="chrome-apps-developer-tool">Chrome Apps Developer Tool</h2>

<p>The Chrome Apps Developer Tool (ADT) for Android is a standalone Android app that allows you to download and run a Chrome App without setting up the development toolchain as described above. Use the Chrome ADT when you want to quickly preview an existing Chrome App (already packaged as a .crx) on your Android device.</p>

<p>The Chrome ADT for Android is currently in a pre-alpha release. To try it out, view the <a href="https://github.com/MobileChromeApps/harness/releases/">ChromeADT.apk release notes</a> for installation and usage instructions.</p>