Author: shazron
Date: Sun May 25 04:21:25 2014
New Revision: 1597382
URL: http://svn.apache.org/r1597382
Log:
Added new files in en/edge
Added:
cordova/site/public/docs/en/edge/guide_appdev_security_index.md.html
cordova/site/public/docs/en/edge/guide_next_index.md.html
Added: cordova/site/public/docs/en/edge/guide_appdev_security_index.md.html
URL:
http://svn.apache.org/viewvc/cordova/site/public/docs/en/edge/guide_appdev_security_index.md.html?rev=1597382&view=auto
==============================================================================
--- cordova/site/public/docs/en/edge/guide_appdev_security_index.md.html (added)
+++ cordova/site/public/docs/en/edge/guide_appdev_security_index.md.html Sun
May 25 04:21:25 2014
@@ -0,0 +1,265 @@
+<!DOCTYPE html>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+--><html lang="en">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0,
user-scalable=no, width=device-width">
+<meta name="generator" content="joDoc">
+<title>Apache Cordova API Documentation</title>
+<link rel="stylesheet" type="text/css" href="index.css">
+<link rel="stylesheet" type="text/css" href="mobile.css" media="only screen
and (max-device-width: 1024px)">
+<link rel="stylesheet" type="text/css" href="prettify/prettify.css">
+</head>
+<body>
+ <div id="header">
+ <h1><a href="index.html">Apache <strong>Cordova</strong>
Documentation</a></h1>
+ <small>
+ <select><optgroup label="Chinese" value="zh">
+<option value="edge">edge</option>
+<option value="3.4.0">3.4.0</option>
+<option value="3.1.0">3.1.0</option>
+</optgroup>
+<optgroup label="English" value="en">
+<option selected value="edge">edge</option>
+<option value="3.5.0">3.5.0</option>
+<option value="3.4.0">3.4.0</option>
+<option value="3.3.0">3.3.0</option>
+<option value="3.2.0">3.2.0</option>
+<option value="3.1.0">3.1.0</option>
+<option value="3.0.0">3.0.0</option>
+<option value="2.9.0">2.9.0</option>
+<option value="2.8.0">2.8.0</option>
+<option value="2.7.0">2.7.0</option>
+<option value="2.6.0">2.6.0</option>
+<option value="2.5.0">2.5.0</option>
+<option value="2.4.0">2.4.0</option>
+<option value="2.3.0">2.3.0</option>
+<option value="2.2.0">2.2.0</option>
+<option value="2.1.0">2.1.0</option>
+<option value="2.0.0">2.0.0</option>
+<option value="1.9.0">1.9.0</option>
+<option value="1.8.1">1.8.1</option>
+<option value="1.8.0">1.8.0</option>
+<option value="1.7.0">1.7.0</option>
+<option value="1.6.1">1.6.1</option>
+<option value="1.6.0">1.6.0</option>
+<option value="1.5.0">1.5.0</option>
+</optgroup>
+<optgroup label="French" value="fr">
+<option value="edge">edge</option>
+<option value="3.4.0">3.4.0</option>
+<option value="3.1.0">3.1.0</option>
+</optgroup>
+<optgroup label="German" value="de">
+<option value="edge">edge</option>
+<option value="3.4.0">3.4.0</option>
+<option value="3.1.0">3.1.0</option>
+</optgroup>
+<optgroup label="Italian" value="it">
+<option value="edge">edge</option>
+<option value="3.4.0">3.4.0</option>
+<option value="3.1.0">3.1.0</option>
+</optgroup>
+<optgroup label="Japanese" value="ja">
+<option value="edge">edge</option>
+<option value="3.4.0">3.4.0</option>
+<option value="3.1.0">3.1.0</option>
+<option value="2.2.0">2.2.0</option>
+<option value="2.1.0">2.1.0</option>
+<option value="2.0.0">2.0.0</option>
+<option value="1.9.0">1.9.0</option>
+<option value="1.8.1">1.8.1</option>
+<option value="1.7.0">1.7.0</option>
+</optgroup>
+<optgroup label="Korean" value="ko">
+<option value="edge">edge</option>
+<option value="3.4.0">3.4.0</option>
+<option value="3.1.0">3.1.0</option>
+<option value="2.0.0">2.0.0</option>
+</optgroup>
+<optgroup label="Russian" value="ru">
+<option value="edge">edge</option>
+<option value="3.4.0">3.4.0</option>
+<option value="3.1.0">3.1.0</option>
+</optgroup>
+<optgroup label="Slovenian" value="sl">
+<option value="edge">edge</option>
+<option value="3.4.0">3.4.0</option>
+</optgroup>
+<optgroup label="Spanish" value="es">
+<option value="edge">edge</option>
+<option value="3.4.0">3.4.0</option>
+<option value="3.1.0">3.1.0</option>
+</optgroup></select></small>
+ </div>
+ <div id="subheader">
+ <h1>Security Guide</h1>
+ <small><select><option value="Security%2520Guide">Security
Guide</option>
+<option value="Security%20Guide_this_guide_discusses_the_following_topics">Â Â
    - This guide discusses the following topics:</option>
+<option value="Security%20Guide_whitelist">Â Â Â Â Â Â - Whitelist</option>
+<option value="Security%20Guide_iframes_and_the_callback_id_mechanism">Â Â Â Â
  - Iframes and the Callback Id Mechanism</option>
+<option value="Security%20Guide_certificate_pinning">Â Â Â Â Â Â - Certificate
Pinning</option>
+<option value="Security%20Guide_self_signed_certificates">Â Â Â Â Â Â -
Self-signed Certificates</option>
+<option value="Security%20Guide_encrypted_storage">Â Â Â Â Â Â - Encrypted
storage</option>
+<option value="Security%20Guide_general_tips">Â Â Â Â Â Â - General
Tips</option>
+<option value="Security%20Guide_recommended_articles_and_other_resources">Â Â
    - Recommended Articles and Other Resources</option></select></small>
