Return-Path: X-Original-To: apmail-cordova-commits-archive@www.apache.org Delivered-To: apmail-cordova-commits-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 93D1510AE3 for ; Thu, 20 Feb 2014 21:09:27 +0000 (UTC) Received: (qmail 70056 invoked by uid 500); 20 Feb 2014 21:08:55 -0000 Delivered-To: apmail-cordova-commits-archive@cordova.apache.org Received: (qmail 69756 invoked by uid 500); 20 Feb 2014 21:08:49 -0000 Mailing-List: contact commits-help@cordova.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@cordova.apache.org Delivered-To: mailing list commits@cordova.apache.org Received: (qmail 69514 invoked by uid 99); 20 Feb 2014 21:08:44 -0000 Received: from tyr.zones.apache.org (HELO tyr.zones.apache.org) (140.211.11.114) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 20 Feb 2014 21:08:44 +0000 Received: by tyr.zones.apache.org (Postfix, from userid 65534) id E3E7F92A782; Thu, 20 Feb 2014 21:08:42 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: purplecabbage@apache.org To: commits@cordova.apache.org Date: Thu, 20 Feb 2014 21:09:28 -0000 Message-Id: In-Reply-To: References: X-Mailer: ASF-Git Admin Mailer Subject: [49/50] [abbrv] docs commit: Version 3.4.0 Version 3.4.0 Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/0e2118b6 Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/0e2118b6 Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/0e2118b6 Branch: refs/heads/master Commit: 0e2118b6d6b526dc9befdff5ad4320534e9dacb8 Parents: 748f671 Author: Steven Gill Authored: Tue Feb 18 16:21:50 2014 -0800 Committer: Jesse MacFadyen Committed: Thu Feb 20 13:02:35 2014 -0800 ---------------------------------------------------------------------- docs/en/3.4.0/config.json | 18 + docs/en/3.4.0/config_ref/images.md | 185 +++++ docs/en/3.4.0/config_ref/index.md | 178 +++++ .../3.4.0/cordova/events/events.backbutton.md | 81 ++ .../3.4.0/cordova/events/events.deviceready.md | 90 +++ .../cordova/events/events.endcallbutton.md | 78 ++ docs/en/3.4.0/cordova/events/events.md | 47 ++ .../3.4.0/cordova/events/events.menubutton.md | 80 ++ docs/en/3.4.0/cordova/events/events.pause.md | 101 +++ docs/en/3.4.0/cordova/events/events.resume.md | 114 +++ .../3.4.0/cordova/events/events.searchbutton.md | 79 ++ .../cordova/events/events.startcallbutton.md | 79 ++ .../cordova/events/events.volumedownbutton.md | 79 ++ .../cordova/events/events.volumeupbutton.md | 79 ++ docs/en/3.4.0/cordova/plugins/pluginapis.md | 80 ++ docs/en/3.4.0/cordova/storage/storage.md | 70 ++ docs/en/3.4.0/guide/appdev/privacy/index.md | 117 +++ docs/en/3.4.0/guide/appdev/whitelist/index.md | 168 ++++ docs/en/3.4.0/guide/cli/index.md | 497 ++++++++++++ docs/en/3.4.0/guide/hybrid/plugins/index.md | 211 +++++ docs/en/3.4.0/guide/hybrid/webviews/index.md | 36 + docs/en/3.4.0/guide/overview/index.md | 139 ++++ .../guide/platforms/amazonfireos/config.md | 66 ++ .../3.4.0/guide/platforms/amazonfireos/index.md | 145 ++++ .../guide/platforms/amazonfireos/plugin.md | 100 +++ .../guide/platforms/amazonfireos/webview.md | 113 +++ docs/en/3.4.0/guide/platforms/android/config.md | 93 +++ docs/en/3.4.0/guide/platforms/android/index.md | 244 ++++++ docs/en/3.4.0/guide/platforms/android/plugin.md | 240 ++++++ docs/en/3.4.0/guide/platforms/android/tools.md | 85 ++ .../3.4.0/guide/platforms/android/upgrading.md | 454 +++++++++++ .../en/3.4.0/guide/platforms/android/webview.md | 131 +++ .../guide/platforms/blackberry10/config.md | 51 ++ .../3.4.0/guide/platforms/blackberry10/index.md | 199 +++++ .../guide/platforms/blackberry10/plugin.md | 255 ++++++ .../3.4.0/guide/platforms/blackberry10/tools.md | 178 +++++ .../guide/platforms/blackberry10/upgrading.md | 490 ++++++++++++ .../en/3.4.0/guide/platforms/firefoxos/index.md | 87 ++ docs/en/3.4.0/guide/platforms/index.md | 98 +++ docs/en/3.4.0/guide/platforms/ios/config.md | 113 +++ docs/en/3.4.0/guide/platforms/ios/index.md | 231 ++++++ docs/en/3.4.0/guide/platforms/ios/plugin.md | 246 ++++++ docs/en/3.4.0/guide/platforms/ios/tools.md | 63 ++ docs/en/3.4.0/guide/platforms/ios/upgrading.md | 788 +++++++++++++++++++ docs/en/3.4.0/guide/platforms/ios/webview.md | 185 +++++ docs/en/3.4.0/guide/platforms/tizen/index.md | 116 +++ docs/en/3.4.0/guide/platforms/ubuntu/index.md | 97 +++ docs/en/3.4.0/guide/platforms/win8/index.md | 124 +++ docs/en/3.4.0/guide/platforms/win8/tools.md | 50 ++ docs/en/3.4.0/guide/platforms/win8/upgrading.md | 61 ++ docs/en/3.4.0/guide/platforms/wp7/index.md | 131 +++ docs/en/3.4.0/guide/platforms/wp8/index.md | 162 ++++ docs/en/3.4.0/guide/platforms/wp8/plugin.md | 224 ++++++ docs/en/3.4.0/guide/platforms/wp8/tools.md | 113 +++ docs/en/3.4.0/guide/platforms/wp8/upgrading.md | 435 ++++++++++ docs/en/3.4.0/guide/support/index.md | 324 ++++++++ docs/en/3.4.0/index.md | 90 +++ docs/en/3.4.0/plugin_ref/plugman.md | 193 +++++ docs/en/3.4.0/plugin_ref/spec.md | 586 ++++++++++++++ 59 files changed, 9967 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0e2118b6/docs/en/3.4.0/config.json ---------------------------------------------------------------------- diff --git a/docs/en/3.4.0/config.json b/docs/en/3.4.0/config.json new file mode 100644 index 0000000..99f6553 --- /dev/null +++ b/docs/en/3.4.0/config.json @@ -0,0 +1,18 @@ +{ + "language": "English", + "merge": { + "events.md": [ + "cordova/events/events.md", + "cordova/events/events.deviceready.md", + "cordova/events/events.pause.md", + "cordova/events/events.resume.md", + "cordova/events/events.backbutton.md", + "cordova/events/events.menubutton.md", + "cordova/events/events.searchbutton.md", + "cordova/events/events.startcallbutton.md", + "cordova/events/events.endcallbutton.md", + "cordova/events/events.volumedownbutton.md", + "cordova/events/events.volumeupbutton.md" + ] + } +} http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0e2118b6/docs/en/3.4.0/config_ref/images.md ---------------------------------------------------------------------- diff --git a/docs/en/3.4.0/config_ref/images.md b/docs/en/3.4.0/config_ref/images.md new file mode 100644 index 0000000..27be27f --- /dev/null +++ b/docs/en/3.4.0/config_ref/images.md @@ -0,0 +1,185 @@ +--- +license: Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. +--- + +# Icons and Splash Screens + +This section shows how to configure an app's icon and optional splash +screen for various platforms, both when working in the Cordova CLI +(described in The Command-Line Interface) or using platform-specific +SDK tools (detailed in the Platform Guides). + +## Configuring Icons in the CLI + +When working in the CLI, icon source files are located within various +platform-specific subdirectories within the project's `www/res/icons` +directory. Newly created projects come with a default set of Cordova +icons for you to replace for the platforms you wish to target. + +Android specifies icons for low, medium, high, and extra-high resolutions: + + android/icon-36-ldpi.png + android/icon-48-mdpi.png + android/icon-72-hdpi.png + android/icon-96-xhdpi.png + +The iOS platform specifies 72-pixel-square icons for iPads, and +57-pixel icons for iPhones and iPods, with high-resolution _2x_ +variants for retina displays: + + ios/icon-57-2x.png + ios/icon-57.png + ios/icon-72-2x.png + ios/icon-72.png + +Windows Phone specifies a default 48-pixel icon, along with various +devices' background tiling images used when representing applications: + + windows-phone/icon-48.png + windows-phone/icon-62-tile.png + windows-phone/icon-173-tile.png + +Blackberry 10 requires an icon element in config.xml: + + + +See BlackBerry's documentation for targeting multiple sizes and locales. + +[http://developer.blackberry.com/html5/documentation/icon_element.html] + +Tizen requires an 128-pixel icon: + + tizen/icon-128.png + +## Configuring Splash Screens in the CLI + +Use the Splashscreen API to enable display of an app's introductory +splash screen on many platforms. When working in the CLI, splash +screen source files are located within the project's `www/res/screens` +subdirectory. + +Android specifies both portrait- and landscape-oriented splash screen +images for low, medium, high, and extra-high resolutions: + + android/screen-hdpi-landscape.png + android/screen-hdpi-portrait.png + android/screen-ldpi-landscape.png + android/screen-ldpi-portrait.png + android/screen-mdpi-landscape.png + android/screen-mdpi-portrait.png + android/screen-xhdpi-landscape.png + android/screen-xhdpi-portrait.png + +The iOS platform specifies variants for iPhone/iPod and iPad, with +variants for retina displays and different orientations. The _568h_ +file applies to the iPhone 5's taller screen: + + ios/screen-ipad-landscape-2x.png + ios/screen-ipad-landscape.png + ios/screen-ipad-portrait-2x.png + ios/screen-ipad-portrait.png + ios/screen-iphone-landscape-2x.png + ios/screen-iphone-landscape.png + ios/screen-iphone-portrait-2x.png + ios/screen-iphone-portrait.png + ios/screen-iphone-portrait-568h-2x.png + +Windows Phone specifies a single splash screen image: + + windows-phone/screen-portrait.jpg + +The following sections detail how to set up splash screens when +working with SDKs and related command-line tools described in Platform +Guides. + +Don't forget to install the SplashScreen plugin before trying to use the +`navigator.splashscreen.hide()` or `navigator.splashscreen.show()` methods. + +## Splash Screens for the Android Platform + +Place [9-patch image](https://developer.android.com/tools/help/draw9patch.html) +files in the Android project's `platforms/android/res/drawable*` directories. + +The size for each should be: + +- xlarge (xhdpi): at least 960 × 720 +- large (hdpi): at least 640 × 480 +- medium (mdpi): at least 470 × 320 +- small (ldpi): at least 426 × 320 + +When creating a new Android project, the default splash screen images +provided in the Cordova sample app should already be present in the +`platforms/android/res/drawable*` directories. Feel free to replace these +with your own images. +When providing your own splash screen images, you do not need to +provide the same permutation of 8 as the Cordova default ones +here. More or less optimization can be used. +The `drawable` directory names must follow the Android conventions for +supporting +[screen sizes](http://developer.android.com/guide/practices/screens_support.html) and +[alternate resources](http://developer.android.com/guide/topics/resources/providing-resources.html#AlternativeResources). + +In the top-level `config.xml` file (not the one in `platforms`), add the +following preferences: + + + + +The first line sets the image to display as the splash screen. This is the +file name of the png in the `drawable*` directories, minus the `.png` +extension. The default value for SplashScreen is `screen` (for the file +`platforms/android/res/drawable*/screen.png`), so if you +name the image anything other than `screen.png` in the `drawable*` directories, +you need to add/modify this line. + +The second line sets the default delay of how long the splashscreen appears in +milliseconds. This should be the worst-case expected start time. +The default value for SplashScreenDelay is 3000 ms. + +Finally, as a best practice, the splash screen should be present only as long +as necessary. When your app has started and the webview has loaded, your app +should hide the splash screen so that your main view is visible as soon as it +is ready. Because the app start time will vary quite a bit due to a number of +factors such as CPU speed and network, it is recommended that your app +explicitly invoke `navigator.splashscreen.hide()` in the JavaScript +method that responds to the `deviceready` event. Otherwise the splash screen +will be visible for the SplashScreenDelay value that you configured above, +which is likely longer than necessary. +This event-driven approach is highly recommended versus having the splash +screen visible for always a fixed duration. + +## Splash Screens for the iOS Platform + +Copy splash screen images into the iOS project's `Resources/splash` +directory. Only add those images for the devices you want to support, +such as iPad or iPhone. The size of each image should be: + +- Default-568h@2x~iphone.png (640x1136 pixels) +- Default-Landscape@2x~ipad.png (2048x1496 pixels) +- Default-Landscape~ipad.png (1024x748 pixels) +- Default-Portrait@2x~ipad.png (1536x2008 pixels) +- Default-Portrait~ipad.png (768x1004 pixels) +- Default@2x~iphone.png (640x960 pixels) +- Default~iphone.png (320x480 pixels) + +## Splash Screens for the BlackBerry 10 Platform + +Add a rim:splash element to config.xml for each resolution and locale you wish +to support: + + http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0e2118b6/docs/en/3.4.0/config_ref/index.md ---------------------------------------------------------------------- diff --git a/docs/en/3.4.0/config_ref/index.md b/docs/en/3.4.0/config_ref/index.md new file mode 100644 index 0000000..2df9931 --- /dev/null +++ b/docs/en/3.4.0/config_ref/index.md @@ -0,0 +1,178 @@ +--- +license: Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. +--- + +# The config.xml File + +Many aspects of an app's behavior can be controlled with a global +configuration file, `config.xml`. This +platform-agnostic XML file is arranged based on the W3C's [Packaged +Web Apps (Widgets)](http://www.w3.org/TR/widgets/) specification, and +extended to specify core Cordova API features, plugins, and +platform-specific settings. + +For projects created with the Cordova CLI (described in The +Command-Line Interface), this file can be found in the top-level +directory: + + app/config.xml + +Note that before version 3.3.1-0.2.0, the file existed at `app/www/config.xml`, +and that having it here is still supported. + +When using the CLI to build a project, versions of this file are +passively copied into various `platforms/` subdirectories, for example: + + app/platforms/ios/AppName/config.xml + app/platforms/blackberry10/www/config.xml + app/platforms/android/res/xml/config.xml + +This section details global and cross-platform configuration options. +See the following sections for platform-specific options: + +- iOS Configuration +- Android Configuration +- BlackBerry 10 Configuration + +In addition to the various configuration options detailed below, you +can also configure an application's core set of images for each target +platform. See Icons and Splash Screens for more information. + +## Core Configuration Elements + +This example shows the default `config.xml` generated by the CLI's +`create` command, described in The Command-Line Interface: + + + HelloWorld + + A sample Apache Cordova application that responds to the deviceready event. + + + Apache Cordova Team + + + + + +The following configuration elements appear in the top-level +`config.xml` file, and are supported across all supported Cordova +platforms: + +- The `` element's `id` attribute provides the app's + reverse-domain identifier, and the `version` its full version number + expressed in major/minor/patch notation. + +- The `` element specifies the app's formal name, as it appears + on the device's home screen and within app-store interfaces. + +- The `` and `` elements specify metadata and + contact information that may appear within app-store listings. + +- The optional `` element defines the app's starting + page in the top-level web assets directory. The default value is + `index.html`, which customarily appears in a project's top-level + `www` directory. + +- `` elements define the set of external domains the app is + allowed to communicate with. The default value shown above allows + it to access any server. See the Domain Whitelist Guide for details. + +- The `` tag sets various options as pairs of + `name`/`value` attributes. Each preference's `name` is + case-insensitive. Many preferences are unique to specific + platforms, as listed at the top of this page. The following sections + detail preferences that apply to more than one platform. + +## Global Preferences + +The following global preferences apply to all platforms: + +- `Fullscreen` allows you to hide the status bar at the top of the + screen. The default value is `false`. Example: + + + +- `Orientation` allows you to lock orientation and prevent the + interface from rotating in response to changes in orientation. + Possible values are `default`, `landscape`, or `portrait`. Example: + + + + __NOTE__: The `default` value means _both_ landscape and portrait + orientations are enabled. If you want to use each platform's + default settings (usually portrait-only), leave this tag out of the + `config.xml` file. + +## Multi-Platform Preferences + +The following preferences apply to more than one platform, but not to +all of them: + +- `DisallowOverscroll` (boolean, defaults to `false`): set to `true` + if you don't want the interface to display any feedback when users + scroll past the beginning or end of content. + + + + Applies to Android and iOS. On iOS, overscroll gestures cause + content to bounce back to its original position. On Android, they + produce a more subtle glowing effect along the top or bottom edge of + the content. + +- `BackgroundColor`: Set the app's background color. Supports a + four-byte hex value, with the first byte representing the alpha + channel, and standard RGB values for the following three bytes. This + example specifies blue: + + + + Applies to Android and BlackBerry. Overrides CSS otherwise available + across _all_ platforms, for example: `body{background-color:blue}`. + +- `HideKeyboardFormAccessoryBar` (boolean, defaults to `false`): set + to `true` to hide the additional toolbar that appears above the + keyboard, helping users navigate from one form input to another. + + + + Applies to iOS and BlackBerry. + +## The _feature_ Element + +If you use the CLI to build applications, you use the `plugin` command +to enable device APIs. This does not modify the top-level `config.xml` +file, so the `` element does not apply to your workflow. If +you work directly in an SDK and using the platform-specific +`config.xml` file as source, you use the `` tag to enable +device-level APIs and external plugins. They often appear with custom values in +platform-specific `config.xml` files. For example, here is how to specify the +Device API for Android projects: + + + + + +Here is how the element appears for iOS projects: + + + + + +See the API Reference for details on how to specify each feature. See +the Plugin Development Guide for more information on plugins. http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0e2118b6/docs/en/3.4.0/cordova/events/events.backbutton.md ---------------------------------------------------------------------- diff --git a/docs/en/3.4.0/cordova/events/events.backbutton.md b/docs/en/3.4.0/cordova/events/events.backbutton.md new file mode 100644 index 0000000..c40d00a --- /dev/null +++ b/docs/en/3.4.0/cordova/events/events.backbutton.md @@ -0,0 +1,81 @@ +--- + license: Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. +--- + +# backbutton + +The event fires when the user presses the back button. + + document.addEventListener("backbutton", yourCallbackFunction, false); + +## Details + +To override the default back-button behavior, register an event +listener for the `backbutton` event, typically by calling +`document.addEventListener` once you receive the `deviceready` event. +It is no longer necessary to call any other method to override the +back-button behavior. + +## Supported Platforms + +- Amazon Fire OS +- Android +- BlackBerry 10 +- Windows Phone 7 and 8 + +## Quick Example + + document.addEventListener("backbutton", onBackKeyDown, false); + + function onBackKeyDown() { + // Handle the back button + } + +## Full Example + + + + + Back Button Example + + + + + + + http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0e2118b6/docs/en/3.4.0/cordova/events/events.deviceready.md ---------------------------------------------------------------------- diff --git a/docs/en/3.4.0/cordova/events/events.deviceready.md b/docs/en/3.4.0/cordova/events/events.deviceready.md new file mode 100644 index 0000000..47537b0 --- /dev/null +++ b/docs/en/3.4.0/cordova/events/events.deviceready.md @@ -0,0 +1,90 @@ +--- + license: Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. +--- + +# deviceready + +The event fires when Cordova is fully loaded. + + document.addEventListener("deviceready", yourCallbackFunction, false); + +## Details + +This event is essential to any application. It signals that Cordova's +device APIs have loaded and are ready to access. + +Cordova consists of two code bases: native and JavaScript. While the +native code loads, a custom loading image displays. However, +JavaScript only loads once the DOM loads. This means the web app may +potentially call a Cordova JavaScript function before the +corresponding native code becomes available. + +The `deviceready` event fires once Cordova has fully loaded. Once the +event fires, you can safely make calls to Cordova APIs. Applications +typically attach an event listener with `document.addEventListener` +once the HTML document's DOM has loaded. + +The `deviceready` event behaves somewhat differently from others. Any +event handler registered after the `deviceready` event fires has its +callback function called immediately. + +## Supported Platforms + +- Amazon Fire OS +- Android +- BlackBerry 10 +- iOS +- Tizen +- Windows Phone 7 and 8 +- Windows 8 + +## Quick Example + + document.addEventListener("deviceready", onDeviceReady, false); + + function onDeviceReady() { + // Now safe to use device APIs + } + +## Full Example + + + + + Device Ready Example + + + + + + + http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0e2118b6/docs/en/3.4.0/cordova/events/events.endcallbutton.md ---------------------------------------------------------------------- diff --git a/docs/en/3.4.0/cordova/events/events.endcallbutton.md b/docs/en/3.4.0/cordova/events/events.endcallbutton.md new file mode 100644 index 0000000..8b3e21d --- /dev/null +++ b/docs/en/3.4.0/cordova/events/events.endcallbutton.md @@ -0,0 +1,78 @@ +--- + license: Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. +--- + +# endcallbutton + +This event fires when the user presses the end call button. + + document.addEventListener("endcallbutton", yourCallbackFunction, false); + +## Details + +The event overrides the default end call behavior. + +Applications typically should use `document.addEventListener` to +attach an event listener once the `deviceready` event fires. + +## Supported Platforms + +- BlackBerry 10 + +## Quick Example + + document.addEventListener("endcallbutton", onEndCallKeyDown, false); + + function onEndCallKeyDown() { + // Handle the end call button + } + +## Full Example + + + + + End Call Button Example + + + + + + + http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0e2118b6/docs/en/3.4.0/cordova/events/events.md ---------------------------------------------------------------------- diff --git a/docs/en/3.4.0/cordova/events/events.md b/docs/en/3.4.0/cordova/events/events.md new file mode 100644 index 0000000..ed7984c --- /dev/null +++ b/docs/en/3.4.0/cordova/events/events.md @@ -0,0 +1,47 @@ +--- + license: Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. +--- + +# Events + +> Cordova lifecycle events. + +## Event Types + +- deviceready +- pause +- resume +- backbutton +- menubutton +- searchbutton +- startcallbutton +- endcallbutton +- volumedownbutton +- volumeupbutton + +## Events added by [org.apache.cordova.battery-status](https://github.com/apache/cordova-plugin-battery-status/blob/master/doc/index.md) + +- batterycritical +- batterylow +- batterystatus + +## Events added by [org.apache.cordova.network-information](https://github.com/apache/cordova-plugin-network-information/blob/master/doc/index.md) + +- online +- offline + http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0e2118b6/docs/en/3.4.0/cordova/events/events.menubutton.md ---------------------------------------------------------------------- diff --git a/docs/en/3.4.0/cordova/events/events.menubutton.md b/docs/en/3.4.0/cordova/events/events.menubutton.md new file mode 100644 index 0000000..2d3006a --- /dev/null +++ b/docs/en/3.4.0/cordova/events/events.menubutton.md @@ -0,0 +1,80 @@ +--- +license: Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. +--- + +# menubutton + +The event fires when the user presses the menu button. + + document.addEventListener("menubutton", yourCallbackFunction, false); + +## Details + +Applying an event handler overrides the default menu button behavior. + +Applications typically should use `document.addEventListener` to +attach an event listener once the `deviceready` event fires. + +## Supported Platforms + +- Amazon Fire OS +- Android +- BlackBerry 10 + +## Quick Example + + document.addEventListener("menubutton", onMenuKeyDown, false); + + function onMenuKeyDown() { + // Handle the back button + } + +## Full Example + + + + + Menu Button Example + + + + + + + http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0e2118b6/docs/en/3.4.0/cordova/events/events.pause.md ---------------------------------------------------------------------- diff --git a/docs/en/3.4.0/cordova/events/events.pause.md b/docs/en/3.4.0/cordova/events/events.pause.md new file mode 100644 index 0000000..dc6f4f0 --- /dev/null +++ b/docs/en/3.4.0/cordova/events/events.pause.md @@ -0,0 +1,101 @@ +--- +license: Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. +--- + +# pause + +The event fires when an application is put into the background. + + document.addEventListener("pause", yourCallbackFunction, false); + +## Details + +The `pause` event fires when the native platform puts the application +into the background, typically when the user switches to a different +application. + +Applications typically should use `document.addEventListener` to +attach an event listener once the `deviceready` event fires. + +## Supported Platforms + +- Amazon Fire OS +- Android +- BlackBerry 10 +- iOS +- Windows Phone 7 and 8 +- Windows 8 + +## Quick Example + + document.addEventListener("pause", onPause, false); + + function onPause() { + // Handle the pause event + } + +## Full Example + + + + + Pause Example + + + + + + + + +## iOS Quirks + +In the `pause` handler, any calls to the Cordova API or to native +plugins that go through Objective-C do not work, along with any +interactive calls, such as alerts or `console.log()`. They are only +processed when the app resumes, on the next run loop. + +The iOS-specific `resign` event is available as an alternative to +`pause`, and detects when users enable the __Lock__ button to lock the +device with the app running in the foreground. If the app (and +device) is enabled for multi-tasking, this is paired with a subsequent +`pause` event, but only under iOS 5. In effect, all locked apps in iOS +5 that have multi-tasking enabled are pushed to the background. For +apps to remain running when locked under iOS 5, disable the app's +multi-tasking by setting +[UIApplicationExitsOnSuspend](http://developer.apple.com/library/ios/#documentation/general/Reference/InfoPlistKeyReference/Articles/iPhoneOSKeys.html) +to `YES`. To run when locked on iOS 4, this setting does not matter. http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0e2118b6/docs/en/3.4.0/cordova/events/events.resume.md ---------------------------------------------------------------------- diff --git a/docs/en/3.4.0/cordova/events/events.resume.md b/docs/en/3.4.0/cordova/events/events.resume.md new file mode 100644 index 0000000..4e38a7d --- /dev/null +++ b/docs/en/3.4.0/cordova/events/events.resume.md @@ -0,0 +1,114 @@ +--- +license: Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. +--- + +# resume + +The event fires when an application is retrieved from the background. + + document.addEventListener("resume", yourCallbackFunction, false); + +## Details + +The `resume` event fires when the native platform pulls the +application out from the background. + +Applications typically should use `document.addEventListener` to +attach an event listener once the `deviceready` event fires. + +## Supported Platforms + +- Amazon Fire OS +- Android +- BlackBerry 10 +- iOS +- Windows Phone 7 and 8 +- Windows 8 + +## Quick Example + + document.addEventListener("resume", onResume, false); + + function onResume() { + // Handle the resume event + } + +## Full Example + + + + + Resume Example + + + + + + + + +## iOS Quirks + +Any interactive functions called from a `pause` event handler execute +later when the app resumes, as signaled by the `resume` event. These +include alerts, `console.log()`, and any calls from plugins or the +Cordova API, which go through Objective-C. + +- __active__ event + + The iOS-specific `active` event is available as an alternative to +`resume`, and detects when users disable the __Lock__ button to unlock +the device with the app running in the foreground. If the app (and +device) is enabled for multi-tasking, this is paired with a subsequent +`resume` event, but only under iOS 5. In effect, all locked apps in +iOS 5 that have multi-tasking enabled are pushed to the background. +For apps to remain running when locked under iOS 5, disable the app's +multi-tasking by setting [UIApplicationExitsOnSuspend](http://developer.apple.com/library/ios/#documentation/general/Reference/InfoPlistKeyReference/Articles/iPhoneOSKeys.html) +to `YES`. To run when locked on iOS 4, this setting does not matter. + +- __resume__ event + + When called from a `resume` event handler, interactive functions such +as `alert()` need to be wrapped in a `setTimeout()` call with a +timeout value of zero, or else the app hangs. For example: + + document.addEventListener("resume", onResume, false); + function onResume() { + setTimeout(function() { + // TODO: do your thing! + }, 0); + } http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0e2118b6/docs/en/3.4.0/cordova/events/events.searchbutton.md ---------------------------------------------------------------------- diff --git a/docs/en/3.4.0/cordova/events/events.searchbutton.md b/docs/en/3.4.0/cordova/events/events.searchbutton.md new file mode 100644 index 0000000..bdde91e --- /dev/null +++ b/docs/en/3.4.0/cordova/events/events.searchbutton.md @@ -0,0 +1,79 @@ +--- +license: Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. +--- + +# searchbutton + +The event fires when the user presses the search button on Android. + + document.addEventListener("searchbutton", yourCallbackFunction, false); + +## Details + +If you need to override the default search button behavior on Android +you can register an event listener for the 'searchbutton' event. + +Applications typically should use `document.addEventListener` to +attach an event listener once the `deviceready` event fires. + +## Supported Platforms + +- Android + +## Quick Example + + document.addEventListener("searchbutton", onSearchKeyDown, false); + + function onSearchKeyDown() { + // Handle the search button + } + +## Full Example + + + + + Search Button Example + + + + + + + http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0e2118b6/docs/en/3.4.0/cordova/events/events.startcallbutton.md ---------------------------------------------------------------------- diff --git a/docs/en/3.4.0/cordova/events/events.startcallbutton.md b/docs/en/3.4.0/cordova/events/events.startcallbutton.md new file mode 100644 index 0000000..ec6f61f --- /dev/null +++ b/docs/en/3.4.0/cordova/events/events.startcallbutton.md @@ -0,0 +1,79 @@ +--- +license: Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. +--- + +# startcallbutton + +The event fires when the user presses the start call button. + + document.addEventListener("startcallbutton", yourCallbackFunction, false); + +## Details + +If you need to override the default start call behavior you can +register an event listener for the `startcallbutton` event. + +Applications typically should use `document.addEventListener` to +attach an event listener once the `deviceready` event fires. + +## Supported Platforms + +- BlackBerry 10 + +## Quick Example + + document.addEventListener("startcallbutton", onStartCallKeyDown, false); + + function onStartCallKeyDown() { + // Handle the start call button + } + +## Full Example + + + + + Start Call Button Example + + + + + + + http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0e2118b6/docs/en/3.4.0/cordova/events/events.volumedownbutton.md ---------------------------------------------------------------------- diff --git a/docs/en/3.4.0/cordova/events/events.volumedownbutton.md b/docs/en/3.4.0/cordova/events/events.volumedownbutton.md new file mode 100644 index 0000000..fd3ff6c --- /dev/null +++ b/docs/en/3.4.0/cordova/events/events.volumedownbutton.md @@ -0,0 +1,79 @@ +--- +license: Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. +--- + +# volumedownbutton + +The event fires when the user presses the volume down button. + + document.addEventListener("volumedownbutton", yourCallbackFunction, false); + +## Details + +If you need to override the default volume down behavior you can +register an event listener for the `volumedownbutton` event. + +Applications typically should use `document.addEventListener` to +attach an event listener once the `deviceready` event fires. + +## Supported Platforms + +- BlackBerry 10 + +## Quick Example + + document.addEventListener("volumedownbutton", onVolumeDownKeyDown, false); + + function onVolumeDownKeyDown() { + // Handle the volume down button + } + +## Full Example + + + + + Volume Down Button Example + + + + + + + http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0e2118b6/docs/en/3.4.0/cordova/events/events.volumeupbutton.md ---------------------------------------------------------------------- diff --git a/docs/en/3.4.0/cordova/events/events.volumeupbutton.md b/docs/en/3.4.0/cordova/events/events.volumeupbutton.md new file mode 100644 index 0000000..a17e63b --- /dev/null +++ b/docs/en/3.4.0/cordova/events/events.volumeupbutton.md @@ -0,0 +1,79 @@ +--- +license: Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. +--- + +# volumeupbutton + +The event fires when the user presses the volume up button. + + document.addEventListener("volumeupbutton", yourCallbackFunction, false); + +## Details + +If you need to override the default volume up behavior you can +register an event listener for the `volumeupbutton` event. + +Applications typically should use `document.addEventListener` to +attach an event listener once the `deviceready` event fires. + +## Supported Platforms + +- BlackBerry 10 + +## Quick Example + + document.addEventListener("volumeupbutton", onVolumeUpKeyDown, false); + + function onVolumeUpKeyDown() { + // Handle the volume up button + } + +## Full Example + + + + + Volume Up Button Example + + + + + + + http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0e2118b6/docs/en/3.4.0/cordova/plugins/pluginapis.md ---------------------------------------------------------------------- diff --git a/docs/en/3.4.0/cordova/plugins/pluginapis.md b/docs/en/3.4.0/cordova/plugins/pluginapis.md new file mode 100644 index 0000000..2073321 --- /dev/null +++ b/docs/en/3.4.0/cordova/plugins/pluginapis.md @@ -0,0 +1,80 @@ +--- +license: Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. +--- + +# Plugin APIs + +Cordova ships with a minimal set of APIs, and projects add what extra APIs they require through plugins. + +You can search through all existing plugins using the [Plugin Registry](http://plugins.cordova.io/). + +The traditional set of Cordova plugins are as follows: + +- [Battery Status](https://github.com/apache/cordova-plugin-battery-status/blob/dev/doc/index.md) +> Monitor the status of the device's battery. + +- [Camera](https://github.com/apache/cordova-plugin-camera/blob/dev/doc/index.md) +> Capture a photo using the device's camera. + +- [Contacts](https://github.com/apache/cordova-plugin-contacts/blob/dev/doc/index.md) +> Work with the devices contact database. + +- [Device](https://github.com/apache/cordova-plugin-device/blob/dev/doc/index.md) +> Gather device specific information. + +- [Device Motion (Accelerometer)](https://github.com/apache/cordova-plugin-device-motion/blob/dev/doc/index.md) +> Tap into the device's motion sensor. + +- [Device Orientation (Compass)](https://github.com/apache/cordova-plugin-device-orientation/blob/dev/doc/index.md) +> Obtain the direction that the device is pointing. + +- [Dialogs](https://github.com/apache/cordova-plugin-dialogs/blob/dev/doc/index.md) +> Visual device notifications. + +- [FileSystem](https://github.com/apache/cordova-plugin-file/blob/dev/doc/index.md) +> Hook into native file system through JavaScript. + +- [File Transfer](https://github.com/apache/cordova-plugin-file-transfer/blob/dev/doc/index.md) +> Hook into native file system through JavaScript. + +- [Geolocation](https://github.com/apache/cordova-plugin-geolocation/blob/dev/doc/index.md) +> Make your application location aware. + +- [Globalization](https://github.com/apache/cordova-plugin-globalization/blob/dev/doc/index.md) +> Enable representation of objects specific to a locale. + +- [InAppBrowser](https://github.com/apache/cordova-plugin-inappbrowser/blob/dev/doc/index.md) +> Launch URLs in another in-app browser instance. + +- [Media](https://github.com/apache/cordova-plugin-media/blob/dev/doc/index.md) +> Record and play back audio files. + +- [Media Capture](https://github.com/apache/cordova-plugin-media-capture/blob/dev/doc/index.md) +> Capture media files using device's media capture applications. + +- [Network Information (Connection)](https://github.com/apache/cordova-plugin-network-information/blob/dev/doc/index.md) +> Quickly check the network state, and cellular network information. + +- [Splashscreen](https://github.com/apache/cordova-plugin-splashscreen/blob/dev/doc/index.md) +> Show and hide the applications splash screen. + +- [Vibration](https://github.com/apache/cordova-plugin-vibration/blob/dev/doc/index.md) +> An API to vibrate the device. + +Non-English translations of these plugin docs can be found by looking at older versions of the Cordova documentation. Use the drop-down menu at the very top-right of this site to switch versions. + http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0e2118b6/docs/en/3.4.0/cordova/storage/storage.md ---------------------------------------------------------------------- diff --git a/docs/en/3.4.0/cordova/storage/storage.md b/docs/en/3.4.0/cordova/storage/storage.md new file mode 100644 index 0000000..dac5c71 --- /dev/null +++ b/docs/en/3.4.0/cordova/storage/storage.md @@ -0,0 +1,70 @@ +--- +license: Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. +--- + +# Storage + +> An overview of storage options for Cordova. + +Several storage APIs are available for Cordova applications. +See +[html5rocks](http://www.html5rocks.com/en/features/storage). +for a more complete overview and examples. + +## LocalStorage + +Also known as _web storage_, _simple storage_, or by its alternate +_session storage_ interface, this API provides synchronous key/value +pair storage, and is available in underlying WebView implementations. +Refer to [the W3C spec](http://www.w3.org/TR/webstorage/) for details. + +__Windows Phone 7 Quirk__: Dot notation is _not_ available, so be sure +to use `setItem` or `getItem` rather than access keys directly from +the storage object, as in `window.localStorage.someKey`. + +## WebSQL + +This API is available in the underlying WebView. +The [Web SQL Database Specification](http://dev.w3.org/html5/webdatabase/) +offers more full-featured database tables accessed via SQL queries. + +The following platforms support WebSQL: + +- Android +- BlackBerry 10 +- iOS +- Tizen + +## IndexedDB + +This API is available in the underlying WebView. +[Indexed DB](http://www.w3.org/TR/IndexedDB/) offers more features +than LocalStorage but fewer than WebSQL. + +The following platforms support IndexedDB: + +- Windows Phone 8 +- BlackBerry 10 + +## Plugin-Based Options + +In addition to the storage APIs listed above, the +[File API](https://github.com/apache/cordova-plugin-file/blob/master/doc/index.md) +allows you to cache data on the local file system. Other +[Cordova plugins](http://plugins.cordova.io/) provide similar storage options. + http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0e2118b6/docs/en/3.4.0/guide/appdev/privacy/index.md ---------------------------------------------------------------------- diff --git a/docs/en/3.4.0/guide/appdev/privacy/index.md b/docs/en/3.4.0/guide/appdev/privacy/index.md new file mode 100644 index 0000000..601ee38 --- /dev/null +++ b/docs/en/3.4.0/guide/appdev/privacy/index.md @@ -0,0 +1,117 @@ +--- +license: Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. +--- + +# Privacy Guide + +Mobile privacy is a critical issue that every app developer must +address. Your users expect that their private information will be +collected and treated appropriately by your app. Also, there are an +increasing number of jurisdictions that now have legal requirements +regarding mobile privacy practices. + +This guide on mobile app privacy should be considered a _primer_ +addressing some the most significant issues. It outlines some broadly +accepted best practices and provides references to other more detailed +guides and references. + +* __Privacy Policy__: You app should include a privacy policy that + addresses topics such as what kind of information your app collects + from or about your users, how that information is used, with whom it + is shared, and how users can make privacy-related choices within the + app. To aid understanding, you should use plain language and avoid + technical jargon. You should make your privacy policy available for + users to review prior to download, such as in the app description in + the app marketplace. In addition, you should make your privacy + policy available within the app itself. The limited size of mobile + device displays creates challenges for displaying privacy policies + to users. Consider developing a _short form_ of the policy that + includes the most important information, and then provide a link to + the "long form" policy for those interested in more details. Several + groups are attempting to develop icon-based standards for + communicating privacy practices, which you may want to consider once + these standards mature. + +* __Collection of sensitive information__: An app's collection of + sensitive personal information raises important privacy concerns. + Examples of sensitive personal information include financial + information, health information, and information from or about + children. It also includes information gathered from certain sensors + and databases typically found on mobile devices and tablets, such as + geolocation information, contacts/phonebook, microphone/camera, and + stored pictures/videos. See the following documentation pages for + more information: [camera](cordova_camera_camera.md.html), + [capture](cordova_media_capture_capture.md.html), + [contacts](cordova_contacts_contacts.md.html), and + [geolocation](cordova_geolocation_geolocation.md.html). Generally, + you should obtain a user's express permission before collecting + sensitive information and, if possible, provide a control mechanism + that allows a user to easily change permissions. App operating + systems can help in some instances by presenting just-in-time dialog + boxes that ask for the user's permission before collection. In these + cases, be sure to take advantage of any opportunity to customize the + dialog box text to clarify how the app uses and, if applicable, + shares such information. + +* __Avoiding user surprise__: If your app collects or uses information + in a way that may be surprising to users in light of the primary + purpose of your app (for example, a music player that accesses + stored pictures), you should take similar steps as with the + collection of sensitive personal information. That is, you should + strongly consider the use of just-in-time dialog boxes to inform the + user about the collection or use of that information and, if + appropriate, provide a corresponding privacy control. + +* __Third party data collection or sharing__: If you app collects + information that is provided to another company--such as a social + networking platform or an ad network (for example, if your app + displays advertising)--you should inform your users of that + collection and sharing. At a minimum, your privacy policy should + describe the information collection and sharing and, if appropriate, + offer your users the ability to control or opt-out of such + collection or sharing. + +* __Collection limitation and security__: Your users entrust your app + with their information and they expect that you will take + appropriate security precautions to protect it. One of the best ways + to avoid security compromises of personal information is not to + collect the information in the first place unless your app has a + specific and legitimate business reason for the collection. For + information that does need to be collected, ensure that you provide + appropriate security controls to protect that information, whether + it is stored on the device or on your backend servers. You should + also develop an appropriate data retention policy that is + implemented within the app and on your backend servers. + +Following are some additional helpful mobile privacy guides for developers: + +* California Attorney General, [Privacy on the Go: Recommendations for the Mobile Ecosystem][1] + +* Center for Democracy & Technology, Future of Privacy Forum, [Best Practices for Mobile App Developers][2] + +* CTIA-The Wireless Association, [Best Practices and Guidelines for Location Based Services][3] + +* Federal Trade Commission, [Mobile Privacy Disclosures: Building Trust Through Transparency][4] + +* Future of Privacy Forum, [Application Privacy][5] Website + +[1]: http://oag.ca.gov/sites/all/files/pdfs/privacy/privacy_on_the_go.pdf +[2]: http://www.futureofprivacy.org/wp-content/uploads/Best-Practices-for-Mobile-App-Developers_Final.pdf +[3]: http://www.ctia.org/business_resources/wic/index.cfm/AID/11300 +[4]: http://www.ftc.gov/os/2013/02/130201mobileprivacyreport.pdf +[5]: http://www.applicationprivacy.org http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0e2118b6/docs/en/3.4.0/guide/appdev/whitelist/index.md ---------------------------------------------------------------------- diff --git a/docs/en/3.4.0/guide/appdev/whitelist/index.md b/docs/en/3.4.0/guide/appdev/whitelist/index.md new file mode 100644 index 0000000..4e5e484 --- /dev/null +++ b/docs/en/3.4.0/guide/appdev/whitelist/index.md @@ -0,0 +1,168 @@ +--- +license: Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. +--- + +# Whitelist Guide + +Domain whitelisting is a security model that controls access to +external domains over which you application has no control. Cordova's +default security policy allows access to any site. Before moving your +application to production, you should formulate a whitelist and allow +access to specific network domains and subdomains. + +Cordova adheres to the [W3C Widget Access][1] specification, which +relies on the `` element within the app's `config.xml` file to +enable network access to specific domains. For projects that rely on +the CLI workflow described in The Command-Line Interface, this file is +located in the project's top-level directory. Otherwise for +platform-specific development paths, locations are listed in the +sections below. (See the various Platform Guides for more information +on each platform.) + +The following examples demonstrate whitelist syntax: + +* Access to [google.com][2]: + + + +* Access to the secure [google.com][3] (`https://`): + + + +* Access to the subdomain [maps.google.com][4]: + + + +* Access to all the subdomains on [google.com][2], for example + [mail.google.com][5] and [docs.google.com][6]: + + + +* Access to _all_ domains, for example, [google.com][2] and + [developer.mozilla.org][7]: + + + + This is the default value for newly created CLI projects. + +## Amazon Fire OS Whitelisting + +Platform-specific whitelisting rules are found in +`res/xml/config.xml`. + +## Android Whitelisting + +Platform-specific whitelisting rules are found in +`res/xml/config.xml`. + +__NOTE__: On Android 2.3 and before, domain whitelisting only works +for `href` hyperlinks, not referenced resources such as images and +scripts. Take steps to avoid scripts from being injected into the +application. + +Navigating to non-whitelisted domains via `href` hyperlink causes the +page to open in the default browser rather than within the +application. (Compare this to iOS's behavior noted below.) + +## iOS Whitelisting + +The platform's whitelisting rules are found in the named application +directory's `config.xml` file. + +Origins specified without a protocol, such as `www.apache.org` rather +than `http://www.apache.org`, default to all of the `http`, `https`, +`ftp`, and `ftps` schemes. + +Wildcards on the iOS platform are more flexible than in the [W3C +Widget Access][1] specification. For example, the following accesses +all subdomains and top-level domains such as `.com` and `.net`: + + + +Unlike the Android platform noted above, navigating to non-whitelisted +domains via `href` hyperlink on iOS prevents the page from opening at +all. + +## BlackBerry 10 Whitelisting + +The whitelisting rules are found in `www/config.xml`. + +BlackBerry 10's use of wildcards differs from other platforms in two +ways: + +* Any content accessed by `XMLHttpRequest` must be declared + explicitly. Setting `origin="*"` does not work in this case. + Alternatively, all web security may be disabled using the + `WebSecurity` preference described in BlackBerry Configuration: + + + +* As an alternative to setting `*.domain`, set an additional + `subdomains` attribute to `true`. It should be set to `false` by + default. For example, the following allows access to `google.com`, + `maps.google.com`, and `docs.google.com`: + + + + The following narrows access to `google.com`: + + + + Specify access to all domains, including the local `file://` + protocol: + + + +(For more information on support, see BlackBerry's documentation on the +[access element][8].) + +## iOS Changes in 3.1.0 + +Prior to version 3.1.0, Cordova-iOS included some non-standard extensions to the domain whitelisting scheme supported by other Cordova platforms. As of 3.1.0, the iOS whitelist now conforms to the resource whitelist syntax described at the top of this document. If you upgrade from pre-3.1.0, and you were using these extensions, you may have to change your `config.xml` file in order to continue whitelisting the same set of resources as before. + +Specifically, these patterns need to be updated: + +- `apache.org` (no protocol): This would previously match `http`, `https`, `ftp`, and `ftps` protocols. Change to "`*://apache.org/*`" to include all protocols, or include a line for each protocol you need to support. + +- `http://apache.*` (wildcard at end of domain): This would previously match all top-level-domains, including all possible two-letter TLDs (but not useful domains like .co.uk). Include a line for each TLD which you actually control, and need to whitelist. + +- `h*t*://ap*he.o*g` (wildcards for random missing letters): These are no longer supported; change to include a line for each domain and protocol that you actually need to whitelist. + +## Windows Phone Whitelisting + +The whitelisting rules for Windows Phone 7 and 8 are found in the +app's `config.xml` file. + +## Tizen Whitelisting + +Whitelisting rules are found in the app's `config.xml` file. The +platform relies on the same `subdomains` attribute as the BlackBerry +platform. +(For more information on support, see Tizen's documentation on the +[access element][9].) + +[1]: http://www.w3.org/TR/widgets-access/ +[2]: http://google.com +[3]: https://google.com +[4]: http://maps.google.com +[5]: http://mail.google.com +[6]: http://docs.google.com +[7]: http://developer.mozilla.org +[8]: https://developer.blackberry.com/html5/documentation/ww_developing/Access_element_834677_11.html +[9]: https://developer.tizen.org/help/index.jsp?topic=%2Forg.tizen.web.appprogramming%2Fhtml%2Fide_sdk_tools%2Fconfig_editor_w3celements.htm +