Apache Cordova Document;Note=Erxin.txt

Apache Cordova Document;Note=Erxin

# Introduction 
- mobile development framework, allows use standard web technologies 
- architecture 

Web App 
A				   
|html api & cordova api 
V
Html Rendering Engine(WebView) <-cordova native api-> Cordova Plugins 
	A																									   A
	|os apis																							 |
	V																										|
mobile os <-----------------------------------------------------------------------+

- webview, cordova-enbaled webview may provide the application with its entire user interface 
- web app run in webview within naive wrapper. the contain has a config.xml file for specify such as orientation shifts 
- plugins provides an interface for cordova and native components to communicate with each other and bindings to standard device APIs 

there a list of core plugins http://cordova.apache.org/docs/en/latest/guide/support/index.html#core-plugin-apis
cordova CLI 
Embedded WebView 
Plugin Interface 
Accelermeter 
BatteryStatus 
Camera 
Capture 
Compass
Connection 
Contacts
Device 
Events 
File 
File Transfer 
Geolocation 
Globalization 
InAppBrowser 
Media 
Notification 
SplashScreen
StatusBar 
Storage 
Vibration 

search for plugins by plugin search or npm 

check more detail for plugin development guide http://cordova.apache.org/docs/en/latest/guide/hybrid/plugins/index.html

plugin must be explicit added 

- development path 
	+ cross-platform CLI workflow, want run as many os as possible. demo for create your first app http://cordova.apache.org/docs/en/latest/guide/cli/index.html. the CLI is a high-level tool 
	+ platform centered this discussed in Embedded webviews http://cordova.apache.org/docs/en/latest/guide/hybrid/webviews/index.html. this will relies on a set of low level shell scripts 
	
	there is a on direction switch from CLI to platform center. 
	
	
# Create your first Cordova app 
- user cordova command-line 
- installing the cordova CLI 
$ npm install -g cordova 

- create  an app 
$ cordova create hello com.example.hello HelloWorld 

this will create a skeletal web-based application 

- add platforms 
$ cd hello 

add platforms that you wantted 
$ cordova platform add ios --save 
$ cordova platform add android --save 

check current installed platforms 
$ cordova platforms ls 

- install pre-requisites for building. required sdk for each platform, if using browser for development can use browser paltform which does not require any platform sdks 
	+ check satisfay requirements for build 
	$ cordova requirements 
	
- build the app 
	+ start page is 
	www/index.html 
	
	+ any intialization should be specified as part of the deviceready event handler in www/js/index.js 
	+ build all platfroms 
	$ cordova build 
	
	+ build specify platform 
	$ cordova build ios 
	
	+ CLI reference http://cordova.apache.org/docs/en/latest/reference/cordova-cli/index.html#cordova-build-command
- test app 
	+ execute in android emulator 
	$ cordova emulate andriod 
	
	+ execute in the real hardware 
	$ cordova run android 
	
	reference setup android emulator http://cordova.apache.org/docs/en/latest/guide/platforms/android/index.html#setting-up-an-emulator
	
- add plugins
	+ use plugin search page
	http://cordova.apache.org/plugins/
	
	+ use command line to open search page 
	$ cordova plugin search camera 
	
	+ plugins can also be added using a directory or a git repo check the CLR command reference 
	
	+ use plugman to mange plugins, http://cordova.apache.org/docs/en/latest/plugin_ref/plugman.html
	
	+ check current installed plugin, plugin ls or plugin list, or plugin 
	$ cordova plugin ls 
	
- use merges to customize each platform 
	+ modify source files in various www directories within the top-level platforms directory, they're regularly replaced with the top-level www directory cross-platform source 
	
	+ top-level merges directory offers a place to specify asses to deploy on specific platforms, each platform-specific subdirectory within merges 
	
	+ use merges mirrors the directory structure of www source tree, allowing you to override or add files as needed 
	
	+ example 
		* add override.css to www/index.html 
		<link rel="stylesheet" type="text/css" href="css/override.css"/>
		
		* optionally add an empty www/css/override.css file, which will be apply for all non-android builds 
		
		* create a css subdirectory within merges/android, then add a corresponding override.css 
		
		* when rebuild the project the android build will use the customized override.css 
		
- updating cordova and your project 
	+ update cordova utility to latest version 
	$ npm update -g cordova 
	
	+ install specific version 
	$ npm install -g cordova@3.1.0-0.2.0
	
	+ check current installed version 
	$ npm info cordova version 
	
	+ update trageting platform 
	$ cordova platform update android --save 
	
# Platform Support 
- a set of development tools and device APIs 
reference http://cordova.apache.org/docs/en/latest/guide/support/index.html

# Android Platform Guides 
- requirements and support 
	+ latest android package supports up to android API-level 23 
	5.x.x   14-23 
	4.1.x   14-22 
	4.0.x   10-22 
	3.7.x   10-21 
	
	+ a general rule, andriod version become unsupported by cordova as they dip below 5% on google's distribution dashboard 
	
- adding sdk packages 
	+ suggest install the latest version for cordova which supported 
	+ open android sdk manager make sure 
		* android platform sdk 
		* android build tool version 19.1.0 or higher 
		* android support repository (under extras)
		
- setting environment variables 
	+ set JAVA_HOME 
	+ set ANDROID_HOME 
	+ add android sdk tool and platform-tools to path 
	