+ </div>
+
+ <div id="sidebar">
+ <div class="vertical_divider"></div>
+ <h1>Guides</h1>
+<ul>
+<li><a href="guide_overview_index.md.html#Overview">Overview</a></li>
+<li><a href="guide_support_index.md.html#Platform%20Support">Platform
Support</a></li>
+<li><a href="guide_cli_index.md.html#The%20Command-Line%20Interface">The
Command-Line Interface</a></li>
+<li><a href="guide_platforms_index.md.html#Platform%20Guides">Platform
Guides</a></li>
+<li><a
href="plugin_ref_plugman.md.html#Using%20Plugman%20to%20Manage%20Plugins">Using
Plugman to Manage Plugins</a></li>
+<li><a href="config_ref_index.md.html#The%20config.xml%20File">The config.xml
File</a></li>
+<li><a href="config_ref_images.md.html#Icons%20and%20Splash%20Screens">Icons
and Splash Screens</a></li>
+<li><a
href="guide_hybrid_webviews_index.md.html#Embedding%20WebViews">Embedding
WebViews</a></li>
+<li><a
href="guide_hybrid_plugins_index.md.html#Plugin%20Development%20Guide">Plugin
Development Guide</a></li>
+<li><a href="guide_appdev_privacy_index.md.html#Privacy%20Guide">Privacy
Guide</a></li>
+<li><a href="guide_appdev_security_index.md.html#Security%20Guide">Security
Guide</a></li>
+<li><a href="guide_appdev_whitelist_index.md.html#Whitelist%20Guide">Whitelist
Guide</a></li>
+<li><a href="cordova_storage_storage.md.html#Storage">Storage</a></li>
+<li><a href="guide_next_index.md.html#Next%20Steps">Next Steps</a></li>
+<li><a href="_index.html">Keyword Index</a></li>
+</ul>
+<h1>API Reference</h1>
+<ul>
+<li><a href="cordova_events_events.md.html#Events">Events</a></li>
+<li><a href="cordova_plugins_pluginapis.md.html#Plugin%20APIs">Plugin
APIs</a></li>
+</ul>
+</div>
+
+ <div id="scrollable">
+ <div id="content">
+ <h1><a name="Security%20Guide">Security Guide</a></h1>
+
+<p>The following guide includes some security best practices that you should
consider when developing a Cordova application. Please be aware that security
is a very complicated topic and therefore this guide is not exhaustive. If you
believe you can contribute to this guide, please feel free to file an issue in
Cordova's bug tracker under <a class="external"
href="https://issues.apache.org/jira/browse/CB/component/12316407";>"Documentation"</a>.
This guide is designed to be applicable to general Cordova development (all
platforms) but special platform-specific considerations will be noted. </p>
+
+<h2>
+<a name="Security%20Guide_this_guide_discusses_the_following_topics">This
guide discusses the following topics:</a>
+</h2>
+
+<ul>
+<li>Whitelist</li>
+<li>Iframes and the Callback Id Mechanism</li>
+<li>Certificate Pinning</li>
+<li>Self-signed Certificates</li>
+<li>Encrypted storage</li>
+<li>General Tips</li>
+<li>Recommended Articles and Other Resources</li>
+</ul>
+<h2>
+<a name="Security%20Guide_whitelist">Whitelist</a>
+</h2>
+
+<ul>
+<li><p>Read and understand the <a
href="guide_appdev_whitelist_index.md.html#Whitelist%20Guide">Whitelist
Guide</a></p></li>
+<li><p>By default, the Whitelist on a newly created app will allow access to
every domain through the <code><access></code> tag:
+ <code><access origin="*"></code>
+If you want network requests to be evaluated against the whitelist, then it is
important to change this and only allow the domains to which you need access.
This can be done by editing the application-level config file located at:
+ <code>{project}/config.xml</code> (recent projects) or
<code>{project}/www/config.xml</code> (older projects)</p></li>
+<li><p>Android's Whitelist on Cordova 2.9.x is considered secure, however, it
was discovered that if foo.com is included in the whitelist, foo.com.evil.com
would be able to pass the whitelist test. This was fixed in Cordova 3.x.
</p></li>
+<li><p>Domain whitelisting does not work on Android API 10 and below, and
WP7/8 for iframes and XMLHttpRequest. This means an attacker can load any
domain in an iframe and any script on that page within the iframe can directly
access Cordova JavaScript objects and the corresponding native Java objects.
You should take this into consideration when building applications for these
platforms. In practice this means making sure you target an Android API higher
than 10, and that if possible you do not use an iframe to load external content
- use the inAppBrowser plugin or other third-party plugins. </p></li>
+</ul>
+<h2>
+<a name="Security%20Guide_iframes_and_the_callback_id_mechanism">Iframes and
the Callback Id Mechanism</a>
+</h2>
+
+<p>If content is served in an iframe from a whitelisted domain, that domain
will have access to the native Cordova bridge. This means that if you whitelist
a third-party advertising network and serve those ads through an iframe, it is
possible that a malicious ad will be able to break out of the iframe and
perform malicious actions. Because of this, you should generally not use
iframes unless you control the server that hosts the iframe content. Also note
that there are third party plugins available to support advertising networks.
Note that this statement is not true for iOS, which intercepts everything
including iframe connections. </p>
+
+<h2>
+<a name="Security%20Guide_certificate_pinning">Certificate Pinning</a>
+</h2>
+
+<p>Cordova does not support true certificate pinning. The main barrier to this
is a lack of native APIs in Android for intercepting SSL connections to perform
the check of the server's certificate. (Although it is possible to do
certificate pinning on Android in Java using JSSE, the webview on Android is
written in C++, and server connections are handled for you by the webview, so
it is not possible to use Java and JSSE there.) Since Apache Cordova is meant
to offer consistent APIs across multiple platforms, not having a capability in
a major platform breaks that consistency.</p>
+
+<p>There are ways to approximate certificate pinning, such as checking the
server's public key (fingerprint) is the expected value when your application
starts or at other various times during your application's lifetime. There are
third-party plugins available for Cordova that can do that. However, this is
not the same as true certificate pinning which automatically verifies the
expected value on every connection to the server.</p>
+
+<h2>
+<a name="Security%20Guide_self_signed_certificates">Self-signed
Certificates</a>
+</h2>
+
+<p>Using self-signed certificates on your server is not recommended. If you
desire SSL, then it is highly recommended that your server have a certificate
that has been properly signed by a well-known CA (certificate authority). The
inability to do true certificate pinning makes this important.</p>
+
+<p>The reason is that accepting self-signed certificates bypasses the
certificate chain validation, which allows any server certificate to be
considered valid by the device. This opens up the communication to
man-in-the-middle attacks. It becomes very easy for a hacker to not only
intercept and read all communication between the device and the server, but
also to modify the communication. The device will never know this is happening
because it doesn't verify that the server's certificate is signed by a trusted
CA. The device has no proof that the server is who it expects. Because of the
ease of doing a man-in-the-middle attack, accepting self-signed certificates is
only marginally better than just running http instead of https on an untrusted
network. Yes, the traffic would be encrypted, but it could be encrypted with
the key from a man-in-the-middle, so the man-in-the-middle can access
everything, so encryption is useless except to passive observers. Users trust
SSL to be secure, a
nd this would be deliberately making it insecure, so the SSL use becomes
misleading. If this will be used on a trusted network (i.e., you are entirely
inside a controlled enterprise), then self-signed certs are still not
recommended. The two recommendations in a trusted network are to just use http
because the network itself is trusted, or to get a certificate signed by a
trusted CA (not self-signed). Either the network is trusted or it is not.</p>
+
+<p>The principles described here are not specific to Apache Cordova, they
apply to all client-server communication.</p>
+
+<p>When running Cordova on Android, using
<code>android:debuggable="true"</code> in the application manifest will permit
SSL errors such as certificate chain validation errors on self-signed certs. So
you can use self-signed certs in this configuration, but this is not a
configuration that should be used when your application is in production. It is
meant to be used only during application development.</p>
+
+<h2>
+<a name="Security%20Guide_encrypted_storage">Encrypted storage</a>
+</h2>
+
+<h2>
+<a name="Security%20Guide_general_tips">General Tips</a>
+</h2>
+
+<h3>Do not use Android Gingerbread!</h3>
+
+<ul>
+<li>Set your min-target-sdk level higher than 10. API 10 is Gingerbread, and
Gingerbread is no longer supported by Google or device manufacturers, and is
therefore not recommend by the Cordova team. </li>
+<li>Gingerbread has been shown to be insecure and one of the most targeted
mobile OSs <a class="external"
href="http://bgr.com/2012/11/06/android-security-gingerbread-malware/";>http://www.mobilemag.com/2012/11/06/andriod-2-3-gingerbread-security/</a>.
</li>
+<li>The Whitelist on Android does not work with Gingerbread or lower. This
means an attacker can load malicious code in an iframe that would then have
access to all of the Cordova APIs and could use that access to steal personal
data, send SMS messages to premium-rate numbers, and perform other malicious
acts. </li>
+</ul>
+<h3>Use InAppBrowser for outside links</h3>
+
+<ul>
+<li>Use the InAppBrowser when opening links to any outside website. This is
much safer than whitelisting a domain name and including the content directly
in your application because the InAppBrowser will use the native browser's
security features and will not give the website access to your Cordova
environment. Even if you trust the third party website and include it directly
in your application, that third party website could link to malicious web
content. </li>
+</ul>
+<h3>Validate all user input</h3>
+
+<ul>
+<li>Always validate any and all input that your application accepts. This
includes usernames, passwords, dates, uploaded media, etc. Because an attacker
could manipulate your HTML and JS assets (either by decompiling your
application or using debugging tools like chrome://inspect), this validation
should also be performed on your server, especially before handing the data off
to any backend service. </li>
+<li>Other sources where data should be validated: user documents, contacts,
push notifications</li>
+</ul>
+<h3>Do not cache sensitive data</h3>
+
+<ul>
+<li>If usernames, password, geolocation information, and other sensitive data
is cached, then it could potentially be retrieved later by an unauthorized user
or application.</li>
+</ul>
+<h3>Don't use eval() unless you know what you're doing</h3>
+
+<ul>
+<li>The JavaScript function eval() has a long history of being abused. Using
it incorrectly can open your code up for injection attacks, debugging
difficulties, and slower code execution. </li>
+</ul>
+<h3>Do not assume that your source code is secure</h3>
+
+<ul>
+<li>Since a Cordova application is built from HTML and JavaScript assets that
get packaged in a native container, you should not consider your code to be
secure. It is possible to reverse engineer a Cordova application. </li>
+</ul>
+<h2>
+<a
name="Security%20Guide_recommended_articles_and_other_resources">Recommended
Articles and Other Resources</a>
+</h2>
+
+<ul>
+<li><a class="external"
href="https://www.owasp.org/index.php/HTML5_Security_Cheat_Sheet";>HTML5
Security cheat sheet, detailing how to secure your HTML5 application</a></li>
+<li><a class="external"
href="https://github.com/phonegap/phonegap/wiki/Platform-Security";>Phonegap's
article on device security, such as using encrypted data</a></li>
+<li><a class="external"
href="http://www.cis.syr.edu/~wedu/Research/paper/webview_acsac2011.pdf";>Whitepaper
about well known security flaws in Webview based hybrid applications</a></li>
+</ul>
+</div>
+ </div>
+
+ <!-- Functionality and Syntax Highlighting -->
+ <script type="text/javascript" src="index.js"></script><script
type="text/javascript" src="prettify/prettify.js"></script>
+</body>
+</html>
Added: cordova/site/public/docs/en/edge/guide_next_index.md.html
URL:
http://svn.apache.org/viewvc/cordova/site/public/docs/en/edge/guide_next_index.md.html?rev=1597382&view=auto
==============================================================================
--- cordova/site/public/docs/en/edge/guide_next_index.md.html (added)
+++ cordova/site/public/docs/en/edge/guide_next_index.md.html Sun May 25
04:21:25 2014
@@ -0,0 +1,396 @@
+<!DOCTYPE html>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+--><html lang="en">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0,
user-scalable=no, width=device-width">
+<meta name="generator" content="joDoc">
+<title>Apache Cordova API Documentation</title>
+<link rel="stylesheet" type="text/css" href="index.css">
+<link rel="stylesheet" type="text/css" href="mobile.css" media="only screen
and (max-device-width: 1024px)">
+<link rel="stylesheet" type="text/css" href="prettify/prettify.css">
+</head>
+<body>
+ <div id="header">
+ <h1><a href="index.html">Apache <strong>Cordova</strong>
Documentation</a></h1>
+ <small>
+ <select><optgroup label="Chinese" value="zh">
+<option value="edge">edge</option>
+<option value="3.4.0">3.4.0</option>
+<option value="3.1.0">3.1.0</option>
+</optgroup>
+<optgroup label="English" value="en">
+<option selected value="edge">edge</option>
+<option value="3.5.0">3.5.0</option>
+<option value="3.4.0">3.4.0</option>
+<option value="3.3.0">3.3.0</option>
+<option value="3.2.0">3.2.0</option>
+<option value="3.1.0">3.1.0</option>
+<option value="3.0.0">3.0.0</option>
+<option value="2.9.0">2.9.0</option>
+<option value="2.8.0">2.8.0</option>
+<option value="2.7.0">2.7.0</option>
+<option value="2.6.0">2.6.0</option>
+<option value="2.5.0">2.5.0</option>
+<option value="2.4.0">2.4.0</option>
+<option value="2.3.0">2.3.0</option>
+<option value="2.2.0">2.2.0</option>
+<option value="2.1.0">2.1.0</option>
+<option value="2.0.0">2.0.0</option>
+<option value="1.9.0">1.9.0</option>
+<option value="1.8.1">1.8.1</option>
+<option value="1.8.0">1.8.0</option>
+<option value="1.7.0">1.7.0</option>
+<option value="1.6.1">1.6.1</option>
+<option value="1.6.0">1.6.0</option>
+<option value="1.5.0">1.5.0</option>
+</optgroup>
+<optgroup label="French" value="fr">
+<option value="edge">edge</option>
+<option value="3.4.0">3.4.0</option>
+<option value="3.1.0">3.1.0</option>
+</optgroup>
+<optgroup label="German" value="de">
+<option value="edge">edge</option>
+<option value="3.4.0">3.4.0</option>
+<option value="3.1.0">3.1.0</option>
+</optgroup>
+<optgroup label="Italian" value="it">
+<option value="edge">edge</option>
+<option value="3.4.0">3.4.0</option>
+<option value="3.1.0">3.1.0</option>
+</optgroup>
+<optgroup label="Japanese" value="ja">
+<option value="edge">edge</option>
+<option value="3.4.0">3.4.0</option>
+<option value="3.1.0">3.1.0</option>
+<option value="2.2.0">2.2.0</option>
+<option value="2.1.0">2.1.0</option>
+<option value="2.0.0">2.0.0</option>
+<option value="1.9.0">1.9.0</option>
+<option value="1.8.1">1.8.1</option>
+<option value="1.7.0">1.7.0</option>
+</optgroup>
+<optgroup label="Korean" value="ko">
+<option value="edge">edge</option>
+<option value="3.4.0">3.4.0</option>
+<option value="3.1.0">3.1.0</option>
+<option value="2.0.0">2.0.0</option>
+</optgroup>
+<optgroup label="Russian" value="ru">
+<option value="edge">edge</option>
+<option value="3.4.0">3.4.0</option>
+<option value="3.1.0">3.1.0</option>
+</optgroup>
+<optgroup label="Slovenian" value="sl">
+<option value="edge">edge</option>
+<option value="3.4.0">3.4.0</option>
+</optgroup>
+<optgroup label="Spanish" value="es">
+<option value="edge">edge</option>
+<option value="3.4.0">3.4.0</option>
+<option value="3.1.0">3.1.0</option>
+</optgroup></select></small>
+ </div>
+ <div id="subheader">
+ <h1>Next Steps</h1>
+ <small><select><option value="Next%2520Steps">Next Steps</option>
+<option value="Best%2520Practices">Best Practices</option>
+<option value="Best%20Practices_1_spa_is_your_friend">Â Â Â Â Â Â - 1) SPA Is
Your Friend</option>
+<option value="Best%20Practices_2_performance_considerations">Â Â Â Â Â Â - 2)
Performance Considerations</option>
+<option value="Best%20Practices_3_recognize_and_handle_offline_status">Â Â Â Â
  - 3) Recognize and Handle Offline Status</option>
+<option value="Handling%2520Upgrades">Handling Upgrades</option>
+<option value="Handling%20Upgrades_upgrading_cordova_projects">Â Â Â Â Â Â -
Upgrading Cordova Projects</option>
+<option value="Handling%20Upgrades_plugin_upgrades">Â Â Â Â Â Â - Plugin
Upgrades</option>
+<option value="Testing">Testing</option>
+<option value="Testing_testing_on_a_simulator_vs_on_a_real_device">Â Â Â Â Â Â
-
+Testing on a simulator vs. on a real device</option>
+<option value="Debugging">Debugging</option>
+<option value="Debugging_safari_remote_debugging">Â Â Â Â Â Â - Safari Remote
Debugging
+</option>
+<option value="Debugging_chrome_remote_debugging">Â Â Â Â Â Â - Chrome Remote
Debugging
+</option>
+<option value="Debugging_ripple">Â Â Â Â Â Â - Ripple</option>
+<option value="Debugging_weinre">Â Â Â Â Â Â - Weinre</option>
+<option value="Debugging_other_options">Â Â Â Â Â Â - Other Options</option>
+<option value="User%2520Interface">User Interface</option>
+<option value="User%20Interface_additional_ui_articles_and_resources">Â Â Â Â
  - Additional UI Articles and Resources</option>