- OSX and linux 
	+ use a text editor to create or modify the ~/.bash_profile, add line 
	export ANDOID_HOME=/Development/android-sdk/ 
	
	+ update your path, add a line resembling the following(substitue the paths with your local android sdk installation's location)
	export PATH=${PATH}:/Development/android-sdk/platform-tools:/Development/android-sdk/tools 
	
	reload your terminal to see changes by 
	$ source ~/.bash_profile 

- project configuration 
	+ setting up an emulator 
	create a android virtual device (avd). 
	
	after that run cordova cli to check the device 
	$ cordova run --list 
- adding sdk packages 
	+ install the packages for whatever API level (http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)

	+ open android sdk manager 
		* install sdk 
		* install build tools version 19+ 
		* android support reporsitory(under extras)
		
- setting environment variables 
JAVA_HOME to JDK install location 
ANDROID_HOME, to android sdk installation location 
add android sdk tools and platform-tools directories to your PATH 

http://cordova.apache.org/docs/en/latest/guide/platforms/android/index.html

- setting up an emulator 
	+ create an android virtual device(AVD) http://developer.android.com/tools/devices/managing-avds.html
	check current avaliable devices 
	$ cordova run --list 
	
- configuring gradle 
	+ cordova-android@4.0.0 are built using Gradle(http://gradle.org/)
	
	Gradle is a open source polyglot build automation system Automate and integrate your DevOps toolchain with a concise and expressive build programming language 
	
	+ setting gradle properties https://docs.gradle.org/current/userguide/build_environment.html
	cdvBuildMultipleApks, if set multiple APK files are generated supported by library projects(x86, ARM, etc). If not set a single APK will be generated 
	
	cdvVersionCode, override the versionCode set in the AndroidManifest.xml 
	
	cdvReleaseSigningPropertiesFile, path to a .properties file that contains signing information 
	
	cdvDebugSigningPropertiesFile, signing information for debug builds 
	
	cdvMinSdkVersion, overrides the value of minSdkVersion set in AndroidManifest.xml 
	
	cdvBuildToolsVersion, override the android.buildToolVersion value 
	
	cdvCompileSdkVersion, override the automatically detected android.compileSdkVersion 
	
	+ support set properties in one of four ways 
		* environment variables 
		$ export ORG_GRADLE_PROJECT_cdvMinSdkVersion=20 
		$ cordova build android 
		
		* by using the --gradleArg flag in your Cordova build or run commands 
		$ crodova run android -- --gradleArg=-PcdvMinSdkVersion=20 
		
		* by palcing a file called gradle.properties in your android platform folder <project>/platforms/android/gradle.properties
		
		#comments line 
		cdvMinSdkVersion=20 
		
		* by extending build.gradle via a build-extras.gradle file and setting the property like so 
		  // In <your-project>/platforms/android/build-extras.gradle
		  ext.cdvMinSdkVersion = 20

		the files required by the last two options could be copied by before_build hook 
		
- extending build.gradle 
	+ customize build.gradle 
	create a sibling file named build-extras.gradle, it will be included by the main build.gradle when present. it must be placed at   // In <your-project>/platforms/android/ folder 
	
	recommended copy and replaced it with before_build hook (http://cordova.apache.org/docs/en/latest/guide/appdev/hooks/index.html)

		* example 
		// Example build-extras.gradle
		// This file is included at the beginning of `build.gradle`
		ext.cdvDebugSigningPropertiesFile = '../../android-debug-keys.properties'

		// When set, this function allows code to run at the end of `build.gradle`
		ext.postBuildExtras = {
			android.buildTypes.debug.applicationIdSuffix = '.debug'
		}

	+ plugins can also include build-extras.gradle files via 
	<framework src="some.gradle" custom="true" type="gradleReference" />

- setting the version code. change version code for generated apk. set the android-versionCode attribute in the widget element of your application's config.xml file. If the android-versionCode is not set, the version code will be determined using the version attribute

versionCode = MAJOR * 10000 + MINOR * 100 + PATCH

	+ if your application has enabled the cdvBuildMultipleApks. gradle property the version code will also be multiplied by 10. the latest code can be used to indicate the architecture apk 
	
	+ increase the android-versionCode property based on the value in your config.xml file's android-versionCode
	
- signing an App, need follow parameters 
Keystore, --keystore, path to a binary file hold a set of keys 
Keystore Password, --storePassword 
Alias, --alias, the id specifing the private key used for singing 
password, --password, password for the private key 
type of the keystore, --keystoreType, auto-detected based on file etension either pkcs12 or jks 

thexe parameters could be specified by CLI build/run commands 

	+ use -- to indicate these are platform-sepcific arguments 
$ cordova run android --release -- --keystore../my-release-key.keystore --storePassword=password --alias=alias_name --password=password 

- using build.json, using the --buildConfig argument to the same command 
	+ example 
{
	"android": {
		"debug": {
			"keystore": "../android.keystore",
			"storePassword": "android",
			"alias": "mykey1",
			"password" : "password",
			"keystoreType": ""
		},
		"release": {
			"keystore": "../android.keystore",
			"storePassword": "",
			"alias": "mykey2",
			"password" : "password",
			"keystoreType": ""
		}
	}
}

- using gradle, specify signing properties by .properties file and pointing to it with the cdvReleaseSigningPropertiesFile and cdvDebugSigningPropertiesFile Gradle properties
	+ contents 
storeFile=relative/path/to/keystore.p12
storePassword=SECRET1
storeType=pkcs12
keyAlias=DebugSigningKey
keyPassword=SECRET2

	+ reference http://cordova.apache.org/docs/en/latest/guide/platforms/android/index.html#setting-gradle-properties
	
- debugging 
	+ check android sdk developer document for debugging 
	
	+ open a project in android studio. when opening your project in android studio recommended you do not edit your code in the IDE. this will edit the code in the platforms folder(not www) and changes are liable to be overwritten instead, edit the www folder and then run $ cordova build 
	
	+ plugin developer wishing to edit their native code in the IDE should use --link flag when adding their plugin to the project via $ cordova plugin add. the changes will sync between the platforms folder and the plugin's source folder 
	
	+ example open cordova project 
		* launch android studio 
		* select import project(Eclipse ADT, gradle, etc)
		* select the android platform directory in <your-project>/platforms/android
		* for the gradle sync question click Yes 
		* run the application directly in the android studio 
		http://developer.android.com/tools/building/building-studio.html
		http://developer.android.com/tools/studio/index.html
		
- platform centered workflow 
	+ cordova-android includes a number of scripts that allow the platform to be usd without full Cordova cli 
	   
	+ each of the scripts discussed below refer to cordova CLI reference, for example cordova-android/bin/create equivalent to $ cordova create 
	
	+ install plugin with Plugman utility 
		
- upgrating, upgrade from older version android project, reference http://cordova.apache.org/docs/en/latest/guide/platforms/android/upgrade.html

- lifecycle guide 
	+ cordova and android 
	native android apps typically consist of a series of activities. each activity has its own lifecycle 
	
	+ in constrast cordova applications on android are executed in a webview which embedded in a single android activity. the lifecycle of this activity is exposed to your application through document events that are fired. the events are not guaranteed to line up with android's lifecycle. 
	
cordova-event		   android-event 
deviceready				 onCreate() 
pause							onPause() 
resume						 onResume() 

	+ android activity may be removed due to lower memory, so when return back cordova app may lost data so make sure save the user state whenever user leave the application 
	
	+ when can this happen 
	
		* user press home button or switches to another application 
		
		* certain plugins can introduce, such as camera 
		
		* clearer understanding the second case 
		everything goes as planned the workflow will be 
		1. user is interacting with your app, need user take a photo 
		2. camera plugin lauches, cordova app is pushed back 
		3. user take a photo 
		4. camera activity finished, cordova activity is moved to the foreground 
		5. user returned to your application 

		this flow can be disrpted if a device is low on memory 
		1. user interacting with your app, need take a photo 
		2. camera plugin launch, os destroy the cordova activity (pause event is fired)
		3. user take a photo 
		4. camera activity finished, os recreates the cordova activity(deviceready and resume events are fired)
		5. user confused why they are back to login screen
		
		* to overcome this we need subscribing to events and property maintaining state as part of the activity lifecycle 
		
	+ respecting the lifecycle 
	when the cordova plugin destroied from cordova-android 5.1.0 provide a means for getting the native callback when application resume 
	
	resume event's payload will contain any pending plugin results from the plugin request that lauched the external activity made prior to the activity being destroyed. formats 
	{
		action: "resume",
		pendingResult: {
			pluginServiceName: string, //name of the plugin 
			pluginStatus: string, //status of the plugin 
			result: any //whatever the result of the plugin call 
		}
	}
	
	pluginStatus: OK, NoResult, Error other miscellaneous errors "Class not found" "Illegal access" "Instantiation error", "Malformed url", "IO error", "JSON error"
	
	+ example for handling camera resume plugin 
// This state represents the state of our application and will be saved and
// restored by onResume() and onPause()
var appState = {
	takingPicture: true,
	imageUri: ""
};

var APP_STORAGE_KEY = "exampleAppState";

var app = {
	initialize: function() {
		this.bindEvents();
	},
	bindEvents: function() {
		// Here we register our callbacks for the lifecycle events we care about
		document.addEventListener('deviceready', this.onDeviceReady, false);
		document.addEventListener('pause', this.onPause, false);
		document.addEventListener('resume', this.onResume, false);
	},
	onDeviceReady: function() {
		document.getElementById("take-picture-button").addEventListener("click", function() {
			// Because the camera plugin method launches an external Activity,
			// there is a chance that our application will be killed before the
			// success or failure callbacks are called. See onPause() and
			// onResume() where we save and restore our state to handle this case
			appState.takingPicture = true;

			navigator.camera.getPicture(cameraSuccessCallback, cameraFailureCallback,
				{
					sourceType: Camera.PictureSourceType.CAMERA,
					destinationType: Camera.DestinationType.FILE_URI,
					targetWidth: 250,
					targetHeight: 250
				}
			);
		});
	},
	onPause: function() {
		// Here, we check to see if we are in the middle of taking a picture. If
		// so, we want to save our state so that we can properly retrieve the
		// plugin result in onResume(). We also save if we have already fetched
		// an image URI
		if(appState.takingPicture || appState.imageUri) {
			window.localStorage.setItem(APP_STORAGE_KEY, JSON.stringify(appState));
		}
	},
	onResume: function(event) {
		// Here we check for stored state and restore it if necessary. In your
		// application, it's up to you to keep track of where any pending plugin
		// results are coming from (i.e. what part of your code made the call)
		// and what arguments you provided to the plugin if relevant
		var storedState = window.localStorage.getItem(APP_STORAGE_KEY);

		if(storedState) {
			appState = JSON.parse(storedState);
		}

		// Check to see if we need to restore an image we took
		if(!appState.takingPicture && appState.imageUri) {
			document.getElementById("get-picture-result").src = appState.imageUri;
		}
		// Now we can check if there is a plugin result in the event object.
		// This requires cordova-android 5.1.0+
		else if(appState.takingPicture && event.pendingResult) {
			// Figure out whether or not the plugin call was successful and call
			// the relevant callback. For the camera plugin, "OK" means a
			// successful result and all other statuses mean error
			if(event.pendingResult.pluginStatus === "OK") {
				// The camera plugin places the same result in the resume object
				// as it passes to the success callback passed to getPicture(),
				// thus we can pass it to the same callback. Other plugins may
				// return something else. Consult the documentation for
				// whatever plugin you are using to learn how to interpret the
				// result field
				cameraSuccessCallback(event.pendingResult.result);
			} else {
				cameraFailureCallback(event.pendingResult.result);
			}
		}
	}
}

// Here are the callbacks we pass to getPicture()
function cameraSuccessCallback(imageUri) {
	appState.takingPicture = false;
	appState.imageUri = imageUri;
	document.getElementById("get-picture-result").src = imageUri;
}

function cameraFailureCallback(error) {
	appState.takingPicture = false;
	console.log(error);
}

app.initialize();

//corresponding html 
<!DOCTYPE html>

<html>
	<head>
		<meta http-equiv="Content-Security-Policy" content="default-src 'self' data: gap: https://ssl.gstatic.com 'unsafe-eval'; style-src 'self' 'unsafe-inline'; media-src *">
		<meta name="format-detection" content="telephone=no">
		<meta name="msapplication-tap-highlight" content="no">
		<meta name="viewport" content="user-scalable=no, initial-scale=1, maximum-scale=1, minimum-scale=1, width=device-width">
		<link rel="stylesheet" type="text/css" href="css/index.css">
		<title>Cordova Android Lifecycle Example</title>
	</head>
	<body>
		<div class="app">
			<div>
				<img id="get-picture-result" />
			</div>
			<Button id="take-picture-button">Take Picture</button>
		</div>
		<script type="text/javascript" src="cordova.js"></script>
		<script type="text/javascript" src="js/index.js"></script>
	</body>
</html>

	+ android provides a developer setting for testing activity destruction on low memory. Enable "Don't keep activities" setting in the develop options 
	
# Blackberry 10 
# iOS 
# OS X 
# Ubuntu 
# Windows 
# WP8 

# Manage versions and platforms 
- support save and restore platforms and plugins. save store information in config.xml. restore step happens automatically when a cordova prepare is issued 

this make a large team development easier 

- platform versioning 
$ cordova platform add <platform[@<version>] | directory | git_url> --save

	+ this command add content to cofig.xml 
<?xml version='1.0' encoding='utf-8'?>
	...
	<engine name="android" spec="~4.0.0" />
	...
</xml>

- mass saving platforms on an exiting project 
$ cordova platform save

- updating/removing platforms 
$ cordova platform update <platform[@<version>] | directory | git_url> --save
$ cordova platform remove <platform> --save

- restoring platforms. by command $ cordova prepare. if you add a platform without specifying a version then it will taken from the config.xml if found 

- plugin versioning 
$ cordova plugin add <plugin[@<version>] | directory | git_url> --save

- save all plugin information 
$ cordova plugin save

- remove plugin information 
$ cordova plugin update <plugin[@<version>] | directory | git_url> --save
$ cordova plugin remove <plugin> --save

- restoring rule is same as platform, config.xml is used first 

# Customize Icons 
- SplashScreen plugin document for how to configuration an app's icon for various platforms 
http://cordova.apache.org/docs/en/latest/reference/cordova-plugin-splashscreen/

- configuring icons in the CLI 
	+ define app icons via <icon> element in config.xml. if not the cordova icon is used 
	<icon src="res/ios/icon.png" platform="ios" width="57" height="57" density="mdpi" target="filename and all its MRT companions"/>

	src, is required other properties are all optional 
	density, is for andoird 
	target is for windows
	
	+ define a pixel-perfect icons set to fit different screen resolutions 
 <platform name="android">
		<!--
			ldpi	: 36x36 px
			mdpi	: 48x48 px
			hdpi	: 72x72 px
			xhdpi   : 96x96 px
			xxhdpi  : 144x144 px
			xxxhdpi : 192x192 px
		-->
		<icon src="res/android/ldpi.png" density="ldpi" />
		<icon src="res/android/mdpi.png" density="mdpi" />
		<icon src="res/android/hdpi.png" density="hdpi" />
		<icon src="res/android/xhdpi.png" density="xhdpi" />
		<icon src="res/android/xxhdpi.png" density="xxhdpi" />
		<icon src="res/android/xxxhdpi.png" density="xxxhdpi" />
	</platform>
	
- ios 
	<platform name="ios">
		<!-- iOS 8.0+ -->
		<!-- iPhone 6 Plus  -->
		<icon src="res/ios/icon-60@3x.png" width="180" height="180" />
		<!-- iOS 7.0+ -->
		<!-- iPhone / iPod Touch  -->
		<icon src="res/ios/icon-60.png" width="60" height="60" />
		<icon src="res/ios/icon-60@2x.png" width="120" height="120" />
		<!-- iPad -->
		<icon src="res/ios/icon-76.png" width="76" height="76" />
		<icon src="res/ios/icon-76@2x.png" width="152" height="152" />
		<!-- iOS 6.1 -->
		<!-- Spotlight Icon -->
		<icon src="res/ios/icon-40.png" width="40" height="40" />
		<icon src="res/ios/icon-40@2x.png" width="80" height="80" />
		<!-- iPhone / iPod Touch -->
		<icon src="res/ios/icon.png" width="57" height="57" />
		<icon src="res/ios/icon@2x.png" width="114" height="114" />
		<!-- iPad -->
		<icon src="res/ios/icon-72.png" width="72" height="72" />
		<icon src="res/ios/icon-72@2x.png" width="144" height="144" />
		<!-- iPhone Spotlight and Settings Icon -->
		<icon src="res/ios/icon-small.png" width="29" height="29" />
		<icon src="res/ios/icon-small@2x.png" width="58" height="58" />
		<!-- iPad Spotlight and Settings Icon -->
		<icon src="res/ios/icon-50.png" width="50" height="50" />
		<icon src="res/ios/icon-50@2x.png" width="100" height="100" />
	</platform>

- windows recommend approach is used target attribute 
	<platform name="windows">
		<icon src="res/windows/storelogo.png" target="StoreLogo" />
		<icon src="res/windows/smalllogo.png" target="Square30x30Logo" />
		<icon src="res/Windows/Square44x44Logo.png" target="Square44x44Logo" />
		<icon src="res/Windows/Square70x70Logo.png" target="Square70x70Logo" />
		<icon src="res/Windows/Square71x71Logo.png" target="Square71x71Logo" />
		<icon src="res/Windows/Square150x150Logo.png" target="Square150x150Logo" />
		<icon src="res/Windows/Square310x310Logo.png" target="Square310x310Logo" />
		<icon src="res/Windows/Wide310x150Logo.png" target="Wide310x150Logo" />
	</platform>
	
- windows phone 8 
 <platform name="wp8">
		<icon src="res/wp/ApplicationIcon.png" width="99" height="99" />
		<!-- tile image -->
		<icon src="res/wp/Background.png" width="159" height="159" />
	</platform>
	
# Storage 
- html5 approach 
- localStorage
window.localStorage
- websql 
android 
blackBerry 10 
iOS 
- indexedDB
android 
blackBerry 10 
windows limitation 
	+ not avaliable in web workers 
	+ not support array keys 
	+ doesn't support object lookup via compound index 
android 4.4+ 

- plugin based options 
	+ FileSystem api in chrome. File plugin provides an extensive implementation and support in all platforms 
	
	+ Sqlite plugin 

cordova-sqlite-storage - core version that relies on native SQLite implementation. As such, it is only available for iOS and Android platforms.
cordova-sqlite-ext - extended version with additional features including support for Windows and REGEXP support on Android and iOS.
cordova-sqlite-evfree - similar to cordova-sqlite-ext but with improved memory handling. Available under GPL v3 or commercial license.

# Manage Privacy 
- privacy guide 
	+ privacy policy 
	make your privacy policy available for users to review prior to download 
	
	+ collection of sensitive information, such as geolocation, contacts/phonebook, microphone/camera, stored pictures/videos 
	
	+ avoiding user surprise 
	
	+ thrid party data collection or sharing should be inform 
	
	+ collection limitation and security 
	
# Manage security 
- whitelist 
	+ read the whitelist guide http://cordova.apache.org/docs/en/latest/guide/appdev/whitelist/index.html
	
	+ domain whitelist doesn't work on android API 10- and wp8 for iframes and xmlhttprequest 
	
	+ use inAppBrowser plugin or other third-party plugins 
	
- iframes and the callback id mechanism 
	+ content is served in an iframe from a whitelisted domain, taht domain will have access to the natie cordova bridge. this means that if your whitelist third-party advertising network these ads possible be a malicious ad will be able to break out the iframe
	
	+ there are thrid party plugins to support advertising network. this statement is not ture for iOS, which intercept everyting including iframe connections 
	
- certificate pinning 
	+ cordova doesnot support true certificate pinning. the main barrier is a lack of native APIs in android for intercepting SSL connection to perform the check of the server's certificate 
	
	+ there are ways to approximate certificate pinning sch as checking server's public key(fingerprint) while your app starts or other various times. 
	
	+ there are also plugins that do true certificate pinning for some platforms 
	
- self signed certificates for your server is not recommend. it should be signed by a well-known CA. 
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.

When running Cordova on Android, using android:debuggable="true" in the application manifest will permit SSL errors such as certificate chain validation errors on self-signed certs.

- general tips 
	+ do not user android Gingerbread, it is API 10 
	+ use inAppBrowser for outside links	
	+ validate all user input 
	+ do not cache sensitive data 
	+ don't use eval() unless you know what you're doing 
	+ do not assume that your source code is secure 
- reference 
https://www.owasp.org/index.php/HTML5_Security_Cheat_Sheet
https://github.com/phonegap/phonegap/wiki/Platform-Security
http://www.cis.syr.edu/~wedu/Research/paper/webview_acsac2011.pdf

# Whitelist Guide 
- cordova provide a policy to configure which external sites may be accessed 
- android 4.0+ should use cordova-plugin-whitelist plugin 
- add <access> element within the app's config.xml file 
	+ access to google.com, support wildcard match, origin="*" means all 
<access origin="http://google.com" />
- cordova-iso version 4.0+ does not require the cordova-plugin-whitelist to be installed 
 <allow-intent> and <allow-navigation>
- windows phone whitelist are found in the config.xml file 

# Create plugins 
- plugin comprise as a single javascript interface along with corresponding native code libraries for each supported platform 

- building a plugin 
	+ using CLI's plugin add command to add a plugin to a project. add from git repo 
	$ cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-device.git

	+ plugin repo must feature a top-level plugin.xml manifest file 

//example 
<?xml version="1.0" encoding="UTF-8"?>
<plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"
		id="cordova-plugin-device" version="0.2.3">
	<name>Device</name>
	<description>Cordova Device Plugin</description>
	<license>Apache 2.0</license>
	<keywords>cordova,device</keywords>
	<js-module src="www/device.js" name="device">
		<clobbers target="device" />
	</js-module>
	<platform name="ios">
		<config-file target="config.xml" parent="/*">
			<feature name="Device">
				<param name="ios-package" value="CDVDevice"/>
			</feature>
		</config-file>
		<header-file src="src/ios/CDVDevice.h" />
		<source-file src="src/ios/CDVDevice.m" />
	</platform>
</plugin>

reference http://cordova.apache.org/docs/en/latest/plugin_ref/spec.html

- validating a plugin using plugman utility 
$ npm insall -g plugman 
	+ need a valid app source directory 
	
	+ example avlid iOS dependencies load properly 
	$ plugman install --platform ios --project /path/to/my/project/www --plugin /path/to/my/plugin
	
	+ plugman reference, http://cordova.apache.org/docs/en/latest/plugin_ref/plugman.html
	
- the javascript interface 
	+ structure your plugin's javascript, you need to call cordova.exec to communicate with the native platform using following syntax 
	
cordova.exec(function(winParam) {},
					   function(error) {},
					   "service",
					   "action",
					   ["firstArgument", "secondArgument", 42, false]);

function(winParam), a success callback function, assuming your exec call complete successfully 
"service", the service name to call on the native side, corresponds to a native class 
"action", action name on the native side 
"[]", arrary of arguments 

- sameple javascript
window.echo = function(str, callback) {
	cordova.exec(callback, function(err) {
		callback('Nothing to echo.');
	}, "Echo", "echo", [str]);
};

//use the plugin 
window.echo("echome", function(echoValue) {
	alert(echoValue == "echome"); // should alert true.
});

- native interface should be implement separately for each platform 
	+ android 
	+ iOS 
	+ blackBerry
	+ window phone 8 
	+ window 
	
- publishing plugins publish your plugin to any npmjs-based registry recommand use https://www.npmjs.com/ then other developer could use your plugin automatically by plugman or Cordova CLI 
	+ isntall plugman 
	$ npm install -g plugman 
	
	+ create package.json 
	$ plugman createpackagejson path-to-your-plugin 
	
	+ publish 
	$ npm add user # that is if you dont have an account yet 
	$ npm publish path-to-your-plugin
	
	reference publish a npm package https://docs.npmjs.com/getting-started/publishing-npm-packages
	
- integrating with plugin search 
	+ add ecosystem:cordova keyword to package.json to surface your plugin in Cordova Plugin Search 
	
	+ indicate support for a particular platform add a keword with <paltformName> as **cordova-<platformName>** to the list of keywords in pacakge.json 
	
	//example for a plugin that support android, ios and windows 
	"keywords": [
		"ecosystem:cordova",
		"cordova-android",
		"cordova-ios",
		"cordova-windows"
	]
	
	for a detail example check the https://github.com/apache/cordova-plugin-device/blob/master/package.json
	
- specifying cordova dependencies 
cordova 6.1.0 added support for specifying the related dependencies of a plugin as part of pacakge.json. get more detail from plugin.xml(http://cordova.apache.org/docs/en/latest/plugin_ref/spec.html#engines-and-engine)
	
	+ specify cordova-related dependencies to package.json 
engines: {
	cordovaDependencies: {
		PLUGIN_VERSION: {
			DEPENDENCY: SEMVER_RANGE,
			DEPENDENCY: SEMVER_RANGE,
			...
		},
		...
	}
}

PLUGIN_VERSION, specify a version of your plugin, it should adhere the syntax for a single version as defined by npm's semver pakcage or an upper bound https://www.npmjs.com/package/semver

DEPENDENCY may be one of the following 
	+ the cordova CLI "cordova" 
	+ a cordova platform (e.g "cordova-android", "cordova-ios", "cordova-windows", etc )
	+ andother cordova plugin (e.g "cordova-plugin-camera", etc )
	
SEMVER_RANGE, should adhere to the synatx for a range as define in nmp's semver https://www.npmjs.com/package/semver

cordovaDependencies may list any number of PLUGIN_VERSION requirements and any number of DEPENDENCY. version of your plugin that do not have their dependencies listed will be assumed to have the same dependency information as the highest PLUGIN_VERSION listed below them 
engines: {
	cordovaDependencies: {
		"1.0.0": { "cordova-android": "<3.0.0"},
		"2.1.0": { "cordova-android": ">4.0.0"}
	}
}
below 1.0.0 is assumed have no dependencies, version between v1.0.0 and 2.1.0 are same. 

- upper bounds,  a single versio a PLUGIN_VERSION in cordovaDependencies may also specify an upper bound to amend entries for older release of your plugin 

engines: {
	cordovaDependencies: {
		"0.0.1":  { "cordova-ios": ">1.0.0" },
		"<1.0.0": { "cordova-ios": "<2.0.0" },
		"<2.0.0": { "cordova-ios": "<5.0.0" }
	}
}
PLUGIN_VERSION allowed single versions or uppper bounds, no other semver ranges are supported 

the rule will be combined to   "cordova-ios >1.0.0 AND cordova-ios <2.0.0 AND cordova-ios <5.0.0"


# Develop plugin for Android 
- android plugins are based on cordova-android, which is built from an android webview with a native bridge. the native portion of an android plugin consists of at least one java class that extend the CordovaPlugin class and overrides one of its execute methods 
	+ example project 
	https://github.com/apache/cordova-android/blob/master/framework/src/org/apache/cordova/CordovaPlugin.java
- plugin class mapping 
	+ plugin's javascript interface uses the cordova.exec method as follows 
	exec(<successFunction>, <failFunction>, <service>, <actions>, [<args>]);
	
	this marshals a request from the webview to the android native side 
	
	whether you distribute a plugin as java file or as a jar file of its own, the plugin must be specified in your cordova-android application's res/xml/config.xml 
	
	use plugin.xml file to inject this feature 
	<feature name="<service_name>">
		<param name="android-package" value="<full_name_including_namespace>"/>
	</feature>
	the service name matchs the one used in the JavaScript exec call. the value is the java class's full qulified namespace identifier 
	
- plugin initialization and lifetime 
	+ one instance of a plugin object is created for the life of each webview. plugins are not instantiated until they referenced by a call from javascript unless <param> with a onlaod name attribute is set to "true"

	<feature name="Echo">
		<param name="android-package" value="<full_name_including_namespace>" />
		<param name="onload" value="true" />
	</feature>

	+ plugins should use the initialize method for their start-up logic 
@Override
public void initialize(CordovaInterface cordova, CordovaWebView webView) {
	super.initialize(cordova, webView);
	// your init code here
}

	+ plugins have access to android lifecycle events 
	
- writing an android java plugin 
	+ a javascript call fires off a plugin request to the native side. and the corresponding java plugin is mapped properly in the config.xml file 

	+ the execute method of plugin class look like this 
@Override
	public boolean execute(String action, JSONArray args, CallbackContext callbackContext) throws JSONException {
		if ("beep".equals(action)) {
			this.beep(args.getLong(0));
			callbackContext.success();
			return true;
		}
		return false;  // Returning false results in a "MethodNotFound" error.
	}

- threading, plugin's javascript does not run in the main thread of webview. instead it runs on the webcore thread 

	+ to interactive with UI thread, you should use the activity's runOnUiThread 
	@Override
	public boolean execute(String action, JSONArray args, final CallbackContext callbackContext) throws JSONException {
		if ("beep".equals(action)) {
			final long duration = args.getLong(0);
			cordova.getActivity().runOnUiThread(new Runnable() {
				public void run() {
					...
					callbackContext.success(); // Thread-safe.
				}
			});
			return true;
		}
		return false;
	}

	+ if you do not need to run on the UI thread, but do not wish to block the webcore thread either, you should execute your code using the cordova ExecutorService obtained with cordova.getThreadPool()
	
	@Override
	public boolean execute(String action, JSONArray args, final CallbackContext callbackContext) throws JSONException {
		if ("beep".equals(action)) {
			final long duration = args.getLong(0);
			cordova.getThreadPool().execute(new Runnable() {
				public void run() {
					...
					callbackContext.success(); // Thread-safe.
				}
			});
			return true;
		}
		return false;
	}
	
- adding dependency libraries, they must be listed in the plugin.xml in one of two ways 
	+ use <framework/> tag. specify the libraries in the manner allows them to be resolved via gradle's dependency management logic 
	
	+ use <lib-file/> tag to specify the location of a jar file. this should only be used if you are sure that no other plugin will be depending on the library you are referencing(if the library is specific to your plugin). other wise the user may encounter native build error if other plugins also reference the same library 
	
- echo android plugin example, to match the javascript interface's each feature use plugin.xml to inject a feature to the local platform's config.xml file 

<platform name="android">
	<config-file target="config.xml" parent="/*">
		<feature name="Echo">
			<param name="android-package" value="org.apache.cordova.plugin.Echo"/>
		</feature>
	</config-file>

	<source-file src="src/android/Echo.java" target-dir="src/org/apache/cordova/plugin" />
</platform>

	+ add following code to the src/android/Echo.java file 
package org.apache.cordova.plugin;

import org.apache.cordova.CordovaPlugin;
import org.apache.cordova.CallbackContext;

import org.json.JSONArray;
import org.json.JSONException;
import org.json.JSONObject;

/**
* This class echoes a string called from JavaScript.
*/
public class Echo extends CordovaPlugin {

@Override
public boolean execute(String action, JSONArray args, CallbackContext callbackContext) throws JSONException {
	if (action.equals("echo")) {
		String message = args.getString(0);
		this.echo(message, callbackContext);
		return true;
	}
	return false;
}

private void echo(String message, CallbackContext callbackContext) {
	if (message != null && message.length() > 0) {
		callbackContext.success(message);
	} else {
		callbackContext.error("Expected one non-empty string argument.");
	}
}
}

- android integration 
	+ android features an intent system that allows processes to communicate with each other. plugins ahve access to a cordovaInterface object 
	http://developer.android.com/reference/android/content/Intent.html
	
	The activity is the context. cordovaInterface allows plugins to start an activity for a result and set the callback plugin for when the intent returns to the application. 
	http://developer.android.com/reference/android/content/Context.html
	
- android permissions, handled at install-time. this can be accomplished using config.xml to inject these permissions 

<config-file target="AndroidManifest.xml" parent="/*">
	<uses-permission android:name="android.permission.READ_CONTACTS"/>
</config-file>

- runtime permissions(cordova-android 5.0.0+)
	+ android 6.0 marshamallow introduce a new permission model, where the user can turn on and off permission as necessary 
	http://developer.android.com/guide/topics/security/permissions.html#perm-groups
	
	as far as a plugin is concerned the permission can be requested by calling the permission method 
	cordova.requestPermission(CordovaPlugin plugin, int requestCode, String permission);

	to cut down verbosity we could use a local static variable 
	public static final String READ = Manifest.permission.READ_CONTACTS;

	standard practice to define 
	public static final int SEARCH_REQ_CODE = 0;

	+ in exec method, check the permission by 
	if(cordova.hasPermission(READ))
	{
		search(executeArgs);
	}
	else
	{
		getReadPermission(SEARCH_REQ_CODE);
	}

protected void getReadPermission(int requestCode)
{
	cordova.requestPermission(this, requestCode, READ);
}

	after the user response for the pop up request permission we need handle the result by 
public void onRequestPermissionResult(int requestCode, String[] permissions,
										 int[] grantResults) throws JSONException
{
	for(int r:grantResults)
	{
		if(r == PackageManager.PERMISSION_DENIED)
		{
			this.callbackContext.sendPluginResult(new PluginResult(PluginResult.Status.ERROR, PERMISSION_DENIED_ERROR));
			return;
		}
	}
	switch(requestCode)
	{
		case SEARCH_REQ_CODE:
			search(executeArgs);
			break;
		case SAVE_REQ_CODE:
			save(executeArgs);
			break;
		case REMOVE_REQ_CODE:
			remove(executeArgs);
			break;
	}
}

	+ it is also possible to request permission for an entire group 
String [] permissions = { Manifest.permission.ACCESS_COARSE_LOCATION, Manifest.permission.ACCESS_FINE_LOCATION };

cordova.requestPermissions(this, 0, permissions);

- debugging android plugins 
	+ can be done with eclipse or android studio. android studio is recommended 
	+ cordova-android is currently used as a library project 
	
- launching other activities 
	+ if the plugin launches a activity which push cordova activity into background, android may destroy activity in the background if low on memory. your plugin's callback to the cordova activity will fail .	
	when cordova activity brought back to foreground a new plugin instance will be created. there are two ways to handle in your plugin 

/**
 * Called when the Activity is being destroyed (e.g. if a plugin calls out to an
 * external Activity and the OS kills the CordovaActivity in the background).
 * The plugin should save its state in this method only if it is awaiting the
 * result of an external Activity and needs to preserve some information so as
 * to handle that result; onRestoreStateForActivityResult() will only be called
 * if the plugin is the recipient of an Activity result
 *
 * @return  Bundle containing the state of the plugin or null if state does not
 *		  need to be saved
 */
public Bundle onSaveInstanceState() {}

/**
 * Called when a plugin is the recipient of an Activity result after the
 * CordovaActivity has been destroyed. The Bundle will be the same as the one
 * the plugin returned in onSaveInstanceState()
 *
 * @param state			 Bundle containing the state of the plugin
 * @param callbackContext   Replacement Context to return the plugin result to
 */
public void onRestoreStateForActivityResult(Bundle state, CallbackContext callbackContext) {}

- this is important to note that the above methods should only be used if your plugin launches an activity for a result and should only restore the state necessary to handle that activity result 

the state of the plugin will not be restored except in the case where an activity result is obtained that your plugin requested using CordovaInterface's startActivityForResult() method and the cordova activity was destroyed by the OS while in the background 

as part of onRestoreStateForActivityResult() your plugin will be passed a replacement CallbackContext. The callback is not the same one that was destroyed with the activity. this replacement callbackContext will return the result as part the resume event 
{
	action: "resume",
	pendingResult: {
		pluginServiceName: string, //will mathc the name element of your plugin.xml 
		pluginStatus: string,
		result: any
	}
}

	+ events sequence 
	cordova app call your plugin 
	your plugin launch an activity(such as camera) for result 
	android os destroys cordova-activity and yoru plugin onSaveInstanceState() is called 
	user interacts wth your activity and the activity finished 
	cordova activity is recreated and the activity result is received onRestoreStateForActivityResult() is called 
	onActivityResult() is called and your plugin passes a result to the new CallbackContext
	the resume event is fired and received by the cordova application 
	
# Develop plugins for Blackberry10 
# Develop plugins for iOS 
# Develop plugins for Window
- implement a plugin for window store and window 8.1 phone and desktop, and universal windows platform(window 10 +) 
...

# Develop plugins for WP8 

# Advanced Topics 
## Embedding WebViews 
### Android webview 
- create your own webview components that maek full use of Cordova APIs 
- the deploy a webview you need to be familiar with each native programming environment 
	+ android webviews 
	+ iOS webViews 
	+ window phone 8.0 webviews 
- starting with cordova 1.9 the android platform relies on a cordovaWebView component compoents 
	+ download latest cordova 
	+ natvigate to android package's /framework run ant jar which create cordova .jar file. formed as /framework/cordova-x.x.x.jar 
	
	+ copy the .jar file into the android project's /libs directory 
	+ add the following to the application's /res/xml/main.xml file, with the layout_height, layout_width and id modified to suit the application 
	
	<org.apache.cordova.CordovaWebView android:id="@+id/tutorialView" android:layout_width="match_parent"	android:layout_height="match_parent" />
	
- modify the activity so that it implements the cordovaInterface. it should implement the included methods. copy them from /framework/src/org/apache/cordova/CordovaActivity.java, or implmenet them on your own	
public class CordovaViewTestActivity extends Activity implements CordovaInterface {
	CordovaWebView cwv;
	/* Called when the activity is first created. */
	@Override
	public void onCreate(Bundle savedInstanceState) {
		super.onCreate(savedInstanceState);
		setContentView(R.layout.main);
		cwv = (CordovaWebView) findViewById(R.id.tutorialView);
		Config.init(this);
		cwv.loadUrl(Config.getStartUrl());
	}
	
	+ if the application needs to use camera, implment 
@Override
public void setActivityResultCallback(CordovaPlugin plugin) {
	this.activityResultCallback = plugin;
}
/**
 * Launch an activity for which you would like a result when it finished. When this activity exits,
 * your onActivityResult() method is called.
 *
 * @param command		   The command object
 * @param intent			The intent to start
 * @param requestCode	   The request code that is passed to callback to identify the activity
 */
public void startActivityForResult(CordovaPlugin command, Intent intent, int requestCode) {
	this.activityResultCallback = command;
	this.activityResultKeepRunning = this.keepRunning;

	// If multitasking turned on, then disable it for activities that return results
	if (command != null) {
		this.keepRunning = false;
	}

	// Start activity
	super.startActivityForResult(intent, requestCode);
}

@Override
/**
 * Called when an activity you launched exits, giving you the requestCode you started it with,
 * the resultCode it returned, and any additional data from it.
 *
 * @param requestCode	   The request code originally supplied to startActivityForResult(),
 *						  allowing you to identify who this result came from.
 * @param resultCode		The integer result code returned by the child activity through its setResult().
 * @param data			  An Intent, which can return result data to the caller (various data can be attached to Intent "extras").
 */
protected void onActivityResult(int requestCode, int resultCode, Intent intent) {
	super.onActivityResult(requestCode, resultCode, intent);
	CordovaPlugin callback = this.activityResultCallback;
	if (callback != null) {
		callback.onActivityResult(requestCode, resultCode, intent);
	}
}

	+ remember to add the thread pool, otherwise plugins have no threads on which to run 
@override 
public ExecutrService getThreadPool(){
	return threadPool;
}

- copy the application's HTML and JavaScript files to the android project's /assets/www directory 
- copy the config.xml file from /framework/res/xml to project's /res/xml directory 

### iOS webview 
### window phone webview 
	
## Next Steps 
- contribute to cordova project 
http://cordova.apache.org/contribute/

- best practices cordova app development 
	+ SPA is your friends 
	your app should adop the SPA(single page application) design 
	
	a cordova application must wait for the deviceready event, if you don't use SPA the other page have to wait for the event again 
	
	+ SPA libraries 
	angularJs, http://angularjs.org/
	emberJs, http://emberjs.com/
	backbone, http://backbonejs.org/
	kendo UI, http://www.telerik.com/kendo-ui
	monaca, http://monaca.mobi/en/
	reactJS, http://facebook.github.io/react/
	sencha touch, http://www.sencha.com/products/touch/
	jquery mobile, http://jquerymobile.com/
	...
	
- performance considerations, consider following issues to improve 
	+ click versus touch, most mistake can make is click events, most device impose a 300ms dely on them in order to distinguish between a touch and a touch "hold" event. Using touchstart or touchend, will result in a dramatic improvement 
	
	check events avaliable in different platforms from http://caniuse.com/#search=touch
	
	use library like HandJS and Fastclick to deal with this which platform not support touch
	
	+ css transition versus DOM manipulation, use hardware accelerated css transitions will be dramatically bettern than using javascript to create animations 
	
	+ networks suck, additional performance articles 
	http://coenraets.org/blog/2013/10/top-10-performance-techniques-for-phonegap-and-hybrid-apps-slides-available/
	https://channel9.msdn.com/Events/Build/2013/4-313
	http://sintaxi.com/you-half-assed-it
	
- recognize and handle offline status, 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. 

http://www.telerik.com/blogs/is-this-thing-on-%28part-1%29
- handling upgrades 
	+ upgrading cordova projects 
	$ cordova platform update platform-name iso, android, etc 
	
	+ plugin upgrades 
	$ cordova plugin rm plugin-name 
	$ cordova plugin add plugin-name 
	
- test cordova apps, any web friendly unit testing solution will do 
	+ testing on a simulator vs on a real device 
	simulators, on real device may realtive to lower memor 
	+ emulators, may fail display 
	
- debugging 
	+ ios, xcode 
	+ safari remote debugging with web inspector 
	http://moduscreate.com/enable-remote-web-inspector-in-ios-6/
	https://developer.apple.com/library/safari/documentation/AppleApplications/Conceptual/Safari_Developer_Guide/Introduction/Introduction.html
	
	+ chrome remote debugging 
	https://developers.google.com/chrome/mobile/docs/debugging
	https://github.com/google/ios-webkit-debug-proxy/
	
- ripple, is a desktop based emulator for cordova projects. it fakes the camera API by letting you select a picture from your hardrive 
http://ripple.incubator.apache.org/

- weinre, creates a local server that can host a remote debug client for your cordova applications 
http://people.apache.org/%7Epmuellr/weinre/docs/latest/

- other options 
http://developer.telerik.com/featured/a-concise-guide-to-remote-debugging-on-ios-android-and-windows-phone/

- user interface 
jquery mobile, http://jquerymobile.com/
ionic, http://ionicframework.com/

- special consideration 
	+ platform quirks
	+ loading remote content, invoking cordova javascript functions from a remotely-loaded html page is an unsupported configuration 
	
	+ display remote content should use plugin InAppBrowser
	
- keeping up
	+ subscribe to cordova blog 
	 subscribe to developer list 
	 
- getting help 
	+ stackoverflow, http://stackoverflow.com/questions/tagged/cordova
	+ phonegap, https://groups.google.com/forum/#!forum/phonegap
	+ meetup, http://phonegap.meetup.com/

	
# Reference 
## Config.xml , http://cordova.apache.org/docs/en/latest/config_ref/index.html
- config.xml is a global configuration file for cordova. it is based on the Packaged Web Apps(Widget) https://www.w3.org/TR/widgets/

when using cli to build a project, this file are copied into various platforms/ subdirectories
app/platforms/ios/AppName/config.xml 
app/platforms/blackberry10/www/config.xml 
...

- widget, root element of config.xml 
id, string 
version, string, 
android-versionCode, string 
ios-CFBundleVersion, string 
...

- example 
<!-- Android -->
<widget id="io.cordova.hellocordova" version="0.0.1" android-versionCode="0.1.3" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0">
</widget>

- name, app's formal name 
<widget ...>
   <name>HelloCordova</name>
</widget>

- description 
- author
- content 
- access, external domains allowed to communicate with 
- allow-navigation, which url webview itself can be navigated to 
<!-- Allow links to example.com -->
<allow-navigation href="http://example.com/*" />

- allow-intent the app is allowed to ask the system to open 
- engine, what platform to restore during a prepare 
- plugin, This element is automatically added to a project's config.xml when a plugin is added using the --save flag
<plugin name="cordova-plugin-device" spec="^1.1.0" 

- variable 
- preference, set various options as pairs of name/value attributes
AllowInlineMediaPlayback, boolean 
...

<preference name="DisallowOverscroll" value="true"/>

- feature, use the cli to build applications, use the plugin command to enable device apis 
- platform, when using cli to build application, it is used to specific perferences platform 
<platform name="android">
   <preference name="Fullscreen" value="true" />
</platform>

- hook, represents your custom script which will be called by cordova when certain action occurs
- sample config.xml 
<?xml version='1.0' encoding='utf-8'?>
<widget id="io.cordova.hellocordova" version="0.0.1" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0">
  <name>HelloCordova</name>
  <description>
	  A sample Apache Cordova application that responds to the deviceready event.
  </description>
  <author email="dev@cordova.apache.org" href="http://cordova.io">
	  Apache Cordova Team
  </author>
  <content src="index.html" />
  <plugin name="cordova-plugin-whitelist" spec="1" />
  <access origin="*" />
  <allow-intent href="http://*/*" />
  <allow-intent href="https://*/*" />
  <allow-intent href="tel:*" />
  <allow-intent href="sms:*" />
  <allow-intent href="mailto:*" />
  <allow-intent href="geo:*" />
  <platform name="android">
	  <allow-intent href="market:*" />
  </platform>
  <platform name="ios">
	  <allow-intent href="itms:*" />
	  <allow-intent href="itms-apps:*" />
  </platform>
</widget>


## Events 
- there are various event provided by cordova to be used by the application, application could add listeners for these events 

	+ html 
<!DOCTYPE html>
<html>
	<head>
	<title>Device Ready Example</title>

	<script type="text/javascript" charset="utf-8" src="cordova.js"></script>
	<script type="text/javascript" charset="utf-8" src="example.js"></script>
	</head>
	<body onload="onLoad()">
	</body>
</html>

	+ js file 
// example.js file
// Wait for device API libraries to load
//
function onLoad() {
	document.addEventListener("deviceready", onDeviceReady, false);
}

// device APIs are available
//
function onDeviceReady() {
	document.addEventListener("pause", onPause, false);
	document.addEventListener("resume", onResume, false);
	document.addEventListener("menubutton", onMenuKeyDown, false);
	// Add similar listeners for other events
}

function onPause() {
	// Handle the pause event
}

function onResume() {
	// Handle the resume event
}

function onMenuKeyDown() {
	// Handle the menubutton event
}

// Add similar event handlers for other events

- application should use document.addEventListener to attach an event 

- the events cordova supported platforms, http://cordova.apache.org/docs/en/latest/cordova/events/events.html

event				   android		 blackberry10		ios		 window phone 8	  windows 
deviceready		y					y							 y			 y							   y 
pause				   y					y							 y			 y							   y 
resume				y					y							 y			 y							   y	
backbutton		 y					y							 n			 n							   n 
menubutton	   y					y							 n			 n							   n 
searchbutton	  y					n							n			   n							   n 
startcallbutton   n					y							n			   n							   n 
endcallbutton	n					y							 n			   n							   n 
volumendownbutton y		 y							   n			   n							   n 
volumeupbutton  y				   y						   n			   n							   n							   

- example 
document.addEventListener("deviceready", onDeviceReady, false);

function onDeviceReady() {
	// Now safe to use device APIs
}


## CLI Reference 
- syntax 
$ cordova <command> [options] -- [platformOpts]

- global command list, commands are available at all times 
command	   description 
create			  create a project 
help				get help for a command 
telemetry	   turn telemetry collection on or off 

- project command list 
command	 description 
info 
requirements 
platform 
plugin 
prepare,		copy files to platforms for building 
compile		 build platform 
clean   
run 
serve			 run project with a local webserver 

- command options, apply to all cordova cli commands 
option		  description 
|-d or verbose	pipe out more verbose output 
|-v or -version 
|--no-update-notifier	   disable updates check
|--nohooks	  suppress executing hooks 
|--no-telemetry		 disable telemetry collection for the current command 

- platform specific options, can be provided to be cordova-cli with a '--' separator that stops the command parsing within the cordova-lib module and pases through rest of the options ofr platform to parse 

- example to create a project with the camera plugin and run it for android platform 
| # Create a cordova project
| cordova create myApp com.myCompany.myApp myApp
| cd myApp
| # Add camera plugin to the project and remember that in config.xml
| cordova plugin add cordova-plugin-camera --save
| # Add camera plugin to the project and remember that in config.xml. Use npm install to fetch.
| cordova plugin add cordova-plugin-camera --save --fetch
| # Add android platform to the project and remember that in config.xml
| cordova platform add android --save
| # Add android platform to the project and remember that in config.xml. Use npm install to fetch.
| cordova platform add android --save --fetch
| # Check to see if your system is configured for building android platform.
| cordova requirements android
| # Build the android and emit verbose logs.
| cordova build android --verbose
| # Run the project on the android platform.
| cordova run android
| # Build for android platform in release mode with specified signing parameters.
| cordova build android --release -- --keystore="..\android.keystore" --storePassword=android --alias=mykey

- cordova create command, create the directory structure for the cordova project in the specified path 

$ cordova create path [id [name [config]]] [options]

value	   description 
path		directory which should not already exist 
id			default  io.cordova.hellocordova 
name	  application's display title 

options 
| --template, use a custom location in npm or github 
| --copy-from\	  --src 
| --link-to		symlink to specified www directory without creating a copy 

	+ directory structure 
myapp/
|-- config.xml
|-- hooks/
|-- merges/
| | |-- android/
| | |-- windows/
| | |-- ios/
|-- www/
|-- platforms/
| |-- android/
| |-- windows/
| |-- ios/
|-- plugins/
  |--cordova-plugin-camera/

	+ www/, contains the project's web artifacts they will copied on a cordova prepare to each platform's www directory 
	
	+ platforms/, contains all the source code and build scripts for the platform that you add to your project. use cli to build app then should not edit any files in the platforms/ directory 
	
	+ plugins/ 
	+ hooks/, contains scripts used to customize cordova-cli commands
	
	+ merges/, platform specific web assets(html, css, and js). these are deployed during a prepare to the appropriate native directory. files placed under merges/ will override the matching files in the www/ folder for the relevant platform 
	
	merges/
	|-- ios/
	| -- app.js
	|-- android/
	| -- android.js
	www/
	-- app.js
	
	after build, android app will contain both app.js and android.js. ios app will only contain app.js 
	
	+ recommanded not checkin platforms/ and plugins/ as a build artifact 
	
- cordova platform command 

$ cordova {platform | platforms} 
				  [ add <platform-spec> [...] {--save | link=<path> | --fetch} | 
				  {remove | rm} platform [...] {--save | --fetch}
				  {list | ls}
				  check | 
				  save   | 
				  update]
				  
| --link, When <platform-spec> is a local path, links the platform library directly instead of making a copy of it
| --fetch, fetches the platform using npm install and stores it into the apps node_modules 
|check, list paltforms which can be updated by cordova-cli platform update 

	+ <platform-spec> 
	<platform-spec> : platform[@version] | path | url[#commit-ish]
	path, to a directory containing a platform 
	commit-ish, commit/tag/branch reference. if none is specified 'master' is used 
	
	supported platforms 
	Android 
	iOS 
	Window(8.1, Phone 8.1, UWP -Window 10)
	Blackberry 10 
	Ubuntu 
	Browser 
	
- cordova plugin command 
cordova {plugin | plugins} [
				add <plugin-spec> [..] {--searchpath=<directory> | --noregistry | --link | --save | --browserify | --force | --fetch} |
				{remove | rm} {<pluginid> | <name>} --save --fetch |
				{list | ls} |
				search [<keyword>] |
				save |
				]
| --searchpath, when looking up plugins by ID, look in this directory and each of its subdirectories before hitting the registry. multiple search paths can be specified with ":" in *nix and ";" for windows 
| --link, installing from a local path creates a symbolic link instead of copying files. useful for plugin development 
| --browserify, compile plugin JS at build time using browserify instead of runtime 

	+ <plugin-spec>
	<plugin-spec> : [@scope/]pluginID[@version]|directory|url[#commit-ish][:subdir]
	
	scope, scope of plugin published as a scoped npm package, https://docs.npmjs.com/misc/scope
	plugin, plugin id 
	version 
	directory 
	url, url to a git repository containing a plugin.xml 
	commit-ish, commit/tag/branch reference if none is specified 'master' is used 
	subdir, sub-directory to find plugin.xml for the specified plugin 
	
	+ algorithm for resolving plugins 
	the plugin-spec, 
	as of cordova version 6.1 the latest plugin version published to npm that the current project can support 
	the latest plugin published to npm 
	
- cordova prepare command, transforms config.xml meta data to platform-specifc manifest files 
	copies icons & splashscreens, copies plugin files for specified platforms so that the project is ready to build 
	
cordova prepare [<platform> [..]]
 [--browserify | --fetch]
	
- cordova compile command, is a subset of the cordova build command. it only performs the compilation setp without doing prepare. this stage is useful to allow extending using hooks 

- cordova build command 

cordova build [<platform> [...]]
	[--debug|--release]
	[--device|--emulator|--target=<targetName>]
	[--buildConfig=<configfile>]
	[--browserify]
	[-- <platformOpts>]				

| --emulator, build it for an emulator, in particular the platform architecture might be different for a device vs emulator 
| --buildConfig=<configfile>  Default: build.json in cordova root directory.
Use the specified build configuration file. build.json
|--<platformOpts> provide platform specifc options 

- cordova run command 
cordova run [<platform> [...]]
	[--list | --debug | --release]
	[--noprepare] [--nobuild]
	[--device|--emulator|--target=<targetName>]
	[--buildConfig=<configfile>]
	[--browserify]
	[-- <platformOpts>]
	
| --list, available targets both device and emulator 
| --noprepare 
| --target, deploy to specific target emulator 
	
- cordova emulate command 
$ cordova run --emulator 

- cordova clean command 
$ cordova clean [<platform> [...]]
	
- requirement command, checks and print out all the requirements for platforms specified. if all requirements are met then exit with code 0 
$ cordova requirements android 
	
- cordova info command, print helpful information and debug reports and getting help 
$ cordova info 

- cordova serve command, run a local web server for www/assets using specified port or default to 8000 
http://HOST_IP:PORT/Platform/www 

$ cordova server [port]
				  
- telemetry command, turns telemetry collection on or off 

for more info https://cordova.apache.org/privacy
$ cordova telemetry on/off 
cordova build --no-telemetry 

- cordova help command, show syntax summary or the help for specific command 
cordova help [command]
cordova [command] -h
cordova -h [command]

				  
## Hooks 
- cordova hooks represent special scripts which could be added by application and plugin 
- supported hook types
hook type									 description 
before_platform_add				 
after_platform_add 
before_platform_rm,	  before remove 
after_platform_rm 
before_platform_ls, before platform list 
after_platform_ls
before_prepare 
after_prepare 
before_compile 
after_compile 
before_build 
after_build
before_emulate
after_emulate
before_run 
after_run 
before_serve
after_serve 
before_clean 
after_clean 
before_plugin_add
after_plugin_add 
before_plugin_rm 
after_plugin_rm 
before_plugin_ls 
after_plugin_ls 
before_plugin_search 
after_plugin_search 
before_plugin_install 
after_plugin_install 
before_plugin_uninstall 

- ways to define hooks, hooks could be defined in project's config.xml using <hoo> element, exp:
<hook type="before_build" src="scripts/appBeforeBuild.bat" />
<hook type="before_build" src="scripts/appBeforeBuild.js" />
<hook type="before_plugin_install" src="scripts/appBeforePluginInstall.js" />

<platform name="android">
	<hook type="before_build" src="scripts/wp8/appAndroidBeforeBuild.bat" />
	<hook type="before_build" src="scripts/wp8/appAndroidBeforeBuild.js" />
	<hook type="before_plugin_install" src="scripts/wp8/appWP8BeforePluginInstall.js" />
	...
</platform>

<platform name="windows">
	<hook type="before_build" src="scripts/windows/appWinBeforeBuild.bat" />
	<hook type="before_build" src="scripts/windows/appWinBeforeBuild.js" />
	<hook type="before_plugin_install" src="scripts/windows/appWinBeforePluginInstall.js" />
	...
</platform>

- order of hooks execution based on hooks definition 
	+ application hooks from /hooks 
	+ application hooks from config.xml 
	+  plugin hooks from plugins/.../plugin.xml 
	
- based on the internal order of execution 
- script interface 
	+ windows quirks, (javascript/non-javascript)
	+ cordova CLI will expect a shebang line as the first line for it to know the interpreter it needs to use to launch the script 
	#!/usr/bin/env [name_of_interpreter_executable]

- javascript hooks are run under node.js 
module.exports = function(context){

}

context object contains hook type executed script full path 
{
  "hook": "before_plugin_install",
  "scriptLocation": "c:\\script\\full\\path\\appBeforePluginInstall.js",
  "cmdLine": "The\\exact\\command\\cordova\\run\\with arguments",
  "opts": {
	"projectRoot":"C:\\path\\to\\the\\project",
	"cordova": {
	  "platforms": ["android"],
	  "plugins": ["plugin-withhooks"],
	  "version": "0.21.7-dev"
	},
	"plugin": {
	  "id": "plugin-withhooks",
	  "pluginInfo": {
		...
	  },
	  "platform": "android",
	  "dir": "C:\\path\\to\\the\\project\\plugins\\plugin-withhooks"
	}
  },
  "cordova": {...}
}
context.opts.plugin object will 

require additional cordova modules in your script using context.requireCordovaModule in the following way 
var Q = context.requireCordovaModule('q');

then we could make script async using Q 
module.exports = function(context) {
	var Q = context.requireCordovaModule('q');
	var deferral = new Q.defer();

	setTimeout(function(){
	  console.log('hook.js>> end');
	deferral.resolve();
	}, 1000);

	return deferral.promise;
}

new module loader script interface is used for the .js files defined via config.xml or plugin.xml only. hooks files in /hooks/ are run via node child_process spawn for compabitility 

- non-javascript are run via node child_process spawn from the project's root directory and have the root directory passes as the first argument 
CORDOVA_VERSION 
CORDOVA_PLATFORMS 
CORDOVA_PLUGINS 
CORDOVA_HOOK 
CORDOVA_CMDLINE 

if a script return a non-zero exit code, the the cordova command will be aborted 


## Plugin.xml 
- define the structure and settings required for your plugin 
- plugin element is the plugin manifest's top-level element 
Attributes(type)			description 
xmln								the plugin namespace http://apache.org/cordova/ns/plugins/1.0
id									 npm style identifier 
versions 

	+ example 

<?xml version="1.0" encoding="UTF-8"?>
<plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"
	xmlns:android="http://schemas.android.com/apk/res/android"
	id="my-plugin-id"
	version="1.0.2">

- engines and engine, specify versions of apache cordova-based frameworks 

in cordova 6.1.0+ recommended place to specify platform plugin and cli in a plugin's package.json 

Attributes(type)			description 
name							  name of the engine 
										cordova 
										cordova-plugman 
										cordova-android 
										cordova-ios 
										cordova-blackberry10 
										cordova-wp8 
										cordova-windows 
										cordova-osx 
										widnows-os 
										android-sdk 
										windows-sdk 
										apple-xcode 
										apple-ios 
										apple-osx 
										blackberry-ndk 
versions 
scriptSrc						for custom frameworks only 
platform(string)	

	+ exp 
<engines>
  <engine name="cordova-android" version="=1.8.0" />
</engines>

<engines>
  <engine name="cordova" version="&gt;=1.7.0" />
  <engine name="cordova-android" version="&gt;=1.8.0" />
  <engine name="cordova-ios" version="&gt;=1.7.1" />
</engines>

- name 
- description 
- author 
- keywords 
- license 
- asset, is used to list the files or directories to be copied into a cordova app's www directory, asset tags that are nested wth <platform> which are platform specified 
<!-- a single file, to be copied in the root directory -->
<asset src="www/foo.js" target="foo.js" />
<!-- a directory, also to be copied in the root directory -->
<asset src="www/foo" target="foo" />

Attributes  description 
src(string)		 where the file or directory is located 
target(string)	where the file should be located	   
	  
- js-module, most plugins include javascript files. each <js-modue> tag corresponds to a javascript file 
Attributes	  description 
src References a file in the plugin directory relative to the plugin.xml
name Provides the last part of the module name. 

<js-module src="socket.js" name="Socket">
</js-module>

	+ clobbers, allowed within <js-module> element. used to specified the namespace under window object where module.export gets inserted 
	
Attributes 
target, the namespace where module exports gets inserted to 
<js-module src="socket.js" name="Socket">
  <clobbers target="chrome.socket" />
</js-module>

	+ merges, allow js-module merge in to existing value 
<js-module src="socket.js" name="Socket">
  <merges target="chrome.socket" />
</js-module>

	+ runs, your code should be specified within cordova.require but not installed on the window object 

	you can only have one <run/> tag which is used for attaching event hadnlers etc. 
	
	<js-module src="socket.js" name="Socket">
		<runs/>
	</js-module>

	<runs/> with <clobbers/> or <merges/> is redundant 
	
- dependency, allows you to specify other plugins on which the current plugin depends 
id(string)
url(string), a git repo which cli attempts to clone 
commit(string), any git reference understood by git checkout 
subdir(string), specifies that the targeted plugin dependency exists 

- platform, identifies platforms that have associated native code or require 
<platform name="android">
  <!-- android-specific elements -->
</platform>

	+ source-file, identifies executable source code that should be installed into a project 
src, 
target-dir 
framework(boolean) apple only 
compiler flags(string) apple only 

exp:
<!-- android -->
<source-file src="src/android/Foo.java" target-dir="src/com/alunny/foo" />
<!-- ios -->

	+ header-file, specifically for platform such as ios and android 
<header-file src="CDVFoo.h" />

	+ resource-file 
<resource-file src="FooPluginStrings.xml" target="res/values/FooPluginStrings.xml" />

	+ config-file, where that document that modification should take place and what shold be modified. two file types have been tested for modification 
	
<config-file target="AndroidManifest.xml" parent="/manifest/application">
	<activity android:name="com.foo.Foo" android:label="@string/app_name">
		<intent-filter>
		</intent-filter>
	</activity>
</config-file>

	+ lib-file, user-generated libraries for window allow <lib-file> include <SDKReferece
	+ framework on which plugin depends 
src, 
custom, idicates whether the framework is included as part of your plugin files 
weak, default false, whether framework is weak linked 
type, indicate the type of framework to add 
parent, relative path to the directory containing the sub-project to which to add the reference 

	+ info addtional information provided to users 
	+ hook represents your custom script which will be called by cordova 
	+ uses-permission a plugin may need to make configuration changes dependent on the target application 
	+ preference, plugin may require user to specify values for their variables 
<preference name="MY_CUSTOM_STRING" default="default-value" />


## Plugin APIs 
- battery status 
	+ cordova-plugin-battery-status 
	
	+ adds following events to window 
	batterystatus 
	batterycritical
	batterylow 
	
	+ installation 
	$ cordova plugin add cordova-plugin-battery-status
	
	+ add event handler by window.addEventListener after deviceready event 
	
	+ status object 
	level 
	isPlugged 
	
	+ batterystatus event 
window.addEventListener("batterystatus", onBatteryStatus, false);

function onBatteryStatus(status) {
	console.log("Level: " + status.level + " isPlugged: " + status.isPlugged);
}

- camera 
	+ cordova-plugin-camera
	+ install 
	$ cordova plugin add cordova-plugin-camera
	
	+ report bug, https://issues.apache.org/jira/issues/?jql=project%20%3D%20CB%20AND%20status%20in%20(Open%2C%20%22In%20Progress%22%2C%20Reopened)%20AND%20resolution%20%3D%20Unresolved%20AND%20component%20%3D%20%22Plugin%20Camera%22%20ORDER%20BY%20priority%20DESC%2C%20summary%20ASC%2C%20updatedDate%20DESC
	
	+ contribute code, https://github.com/apache/cordova-plugin-camera/pulls
	http://wiki.apache.org/cordova/ContributorWorkflow
	
	+ generate documentation for javascript jsdoc-to-markdown 
	+ API Reference 
camera 
	.getPicture(successCallback, errorCallback, options), if success the image is passed as a base64 encoded string or as the uri for the image file. when Camera.sourceType equals Camera.PictureSourceType.CAMERA. 
	if it is  Camera.PictureSourceType.PHOTOLIBRARY or Camera.PictureSourceType.SAVEDPHOTOALBUM will let the user choose a existing 
	
	example:
	navigator.camera.getPicture(cameraSuccess, cameraError, cameraOptions);
	
	.cleanup(), only support in IOS, clear intermediate image files 
	.onError:function 
	.onSuccess:function 
	.CameraOptions:object 
	Properties		  type		default		 description 
	quality 
	destinationType 
	sourceType 
	allowEdit 
	encodingType 
	targetWidth 
	targetHeight 
	mediaType					   PICTURE		 
	correctOrientation  bool						rotate the image to correct for the orientation 
	saveToPhotoAlbum 
	popoverOptions 
	cameraDirection 
	
Camera 
	.DestinationType: enum 
	DATA_URL 0 
	FILE_URL 1 
	NATIVE_URL 2
	
	.EncodingType:enum 
	JPEG		0 
	PNG		 1
	
	.MediaType:enum 
	PICTURE	 0 
	VIDEO		  1 
	ALLMEDIA 2 
	
	.PictureSourceType:enum 
	PHOTOLIBRARY		 0 
	CAMERA					  1 
	SAVEDPHOTOALBUM  2 
	
	.PopoverArrowDirection:enum
	ARROW_UP 
	ARROW_DOWN 
	ARROW_LEFT 
	ARROW_RIGHT 
	ARROW_ANY 
	
	.Direction:enum 
	BACK 
	FRONT 
	
CameraPopoverHandle, support in ios a handle to an image picker popover 
CameraPopoverOptions
	+ browser and os quirks 
http://cordova.apache.org/docs/en/latest/reference/cordova-plugin-camera/index.html#amazon-fire-os-quirks

	+ simple html5 localstorage for mobile app http://brian.io/lawnchair/

- console 
	+ cordova-plugin-console, avaliable after deviceready event 
document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
	console.log("console.log works well");
}

	+ install 
	$ cordova plugin add cordova-plugin-console
	
	+ supported methods 
	console.log
	console.error
	console.exception
	console.warn
	console.info
	console.debug
	console.assert
	console.dir
	console.dirxml
	console.time
	console.timeEnd
	console.table
	
	+ format options 
	
	%j - format arg as JSON
	%o - format arg as JSON
	%c - format arg as ''. No color formatting could be done.
	%% - replace with '%'

- contacts 
	+ cordova-plugin-contacts, defines a global navigator.contacts object which provide access to device contacts database 
	
	avaliable after deviceready 
document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
console.log(navigator.contacts);
}

	+ install 
	$ cordova plugin add cordova-plugin-contacts
	
	+ methods 

	navigator.contacts.create, example 
		var myContact = navigator.contacts.create({"displayName": "Test User"});
		
	navigator.contacts.find
	navigator.contacts.pickContact

	+ objects 
	
Contact
ContactName
ContactField
ContactAddress
ContactOrganization
ContactFindOptions
ContactError
ContactFieldTyp

- device 
	+ cordova-plugin-device, describe device's hardware and software 
	+ install 
	$ cordova plugin add cordova-plugin-device
	
	+ properties 
	
	device.cordova, the version of cordova running on the device 
	device.model, the name of the device's model or product 
	
		// Android:	Nexus One	   returns "Passion" (Nexus One code name)
		//			 Motorola Droid  returns "voles"
		// BlackBerry: Torch 9800	  returns "9800"
		// Browser:	Google Chrome   returns "Chrome"
		//			 Safari		  returns "Safari"
		// iOS:	 for the iPad Mini, returns iPad2,5; iPhone 5 is iPhone 5,1. See http://theiphonewiki.com/wiki/index.php?title=Models
		// OSX:						returns "x86_64"
		// 
		var model = device.model;
		
	device.platform
	
		// Depending on the device, a few examples are:
		//   - "Android"
		//   - "BlackBerry 10"
		//   - "browser"
		//   - "iOS"
		//   - "WinCE"
		//   - "Tizen"
		//   - "Mac OS X"
		var devicePlatform = device.platform;
	
	device.uuid, device uuid 
	device.version
	device.manufacturer
	device.isVirtual, is running on a simulator 
	device.serial, hardware serial number 

- device motion 
	+ cordova-plugin-device-motion, provides access to the device's accelerometer which detect changes relative to the current orientation in three dimensions along the x, y and z 
	
	document.addEventListener("deviceready", onDeviceReady, false);
	function onDeviceReady() {
		console.log(navigator.accelerometer);
	}
	+ install
	$ cordova plugin add cordova-plugin-device-motion
	
	+ methods 
	
	navigator.accelerometer.getCurrentAcceleration
		function onSuccess(acceleration) {
			alert('Acceleration X: ' + acceleration.x + '\n' +
				  'Acceleration Y: ' + acceleration.y + '\n' +
				  'Acceleration Z: ' + acceleration.z + '\n' +
				  'Timestamp: '	  + acceleration.timestamp + '\n');
		}

		function onError() {
			alert('onError!');
		}

		navigator.accelerometer.getCurrentAcceleration(onSuccess, onError);
	
	navigator.accelerometer.watchAcceleration
	navigator.accelerometer.clearWatch

	+ objects 
	Acceleration 
   
- device orientation 
	+ cordova-plugin-device-orientation, provides access to the device's compass, the compass is a sensor that detects the direction or heading that device is pointed 
	it measures the heading in degrees from 0 to 359.99 where 0 is north 
document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
	console.log(navigator.compass);
}
	
	+ install 
	$ cordova plugin add cordova-plugin-device-orientation
	
	+ methods 

	navigator.compass.getCurrentHeading
		function onSuccess(heading) {
			alert('Heading: ' + heading.magneticHeading);
		};

		function onError(error) {
			alert('CompassError: ' + error.code);
		};

		navigator.compass.getCurrentHeading(onSuccess, onError);
		
	navigator.compass.watchHeading, Gets the device's current heading at a regular interval.
		function onSuccess(heading) {
			var element = document.getElementById('heading');
			element.innerHTML = 'Heading: ' + heading.magneticHeading;
		};

		function onError(compassError) {
			alert('Compass error: ' + compassError.code);
		};

		var options = {
			frequency: 3000
		}; // Update every 3 seconds

		var watchID = navigator.compass.watchHeading(onSuccess, onError, options);

	navigator.compass.clearWatch, clear the compass by watch id 
	
	+ CompassHeading the object returned by compassSuccess callback 
	Properties 
	magneticHeading, the heading in degrees from 0-359.99 
	trueHeading, the heading relative to the geographic north pole in degree 0-359.99 
	headingAccuracy, the deviation in degrees between the reported heading and the true heading 
	timestamp, DOMTimeStamp 
	
	+ CopmassError return by compassError callback 
	Properties 
	code	 CompassError.COMPASS_INTERNAL_ERR or CompassError.COMPASS_NOT_SUPPORTED

- dialogs 
	+ cordova-plugin-dialogs, provide access to some native UI dialog element via a global navigator.notification object. avaliable until deviceready 
	
	+ install 
	cordova plugin add cordova-plugin-dialogs
	
	+ methods 

	navigator.notification.alert, navigator.notification.alert(message, alertCallback, [title], [buttonName])
	navigator.notification.confirm, navigator.notification.confirm(message, confirmCallback, [title], [buttonLabels])
	navigator.notification.prompt, navigator.notification.prompt(message, promptCallback, [title], [buttonLabels], [defaultText])
	navigator.notification.beep, play a beep sound, navigator.notification.beep(times); The number of times to repeat the beep

- file 
	+ cordova-plugin-file, implement a file api allowing read/write access to files residing on the device 
	
	this plugin is based on html5 file api http://www.w3.org/TR/FileAPI/
	
	sample http://cordova.apache.org/docs/en/latest/reference/cordova-plugin-file/index.html#sample
	
	this is enabled after deviceready 
	
	+ installation 
	$ cordova plugin add cordova-plugin-file
	
	+ window phone 8/7 and window don't support FileReader.readAsArrayBuffer nor FileWriter.write(blob)
	
	+ where to store files file:///path/to/spot and can be converted to a directoryEntry using window.resolveLocalFileSystemURL()
	
	cordova.file.applicationDirectory, read only directory where the application is installed 
	cordova.file.applicationStorageDirectory, root directory of the application's sandbox 
	cordova.file.dataDirectory, persistent and private data storage within the application's sandbox using internal memory. on android also support .externalDataDirectory, on ios support .synceDataDirectory which iuse icloud 
	corodva.file.cacheDirectory, for cache data, os may delete these files when device runs low on storage 
	cordova.file.externalApplicationStorgageDirectory, android 
	cordova.file.externalDataDirectory android 
	cordova.file.externalCacheDirectory android 
	cordova.file.externalRootDirectory android/blackberry 10, external storage(sd card) root. 
	cordova.file.tempDirectory, temp directory that the os can clear at will 
	cordova.file.syncedDataDirectory, holds app-specific files that shold be synced (icloud, ios, windows)
	cordova.file.documentsDirectory, files private to the app but that are meaning ful to other app such as office files 
	cordova.file.sharedDirectory, files globally available to all apps 
	
	+ file system layouts, how the cordova.file.* map to physical path on real device. implementation detail 
	
		* ios file 
		device path													  cordova.file* 
		/var/mobile/Applications/<UUID>/		applicationStorageDirectory 
		appname.app/												application directory 
		Documents/												   documentsDirectory 
		NoCloud/ 
		Library/
		NoCloud/														dataDirectory 
		Cloud/															  cacheDirectory 
		tmp/																  tempDirectory 
		
		* android file system layout 
		file:///android_asset/			  applicationDirectory 
		/data/data/<app-id>/			 applicationStorageDirectory 
		cache											cacheDirectory 
		files											   dataDirectory 
		Documents 
		<sdcard>/								   externalRootDirectory
		Android/data/<app-id>		   externalApplicationStorgageDirectory
		cache											externalCacheDirectory
		files											   externalDataDirectory
		
		* windows file system layout 
		ms-appdata:///						 applicationDirectory
		local/										   dataDirectory
		temp/										   cacheDirectory 
		temp/										   tempDirectory 
		roaming/									 syncedDataDirectory
		
	+ list of error codes 
	|1 	NOT_FOUND_ERR
	|2 	SECURITY_ERR
	|3 	ABORT_ERR
	|4 	NOT_READABLE_ERR
	|5 	ENCODING_ERR
	|6 	NO_MODIFICATION_ALLOWED_ERR
	|7 	INVALID_STATE_ERR
	|8 	SYNTAX_ERR
	|9 	INVALID_MODIFICATION_ERR
	|10 	QUOTA_EXCEEDED_ERR
	|11 	TYPE_MISMATCH_ERR
	|12 	PATH_EXISTS_ERR
	
	+ sample create files and directories http://cordova.apache.org/docs/en/latest/reference/cordova-plugin-file/index.html#sample-create-files-and-directories-write-read-and-append-files
	
	+ create a persistent file, before use the file plugin you can get access to the file system using requestFileSystem which support either persistent or temporary 
window.requestFileSystem(LocalFileSystem.PERSISTENT, 0, function (fs) {

	console.log('file system open: ' + fs.name);
	fs.root.getFile("newPersistentFile.txt", { create: true, exclusive: false }, function (fileEntry) {

		console.log("fileEntry is file?" + fileEntry.isFile.toString());
		// fileEntry.name == 'someFile.txt'
		// fileEntry.fullPath == '/someFile.txt'
		writeFile(fileEntry, null);

	}, onErrorCreateFile);

}, onErrorLoadFs);

	+ create a temp file 
window.requestFileSystem(window.TEMPORARY, 5 * 1024 * 1024, function (fs) {

	console.log('file system open: ' + fs.name);
	createFile(fs.root, "newTempFile.txt", false);

}, onErrorLoadFs);

or 

function createFile(dirEntry, fileName, isAppend) {
	// Creates a new file or returns the file if it already exists.
	dirEntry.getFile(fileName, {create: true, exclusive: false}, function(fileEntry) {

		writeFile(fileEntry, null, isAppend);

	}, onErrorCreateFile);

}
	+ write to a file 
function writeFile(fileEntry, dataObj) {
	// Create a FileWriter object for our FileEntry (log.txt).
	fileEntry.createWriter(function (fileWriter) {

		fileWriter.onwriteend = function() {
			console.log("Successful file read...");
			readFile(fileEntry);
		};

		fileWriter.onerror = function (e) {
			console.log("Failed file read: " + e.toString());
		};

		// If data object is not passed in,
		// create a new Blob instead.
		if (!dataObj) {
			dataObj = new Blob(['some file data'], { type: 'text/plain' });
		}

		fileWriter.write(dataObj);
	});
}
	+ read a file 
function readFile(fileEntry) {

	fileEntry.file(function (file) {
		var reader = new FileReader();

		reader.onloadend = function() {
			console.log("Successful file read: " + this.result);
			displayFileData(fileEntry.fullPath + ": " + this.result);
		};

		reader.readAsText(file);

	}, onErrorReadFile);
}
	+ display an image 
function displayImageByFileURL(fileEntry) {
	var elem = document.getElementById('imageFile');
	elem.src = fileEntry.toURL();
}

	+ create directories 
function createDirectory(rootDirEntry) {
	rootDirEntry.getDirectory('NewDirInRoot', { create: true }, function (dirEntry) {
		dirEntry.getDirectory('images', { create: true }, function (subDirEntry) {

			createFile(subDirEntry, "fileInNewSubDir.txt");

		}, onErrorGetDir);
	}, onErrorGetDir);
}

- file transfer 
	+ cordova-plugin-file-transfer allows to upload and download files. this plugin defines FileTransfer, FileUploadOptions constructors 
	
	avaliable after deviceready 
	
document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
	console.log(FileTransfer);
}

	+ install 
	$ cordova plugin add cordova-plugin-file-transfer
	
	+ FileTransfer 
	Properties 
	onprogress, called with ProgressEvent when a new chunk of data is transferred 
	
	Methods 
	upload(fileURL, server/*URL*/, successCallback, errorCallback, options, trustAllHost(optional )
		options:
		fileKey, the name of the form element 
		fileName, the file name to use when saving the file on the server 
		httpMethod, PUT or POST default to POST 
		mimeType, default to image/jpeg(DOMString)
		params, a set of optional key/value paires to pass in the HTTP request DOMString 
		chunkedMode, whether to upload the data in chunked streaming mode default to true 
		headers, a map of header name/header values. use array to supply more than one value 
			
	download(source, target, successCallback, errorCallback, trustAllHosts, options(currently only support headers)
	abort 
	
	+ FileUploadResult, object is passed to the callback 
	properties 
	bytesSent 
	responseCode 
	response 
	headers, only support on ios 
	
	+ FileTransferError, object 
	properties:
	code 
	source 
	target 
	http_status 
	body 
	exception 
	
	constants:
	
	1 = FileTransferError.FILE_NOT_FOUND_ERR
	2 = FileTransferError.INVALID_URL_ERR
	3 = FileTransferError.CONNECTION_ERR
	4 = FileTransferError.ABORT_ERR
	5 = FileTransferError.NOT_MODIFIED_ERR

	+ sample http://cordova.apache.org/docs/en/latest/reference/cordova-plugin-file-transfer/index.html#sample-download-and-upload-files
	
- geolocation 
	+ cordova-plugin-geolocation, provides information about the device's location such as latitude and longitude 
	
	include GPS and location inferred form network signals such as IP, RFID, Wifi and bluetooth MAC address, GSM/CDMA cell ids. no guarantee that the api returns the device's actual location 
	
   document.addEventListener("deviceready", onDeviceReady, false);
	function onDeviceReady() {
		console.log("navigator.geolocation works well");
	}

	+ install 
	$ cordova plugin add cordova-plugin-geolocation
	
	+ methods 
	
	navigator.geolocation.getCurrentPosition(onSuccess, onError, options)
	
		var onSuccess = function(position) {
			alert('Latitude: '		  + position.coords.latitude		  + '\n' +
				  'Longitude: '		 + position.coords.longitude		 + '\n' +
				  'Altitude: '		  + position.coords.altitude		  + '\n' +
				  'Accuracy: '		  + position.coords.accuracy		  + '\n' +
				  'Altitude Accuracy: ' + position.coords.altitudeAccuracy  + '\n' +
				  'Heading: '		   + position.coords.heading		   + '\n' +
				  'Speed: '			 + position.coords.speed			 + '\n' +
				  'Timestamp: '		 + position.timestamp				+ '\n');
		};

		// onError Callback receives a PositionError object
		//
		function onError(error) {
			alert('code: '	+ error.code	+ '\n' +
				  'message: ' + error.message + '\n');
		}

		navigator.geolocation.getCurrentPosition(onSuccess, onError);
	
	navigator.geolocation.watchPosition(onSuccess, onError, options), return a watch id, should be used with navigator.geolocation.clearWatch(watchId/*string*/)
	
	navigator.geolocation.clearWatch
	
	+ geolocationOptions 
	enableHighAccuracy, by default device try to retrieve a position using network-based methods, set this to true will use satellite positioning 
	
	timeout, milliseconds
	
	maximumAge, accept a cached position whose age is no greater than the specified time, milliseconds 

	+ objects 
	
	Position
		Properties 
		coords, a set of geographic coordinates 
		timestamp
		
	PositionError
		Properties 
		code, one of the predefined error codes, PositionError.PERMISSION_DENIED, PositionError.POSITION_UNAVAILABLE, PositionError.TIMEOUT
		message
	Coordinates a object is attached to a position object 
		properties 
		latitude 
		longitude 
		altitude, height of the position in meters above the ellipsoid 
		accuracy 
		altitudeAccuracy 
		heading 
		speed 
		
	+ sample http://cordova.apache.org/docs/en/latest/reference/cordova-plugin-geolocation/index.html#sample-get-the-weather-find-stores-and-see-photos-of-things-nearby-with-geolocation
	
	get weather information from api.openweathermap.org

- globalization 
	+ cordova-plugin-globalization, plugin obtains information and performs operations specific to the user's location language and timezone 
	
	this plugin define a navigator.globalization object after deviceready 
	
	+ install 
	$ cordova plugin add cordova-plugin-globalization
	
	+ objects 
	GlobalizationError 
	
	+ methods 
	
	navigator.globalization.getPreferredLanguage
	navigator.globalization.getLocaleName
	navigator.globalization.dateToString
	navigator.globalization.stringToDate
	navigator.globalization.getDatePattern
	navigator.globalization.getDateNames
	navigator.globalization.isDayLightSavingsTime
	navigator.globalization.getFirstDayOfWeek
	navigator.globalization.numberToString
	navigator.globalization.stringToNumber
	navigator.globalization.getNumberPattern
	navigator.globalization.getCurrencyPattern

	+ reference http://cordova.apache.org/docs/en/latest/reference/cordova-plugin-globalization/index.html
	
- inappbrowser 
	+ cordova-plugin-inappbrowser, provides a web browser view that displays when calling cordova.InAppBrowser.open()
	
	var ref = cordova.InAppBrowser.open('http://apache.org', '_blank', 'location=yes');
	
	it is defined to replace the window.open() by 
	window.open = cordova.InAppBrowser.open;
	
	delete window.open // Reverts the call back to it's prototype's default
	
	+ install 
	$ cordova plugin add cordova-plugin-inappbrowser
	
	+ cordova.InAppBrowser.open
	var ref = cordova.InAppBrowser.open(url, target, options);
	ref, reference to the InAppBrowser window 
	url 
	target, _self(default) opens in the webview if url in white list otherwise open in InAppBrowser
				_blank, open in InAppBrowser
				_system, open in system's browser 
	options, for InAppBrowser, defaulting to location=yes, string must not contain any blank space, and each feature's name/value pairs must be separated by a comma. Feature names are case insensitive. 
		hidden 
		clearcache 
		clearsessioncache 
		zoom 
		hardwareback 
		mediaPlaybackRequesUserAction 
		
		ios only:
		closebuttoncaption 
		...
		
	+ InAppBrowser, the object return from a call opn 
	methods:
	
	addEventListener
	removeEventListener
	close
	show
	executeScript
	insertCSS

- media 
	+ cordova-plugin-media, provides the ability to record and play back audio files on a device. 
	
	define a global Media constructor 
	
document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
	console.log(Media);
}
	+ install 
	$ cordova plugin add cordova-plugin-media
	
	+ Media 
	var media = new Media(src, mediaSuccess, [mediaError], [mediaStatus]);
	src, url containing the audio content (domstring)
	
	var my_media = new Media('cdvfile://localhost/temporary/recording.mp3', ...);

	constants:
	
	Media.MEDIA_NONE = 0;
	Media.MEDIA_STARTING = 1;
	Media.MEDIA_RUNNING = 2;
	Media.MEDIA_PAUSED = 3;
	Media.MEDIA_STOPPED = 4;

	methods:
	

	media.getCurrentAmplitude: Returns the current position within an audio file.

	media.getCurrentPosition: Returns the current position within an audio file.

	media.getDuration: Returns the duration of an audio file.

	media.play: Start or resume playing an audio file.

	media.pause: Pause playback of an audio file.

	media.pauseRecord: Pause recording of an audio file.

	media.release: Releases the underlying operating system's audio resources.

	media.resumeRecord: Resume recording of an audio file.

	media.seekTo: Moves the position within the audio file.

	media.setVolume: Set the volume for audio playback.

	media.startRecord: Start recording an audio file.

	media.stopRecord: Stop recording an audio file.

	media.stop: Stop playing an audio file.

- media capture 
	+ cordova-plugin-media-capture, provide access to the device's audio, image and video capture capabitlities 
	
	document.addEventListener("deviceready", onDeviceReady, false);
	function onDeviceReady() {
		console.log(navigator.device.capture);
	}
	
	+ install 
	$ cordova plugin add cordova-plugin-media-capture
	
	+ objects 
	Capture
	CaptureAudioOptions
	CaptureImageOptions
	CaptureVideoOptions
	CaptureCallback
	CaptureErrorCB
	ConfigurationData
	MediaFile
	MediaFileDat
	
	+ methods 
	
	capture.captureAudio
	capture.captureImage
	capture.captureVideo
	MediaFile.getFormatData

	+ properties 
	supportedAudioModes 
	supportedImageModes 
	supportedVideoModels 
	
	+ capture.captureAudio 
	navigator.device.capture.captureAudio(
		CaptureCB captureSuccess, CaptureErrorCB captureError,  [CaptureAudioOptions options]
	);
	
- network information 
	+ cordova-plugin-network-information, provide a implementation of an old version of the network information api. it provides information about the device's cellular and wifi connection and whether the device has a internet connection 
	
	expose navigator.connection object after deviceready 
	+ install 
	$ cordova plugin add cordova-plugin-network-information
	
	+ properties 
	connection.type
	
	constants:
	
	Connection.UNKNOWN
	Connection.ETHERNET
	Connection.WIFI
	Connection.CELL_2G
	Connection.CELL_3G
	Connection.CELL_4G
	Connection.CELL
	Connection.NONE

	+ network events 
	offline, document.addEventListener("offline", yourCallbackFunction, false);
	
	online, document.addEventListener("online", yourCallbackFunction, false);
	
- splashscreen 
	+ cordova-plugin-splashscreen, this plugin displays and hides a splash screen during application launch. 
	
	+ install 
	$ cordova plugin add cordova-plugin-splashscreen
	
	+ add configuration 
	In the top-level config.xml file (not the one in platforms), add configuration elements like those specified here.
	
	directory structure:
projectRoot
	hooks
	platforms
	plugins
	www
		css
		img
		js
	res
		screen
			android
			ios
			windows	 
			
	configuration in config.xml :
<platform name="android">
	<!-- you can use any density that exists in the Android project -->
	<splash src="res/screen/android/splash-land-hdpi.png" density="land-hdpi"/>
	<splash src="res/screen/android/splash-land-ldpi.png" density="land-ldpi"/>
	<splash src="res/screen/android/splash-land-mdpi.png" density="land-mdpi"/>
	<splash src="res/screen/android/splash-land-xhdpi.png" density="land-xhdpi"/>

	<splash src="res/screen/android/splash-port-hdpi.png" density="port-hdpi"/>
	<splash src="res/screen/android/splash-port-ldpi.png" density="port-ldpi"/>
	<splash src="res/screen/android/splash-port-mdpi.png" density="port-mdpi"/>
	<splash src="res/screen/android/splash-port-xhdpi.png" density="port-xhdpi"/>
</platform>

<platform name="ios">
	<!-- images are determined by width and height. The following are supported -->
	<splash src="res/screen/ios/Default~iphone.png" width="320" height="480"/>
	<splash src="res/screen/ios/Default@2x~iphone.png" width="640" height="960"/>
	<splash src="res/screen/ios/Default-Portrait~ipad.png" width="768" height="1024"/>
	<splash src="res/screen/ios/Default-Portrait@2x~ipad.png" width="1536" height="2048"/>
	<splash src="res/screen/ios/Default-Landscape~ipad.png" width="1024" height="768"/>
	<splash src="res/screen/ios/Default-Landscape@2x~ipad.png" width="2048" height="1536"/>
	<splash src="res/screen/ios/Default-568h@2x~iphone.png" width="640" height="1136"/>
	<splash src="res/screen/ios/Default-667h.png" width="750" height="1334"/>
	<splash src="res/screen/ios/Default-736h.png" width="1242" height="2208"/>
	<splash src="res/screen/ios/Default-Landscape-736h.png" width="2208" height="1242"/>
</platform>

<platform name="windows">
	<!-- images are determined by width and height. The following are supported -->
	<splash src="res/screen/windows/splashscreen.png" width="620" height="300"/>
	<splash src="res/screen/windows/splashscreenphone.png" width="1152" height="1920"/>
</platform>

<platform name="blackberry10">
	<!-- Add a rim:splash element for each resolution and locale you wish -->
	<!-- http://developer.blackberry.com/html5/documentation/rim_splash_element.html -->
	<rim:splash src="res/screen/blackberry/splashscreen.png"/>
</platform>

<preference name="SplashScreenDelay" value="10000" />

	+ preferences:
	config.xml
	AutoHideSplashScreen , default true 
	 <preference name="AutoHideSplashScreen" value="true" />
	 
	 SplashScreenDelay 
	<preference name="SplashScreenDelay" value="3000" />

	ShowSplashScreenSpinner  default to true 
	<preference name="ShowSplashScreenSpinner" value="false"/>
	
	+ methods 
	
	splashscreen.show
	splashscreen.hide
	
- vibration 
	+ cordova-plugin-vibration, this plugin provide a to vibrate the device 
	
	expose navigator.vibrate after deviceready 
	
	+ install 
	$ cordova plugin add cordova-plugin-vibration
	
	+ vibrate, this function has three different functionalities based on parameters passed to it 
	navigator.vibrate(time), milisecond
	or 
	navigator.vibrate([time])
	
- statusbar 
	+ cordova-plugin-statusbar provide functions to customize the ios and android statusbar 
	
	+ install 
	$ cordova plugin add cordova-plugin-statusbar
	
	+ preferences 
	config.xml 
	StatusBarOverlaysWebView default true 
	<preference name="StatusBarOverlaysWebView" value="true" />
	
	StatusbarBackgroundColor, no default value 
	<preference name="StatusBarBackgroundColor" value="#000000" />
	
	StatusBarStyle, default to light content 
	<preference name="StatusBarStyle" value="lightcontent" />
	
	+ hiding at startup you must modify your app's Info.plist file. add/edit these two attributes if not presetn set "Status bar is initially hidden" to "YES" and  "View controller-based status bar appearance" to "NO"
	
	added without xcode by 
	<key>UIStatusBarHidden</key>
	<true/>
	<key>UIViewControllerBasedStatusBarAppearance</key>
	<false/>
	
	+ methods, global StatusBar object 
	
	StatusBar.overlaysWebView
	StatusBar.styleDefault
	StatusBar.styleLightContent
	StatusBar.styleBlackTranslucent
	StatusBar.styleBlackOpaque
	StatusBar.backgroundColorByName
	StatusBar.backgroundColorByHexString
	StatusBar.hide
	StatusBar.show

	+ properties 
	StatusBar.isVisible 
	
	+ add permission in config.xml 
	<feature name="StatusBar">
			<param name="ios-package" value="CDVStatusBar" onload="true" />
	</feature>
- whitelist 
	+ cordova-plugin-whitelist, implements a whitelist policy for navigating the application webview on cordova 4. 0 
	
	controls which URLs the webview iteself can be navigated to, applies to top-level navigations only 
	
	+ add to config.xml 
<!-- Allow links to example.com -->
<allow-navigation href="http://example.com/*" />

<!-- Wildcards are allowed for the protocol, as a prefix
	 to the host, or as a suffix to the path -->
<allow-navigation href="*://*.example.com/*" />

<!-- A wildcard can be used to whitelist the entire network,
	 over HTTP and HTTPS.
	 *NOT RECOMMENDED* -->
<allow-navigation href="*" />

<!-- The above is equivalent to these three declarations -->
<allow-navigation href="http://*/*" />
<allow-navigation href="https://*/*" />
<allow-navigation href="data:*" />

	this whitelist doenot apply to plugin only effect the window.open method 
	
	+ suggest use cordova content security policy, in config.xml, network request whitelist, http://cordova.apache.org/docs/en/latest/reference/cordova-plugin-whitelist/index.html#content-security-policy instead of the below configuration 
<!-- Allow images, xhrs, etc. to google.com -->
<access origin="http://google.com" />
<access origin="https://google.com" />

<!-- Access to the subdomain maps.google.com -->
<access origin="http://maps.google.com" />

<!-- Access to all the subdomains on google.com -->
<access origin="http://*.google.com" />

<!-- Enable requests to content: URLs -->
<access origin="content:///*" />

<!-- Don't block any requests -->
<access origin="*" />	   

- legacy whitelist