+<option value="Keeping%2520Up">Keeping Up</option>
+<option value="Getting%2520Help">Getting Help</option></select></small>
+ </div>
+
+ <div id="sidebar">
+ <div class="vertical_divider"></div>
+ <h1>Guides</h1>
+<ul>
+<li><a href="guide_overview_index.md.html#Overview">Overview</a></li>
+<li><a href="guide_support_index.md.html#Platform%20Support">Platform
Support</a></li>
+<li><a href="guide_cli_index.md.html#The%20Command-Line%20Interface">The
Command-Line Interface</a></li>
+<li><a href="guide_platforms_index.md.html#Platform%20Guides">Platform
Guides</a></li>
+<li><a
href="plugin_ref_plugman.md.html#Using%20Plugman%20to%20Manage%20Plugins">Using
Plugman to Manage Plugins</a></li>
+<li><a href="config_ref_index.md.html#The%20config.xml%20File">The config.xml
File</a></li>
+<li><a href="config_ref_images.md.html#Icons%20and%20Splash%20Screens">Icons
and Splash Screens</a></li>
+<li><a
href="guide_hybrid_webviews_index.md.html#Embedding%20WebViews">Embedding
WebViews</a></li>
+<li><a
href="guide_hybrid_plugins_index.md.html#Plugin%20Development%20Guide">Plugin
Development Guide</a></li>
+<li><a href="guide_appdev_privacy_index.md.html#Privacy%20Guide">Privacy
Guide</a></li>
+<li><a href="guide_appdev_security_index.md.html#Security%20Guide">Security
Guide</a></li>
+<li><a href="guide_appdev_whitelist_index.md.html#Whitelist%20Guide">Whitelist
Guide</a></li>
+<li><a href="cordova_storage_storage.md.html#Storage">Storage</a></li>
+<li><a href="guide_next_index.md.html#Next%20Steps">Next Steps</a></li>
+<li><a href="_index.html">Keyword Index</a></li>
+</ul>
+<h1>API Reference</h1>
+<ul>
+<li><a href="cordova_events_events.md.html#Events">Events</a></li>
+<li><a href="cordova_plugins_pluginapis.md.html#Plugin%20APIs">Plugin
APIs</a></li>
+</ul>
+</div>
+
+ <div id="scrollable">
+ <div id="content">
+ <h1><a name="Next%20Steps">Next Steps</a></h1>
+
+<p>For developers who have an understanding of how to use the Cordova CLI and
make use of plugins, there are a few things you may want to consider
researching next to build better, more performant Cordova applications. The
following document offers advice on various topics relating to best practices,
testing, upgrades, and other topics, but is not meant to be prescriptive.
Consider this your launching point for your growth as a Cordova developer.
Also, if you see something that can be improved, please <a class="external"
href="http://cordova.apache.org/#contribute";>contribute</a>!</p>
+
+<p>This guide contains the following topics:</p>
+
+<ul>
+<li><a href="guide_next_index.md.html#Best%20Practices">Best Practices</a></li>
+<li><a href="guide_next_index.md.html#Handling%20Upgrades">Handling
Upgrades</a></li>
+<li><a href="guide_next_index.md.html#Testing">Testing</a></li>
+<li><a href="guide_next_index.md.html#Debugging">Debugging</a></li>
+<li><a href="guide_next_index.md.html#User%20Interface">User Interface</a></li>
+<li><a href="guide_next_index.md.html#Keeping%20Up">Keeping Up</a></li>
+<li>
+<a href="guide_next_index.md.html#Getting%20Help">Getting Help</a> </li>
+</ul>
+<h1><a name="Best%20Practices">Best Practices</a></h1>
+
+<h2>
+<a name="Best%20Practices_1_spa_is_your_friend">1) SPA Is Your Friend</a>
+</h2>
+
+<p>First and foremost - your Cordova applications should adopt the SPA (Single
Page Application) design. Loosely defined, a SPA is a client-side application
that is run from one request of a web page. The user loads an initial set of
resources (HTML, CSS, and JavaScript) and further updates (showing a new view,
loading data) is done via AJAX. SPAs are commonly used for more complex
client-side applications. GMail is a great example of this. After you load
GMail, mail views, editing, and organization are all done by updating the DOM
instead of actually leaving the current page to load a completely new one. </p>
+
+<p>Using a SPA can help you organize your application in a more efficient
manner, but it also has specific benefits for Cordova applications. A Cordova
application must wait for the <a
href="cordova_events_events.md.html#deviceready">deviceready</a> event to fire
before any plugins may be used. If you do not use a SPA, and your user clicks
to go from one page to another, you will have to wait for <a
href="cordova_events_events.md.html#deviceready">deviceready</a> to fire again
before you make use of a plugin. This is easy to forget as your application
gets larger. </p>
+
+<p>Even if you choose not to use Cordova, creating a mobile application
without using a single page architecture will have serious performance
implications. This is because navigating between pages will require scripts,
assets, etc., to be reloaded. Even if these assets are cached, there will still
be performance issues. </p>
+
+<p>Examples of SPA libraries you can use in your Cordova applications are:</p>
+
+<ul>
+<li><a class="external" href="http://angularjs.org";>AngularJS</a></li>
+<li><a class="external" href="http://backbonejs.org";>Backbone</a></li>
+<li><a class="external" href="http://www.telerik.com/kendo-ui";>Kendo
UI</a></li>
+<li><a class="external" href="http://monaca.mobi/en/";>Monaca</a></li>
+<li><a class="external"
href="http://facebook.github.io/react/";>ReactJS</a></li>
+<li><a class="external" href="http://www.sencha.com/products/touch/";>Sencha
Touch</a></li>
+<li><a href="jquerymobile.com">jQuery Mobile</a></li>
+</ul>
+<p>And many, many, more.</p>
+
+<h2>
+<a name="Best%20Practices_2_performance_considerations">2) Performance
Considerations</a>
+</h2>
+
+<p>One of the biggest mistakes a new Cordova developer can make is to assume
that the performance they get on a desktop machine is the same they will get on
a mobile device. While our mobile devices have gotten more powerful every year,
they still lack the power and performance of a desktop. Mobile devices
typically have much less RAM and a GPU that is a far cry from their desktop (or
even laptop) brethren. A full list of tips here would be too much, but here are
a few things to keep in mind (with a list of longer resources at the end for
further research).</p>
+
+<p><strong>Click versus Touch</strong> - The biggest and simplest mistake you
can make is to use click events. While these "work" just fine on mobile, most
devices impose a 300ms delay on them in order to distinguish between a touch
and a touch "hold" event. Using <code>touchstart</code>, or
<code>touchend</code>, will result in a dramatic improvement - 300ms doesn't
sound like much, but it can result in jerky UI updates and behavior. You should
also consider the fact that âtouchâ events are not supported on non-webkit
browsers, see <a class="external"
href="http://caniuse.com/#search=touch";>CanIUse</a>. In order to deal with
these limitations, you can checkout various libraries like HandJS and
Fastouch.</p>
+
+<p><strong>CSS Transitions versus DOM Manipulation</strong> - Using hardware
accelerated CSS transitions will be dramatically better than using JavaScript
to create animations. See the list of resources at the end of this section for
examples.</p>
+
+<p><strong>Networks Suck</strong> - Ok, networks don't always suck, but the
latency of mobile networks, even good mobile networks, is far worse than you
probably think. A desktop app that slurps down 500 rows of JSON data, every 30
seconds, will be both slower on a mobile device as well as a battery hog. Keep
in mind that Cordova apps have multiple ways to persist data in the app
(LocalStorage and the file system for example). Cache that data locally and be
cognizant of the amount of data you are sending back and forth. This is an
especially important consideration when your application is connected over a
cellular network.</p>
+
+<p><strong>Additional Performance Articles and Resources</strong></p>
+
+<ul>
+<li><a class="external" href="http://sintaxi.com/you-half-assed-it";>"You half
assed it"</a></li>
+<li><a class="external"
href="http://coenraets.org/blog/2013/10/top-10-performance-techniques-for-phonegap-and-hybrid-apps-slides-available/";>"Top
Ten Performance Tips for PhoneGap and Hybrid Apps"</a></li>
+<li>"Fast Apps and Sites with JavaScript": http://channel9.msdn.com/<a
href="cordova_events_events.md.html#Events">Events</a>/Build/2013/4-313</li>
+</ul>
+<h2>
+<a name="Best%20Practices_3_recognize_and_handle_offline_status">3) Recognize
and Handle Offline Status</a>
+</h2>
+
+<p>See the previous tip about networks. Not only can you be on a slow network,
it is entirely possible for your application to be completely offline. Your
application should handle this in an intelligent manner. If your application
does not, people will think your application is broken. Given how easy it is to
handle (Cordova supports listening for both an offline and online event), there
is absolutely no reason for your application to not respond well when run
offline. Be sure to test (see the <a
href="guide_next_index.md.html#Testing">Testing</a> section below) your
application and be sure to test how your application handles when you start in
one state and then switch to another.</p>
+
+<p>Note that the online and offline events, as well as the Network Connection
API is not perfect. You may need to rely on using an XHR request to see if the
device is truly offline or online. At the end of the day, be sure add some form
of support for network issues - in fact, the Apple store (and probably other
stores) will reject apps that donât properly handle offline/online states.
For more discussion on this topic, see
+<a class="external"
href="http://blogs.telerik.com/appbuilder/posts/13-04-23/is-this-thing-on-%28part-1%29";>"Is
This Thing On?"</a></p>
+
+<h1><a name="Handling%20Upgrades">Handling Upgrades</a></h1>
+
+<h2>
+<a name="Handling%20Upgrades_upgrading_cordova_projects">Upgrading Cordova
Projects</a>
+</h2>
+
+<p>If your existing project was created using Cordova 3.x, you can upgrade the
project by issuing the following:</p>
+
+<pre class="prettyprint"><code>cordova platform update platform-name ios,
android, etc.
+</code></pre>
+
+<p>If your existing project was created under a version prior to Cordova 3.x,
it would probably be best to create a new Cordova 3.x project, and then copy
your existing projectâs code and assets to the new project. Typical steps:</p>
+
+<ul>
+<li>Create a new Cordova 3.x project (cordova create ...)</li>
+<li>Copy the www folder from your old project to the new project</li>
+<li>Copy any configuration settings from the old project to the new
project</li>
+<li>Add any plugins used in the old project to the new project</li>
+<li>Build your project</li>
+<li>Test, test, test!</li>
+</ul>
+<p>Regardless of the project's prior version, it is absolutely critical that
you read up on what was changed in the updated version, as the update may break
your code. The best place to find this information will be in the release notes
published both in the repositories and on the Cordova blog. You will want to
test your app thoroughly in order to verify that it is working correctly after
you perform the update.</p>
+
+<p>Note: some plugins may not be compatible with the new version of Cordova.
If a plugin is not compatible, you may be able to find a replacement plugin
that does what you need, or you may need to delay upgrading your project.
Alternatively, alter the plugin so that it does work under the new version and
contribute back to the community.</p>
+
+<h2>
+<a name="Handling%20Upgrades_plugin_upgrades">Plugin Upgrades</a>
+</h2>
+
+<p>As of Cordova 3.4, there is no mechanism for upgrading changed plugins
using a single command. Instead, remove the plugin and add it back to your
project, and the new version will be installed:</p>
+
+<pre class="prettyprint"><code>cordova plugin rm com.some.plugin
+cordova plugin add com.some.plugin
+</code></pre>
+
+<p>Be sure to check the updated plugin's documentation, as you may need to
adjust your code to work with the new version. Also, double check that the new
version of the plugin works with your projectâs version of Cordova.</p>
+
+<p>Always test your apps to ensure that installing the new plugin has not
broken something that you did not anticipate.</p>
+
+<p>If your project has a lot of plugins that you need updated, it might save
time to create a shell or batch script that removes and adds the plugins with
one command. </p>
+
+<h1><a name="Testing">Testing</a></h1>
+
+<p><a href="guide_next_index.md.html#Testing">Testing</a> your applications is
super important. The Cordova team uses Jasmine but any web friendly unit
testing solution will do. </p>
+
+<h2>
+<a name="Testing_testing_on_a_simulator_vs_on_a_real_device">
+Testing on a simulator vs. on a real device</a>
+</h2>
+
+<p>Itâs not uncommon to use desktop browsers and device simulators/emulators
when developing a Cordova application. However, it is incredibly important that
you test your app on as many physical devices as you possibly can:</p>
+
+<ul>
+<li>Simulators are just that: simulators. For example, your app may work in
the iOS simulator without a problem, but it may fail on a real device
(especially in certain circumstances, such as a low memory state). Or, your app
may actually fail on the simulator while it works just fine on a real device.
</li>
+<li>Emulators are just that: emulators. They do not represent how well your
app will run on a physical device. For example, some emulators may render your
app with a garbled display, while a real device has no problem. (If you do
encounter this problem, disable the host GPU in the emulator.)</li>
+<li>Simulators are generally faster than your physical device. Emulators, on
the other hand, are generally slower. Do not judge the performance of your app
by how it performs in a simulator or an emulator. Do judge the performance of
your app by how it runs on a spectrum of real devices.</li>
+<li>It's impossible to get a good feel for how your app responds to your touch
by using a simulator or an emulator. Instead, running the app on a real device
can point out problems with the sizes of user interface elements,
responsiveness, etc.</li>
+<li>Although it would be nice to be able to test only on one device per
platform, it is best to test on many devices sporting many different OS
versions. For example, what works on your particular Android smartphone may
fail on another Android device. What works on an iOS 7 device may fail on an
iOS 6 device.</li>
+</ul>
+<p>It is, of course, impossible to test on every possible device on the
market. For this reason, itâs wise to recruit many testers who have different
devices. Although they wonât catch every problem, chances are good that they
will discover quirks and issues that you would never find alone.</p>
+
+<p>Tip: It is possible on Android Nexus devices to easily flash different
versions of Android onto the device. This simple process will allow you to
easily test your application on different levels of Android with a single
device, without voiding your warranty or requiring you to âjailbreakâ or
ârootâ your device. The Google Android factory images and instructions are
located at: https://developers.google.com/android/nexus/images#instructions</p>
+
+<h1><a name="Debugging">Debugging</a></h1>
+
+<p><a href="guide_next_index.md.html#Debugging">Debugging</a> Cordova requires
some setup. Unlike a desktop application, you can't simply open dev tools on
your mobile device and start debugging, luckily there are some great
alternatives.</p>
+
+<h2>
+<a name="Debugging_safari_remote_debugging">Safari Remote Debugging
+</a>
+</h2>
+
+<p>The first option is Safari Remote <a
href="guide_next_index.md.html#Debugging">Debugging</a>. This works only on OSX
and only with iOS 6 (and higher). It uses Safari to connect to your device (or
the simulator) and will connect the browser's dev tools to the Cordova
application. You get what you expect from dev tools - DOM
inspection/manipulation, a JavaScript debugger, network inspection, the
console, and more. For more details, see this excellent blog post: <a
class="external"
href="http://moduscreate.com/enable-remote-web-inspector-in-ios-6/%5D";>http://moduscreate.com/enable-remote-web-inspector-in-ios-6/</a></p>
+
+<h2>
+<a name="Debugging_chrome_remote_debugging">Chrome Remote Debugging
+</a>
+</h2>
+
+<p>Virtually the same as the Safari version, this works with Android only but
can be used from any desktop operating system. It requires a minimum of Android
4.4 (KitKat), minimum API level of 19, and Chrome 30+ (on the desktop). Once
connected, you get the same Chrome Dev Tools experience for your mobile
applications as you do with your desktop applications. Even better, the Chrome
Dev Tools have a mirror option that shows your app running on the mobile
device. This is more than just a view - you can scroll and click from dev tools
and it updates on the mobile device. More details on Chrome Remote <a
href="guide_next_index.md.html#Debugging">Debugging</a> may be found here: <a
class="external"
href="https://developers.google.com/chrome/mobile/docs/debugging";>https://developers.google.com/chrome/mobile/docs/debugging</a></p>
+
+<p>It is possible to use Chrome Dev Tools to inspect iOS apps, through a
WebKit proxy: <a class="external"
href="https://github.com/google/ios-webkit-debug-proxy/";>https://github.com/google/ios-webkit-debug-proxy/</a></p>
+
+<h2>
+<a name="Debugging_ripple">Ripple</a>
+</h2>
+
+<p>Ripple is a desktop based emulator for Cordova projects. Essentially it
lets you run a Cordova application in your desktop application and fake various
Cordova features. For example, it lets you simulate the accelerometer to test
shake events. It fakes the camera API by letting you select a picture from your
hard drive. Ripple lets you focus more on your custom code rather than worrying
about Cordova plugins. You can find out more about Ripple here: <a
class="external"
href="http://ripple.incubator.apache.org/";>http://ripple.incubator.apache.org/</a></p>
+
+<h2>
+<a name="Debugging_weinre">Weinre</a>
+</h2>
+
+<p>Weinre creates a local server that can host a remote debug client for your
Cordova applications. After you've installed and started it up, you copy a line
of code into your Cordova application and then restart it. You can then open a
dev tool panel on your desktop to work with the application. Weinre is not
quite as fancy as Chrome and Safari Remote debugging but has the benefit of
working with a much greater range of operating systems and platforms. More
information may be found here: <a class="external"
href="http://people.apache.org/~pmuellr/weinre/docs/latest/";>http://people.apache.org/~pmuellr/weinre/docs/latest/</a></p>
+
+<h2>
+<a name="Debugging_other_options">Other Options</a>
+</h2>
+
+<ul>
+<li>BlackBerry 10 supports debugging as well: <a class="external"
href="https://developer.blackberry.com/html5/documentation/v2_0/debugging_using_web_inspector.html";>Documentation</a>
+</li>
+<li>You can debug using Firefox App Manager as well, see <a class="external"
href="https://hacks.mozilla.org/2014/02/building-cordova-apps-for-firefox-os/";>this
blog post</a> and this
+<a class="external"
href="https://developer.mozilla.org/en-US/Apps/Tools_and_frameworks/Cordova_support_for_Firefox_OS#Testing_and_debugging";>MDN
article</a>.</li>
+<li>For more examples and explanation of the above debugging tips, see: <a
class="external"
href="http://developer.telerik.com/featured/a-concise-guide-to-remote-debugging-on-ios-android-and-windows-phone/";>http://developer.telerik.com/featured/a-concise-guide-to-remote-debugging-on-ios-android-and-windows-phone/</a>
+</li>
+</ul>
+<h1><a name="User%20Interface">User Interface</a></h1>
+
+<p>Building a Cordova application that looks nice on mobile can be a
challenge, especially for developers. Many people chose to use a UI framework
to make this easier. Here is a short list of options you may want to
consider.</p>
+
+<ul>
+<li>
+<a href="jquerymobile.com">jQuery Mobile</a> - jQuery Mobile automatically
enhances your layout for mobile optimization. It also handles creating a SPA
for you automatically.</li>
+<li>
+<a class="external" href="http://ionicframework.com/";>ionic</a> - This
powerful UI framework actually has its own CLI to handle project creation. </li>
+<li>
+<a class="external" href="http://goratchet.com/";>Ratchet</a> - Brought to you
by the people who created Bootstrap. </li>
+<li>
+<a class="external" href="http://www.telerik.com/kendo-ui";>Kendo UI</a> - Open
source UI and application framework from Telerik.</li>
+<li><a class="external" href="http://topcoat.io";>Topcoat</a></li>
+<li><a class="external"
href="http://facebook.github.io/react/";>ReactJS</a></li>
+</ul>
+<p>When building your user interface, it is important to think about all
platforms that you are targeting and the differences between the userâs
expectations. For example, an Android application that has an iOS-style UI will
probably not go over well with users. This sometimes is even enforced by the
various application stores. Because of this, it is important that you respect
the conventions of each platform and therefore are familiar with the various
Human Interface Guidelines:
+* <a class="external"
href="https://developer.apple.com/library/ios/documentation/userexperience/conceptual/MobileHIG/index.html";>iOS</a>
+* <a class="external"
href="https://developer.android.com/designWP8";>Android</a>
+* <a class="external"
href="http://dev.windowsphone.com/en-us/design/library";>Windows Phone</a></p>
+
+<h2>
+<a name="User%20Interface_additional_ui_articles_and_resources">Additional UI
Articles and Resources</a>
+</h2>
+
+<p>Although browser engines become more and more standards complaint, we still
live in a prefixed world (-webkit and -ms.) The following article is valuable
when developing UIâs in for cross browser apps: <a class="external"
href="http://blogs.windows.com/windows_phone/b/wpdev/archive/2012/11/15/adapting-your-webkit-optimized-site-for-internet-explorer-10.aspx";>http://blogs.windows.com/windows_phone/b/wpdev/archive/2012/11/15/adapting-your-webkit-optimized-site-for-internet-explorer-10.aspx</a></p>
+
+<h1><a name="Keeping%20Up">Keeping Up</a></h1>
+
+<p>Here are a few ways to keep up to date with Cordova.</p>
+
+<ul>
+<li>Subscribe to the <a class="external"
href="http://cordova.apache.org/#news";>Cordova blog</a>.</li>
+<li>Subscribe to the <a class="external"
href="http://cordova.apache.org/#mailing-list";>developer list</a>. Note - this
is not a support group! Rather this is a place where development of Cordova is
discussed.</li>
+</ul>
+<h1><a name="Getting%20Help">Getting Help</a></h1>
+
+<p>The following links are the best places to get help for Cordova:</p>
+
+<ul>
+<li>StackOverflow: <a class="external"
href="http://stackoverflow.com/questions/tagged/cordova";>http://stackoverflow.com/questions/tagged/cordova</a>
+By using the Cordova tag, you can view and browse all Cordova questions. Note
that StackOverflow automatically converts the "Phonegap" tag to "Cordova", so
this way you will be able to access historical questions as well</li>
+<li>PhoneGap Google Group: <a class="external"
href="https://groups.google.com/forum/#!forum/phonegap";>https://groups.google.com/forum/#!forum/phonegap</a>
+This Google Group was the old support forum for when Cordova was still called
PhoneGap. While there are still a lot of Cordova users that frequent this
group, the Cordova community has expressed an interest in focusing less on this
group and instead using StackOverflow for support</li>
+<li>Meetup: <a class="external"
href="http://phonegap.meetup.com";>http://phonegap.meetup.com</a> -
+Consider finding a local Cordova/PhoneGap meetup group</li>
+</ul>
+</div>
+ </div>
+
+ <!-- Functionality and Syntax Highlighting -->
+ <script type="text/javascript" src="index.js"></script><script
type="text/javascript" src="prettify/prettify.js"></script>
+</body>
+</html>
