Skip to content

doc: update 12.x 2025.01 snapshot #1447

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
erisu merged 2 commits into from
Nov 25, 2025
Merged

doc: update 12.x 2025.01 snapshot #1447

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
aa0dc7e
doc: update 12.x-2025.01-snapshot
erisu Nov 24, 2025
27051b7
doc(ios): update 12.x-2025.01-snapshot
erisu Nov 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
91 changes: 49 additions & 42 deletions www/docs/en/12.x-2025.01/config_ref/images.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,19 +45,11 @@ width | *Optional* <br/> Icon width in pixels
height | *Optional* <br/> Icon height in pixels
target | *Optional* <br/> {% cdv_platform electron %} <br/> Set target to supply unique icons for `app` and `installer`

The following configuration can be used to define a single default icon
which will be used for all platforms.
```xml
<icon src="res/icon.png" />
```
For each platform, you can also define a pixel-perfect icon set to fit
different screen resolutions.

## Android

Instead of using a single image for an icon, you can use two images (background and foreground) to create an **Adaptive Icon**. To use Adaptive Icons in Cordova, at minimum **Cordova CLI** 9.0.0 and **Cordova-Android** 8.0.0 is required.
Android's **Adaptive Icons** feature enables you to create separate foreground and background layers for your App Icons. To use Adaptive Icons in Cordova, you need at least **Cordova CLI** 9.0.0 and **Cordova-Android** 8.0.0.

Android 13 has introduced themed icons which are monochrome images appended to the existing **Adaptive Icons**. To use Themed Icon in Cordova, at minimum **Cordova CLI** 12.0.0 and **Cordova-Android** 12.0.0 is required.
With Android 13, Google introduced **Themed Icons**, which are monochrome variations of **Adaptive Icons** that integrate seamlessly with the system's color scheme. To use **Themed Icons** in Cordova, you'll need at least **Cordova CLI** 12.0.0 and **Cordova-Android** 12.0.0.

Attributes | Description
--------------|--------------------------------------------------------------------------------
Expand All @@ -71,6 +63,7 @@ density | *Required* <br/> Specified icon density
To use the adaptive icons the `background`, `foreground` and optionally `monochrome` attributes must be defined in place of the `src` attribute. The `src` attribute is not used for adaptive icons.

#### Adaptive Icon with Images:

```xml
<platform name="android">
<icon monochrome="res/icon/android/ldpi-monochrome.png" background="res/icon/android/ldpi-background.png" density="ldpi" foreground="res/icon/android/ldpi-foreground.png" />
Expand All @@ -85,6 +78,7 @@ To use the adaptive icons the `background`, `foreground` and optionally `monochr
**Note:** In this example, the foreground image will also be used as the fallback icon for Android devices that do not support the adaptive icons. The fallback icon can be overridden by setting the src attribute.

#### Adaptive Icon with Vectors:

```xml
<platform name="android">
<icon monochrome="res/icon/android/ldpi-monochrome.png" background="res/icon/android/ldpi-background.xml" density="ldpi" foreground="res/icon/android/ldpi-foreground.xml" src="res/android/ldpi.png" />
Expand All @@ -99,6 +93,7 @@ To use the adaptive icons the `background`, `foreground` and optionally `monochr
**Note:** In this example, the src attribute must be defined when then foreground attribute is defined with a vector or color.

#### Adaptive Icon with Colors:

Create a `res/values/colors.xml` resource file in your project directory to store the app's color definitions.
```xml
<?xml version="1.0" encoding="utf-8"?>
Expand Down Expand Up @@ -143,7 +138,8 @@ In the `config.xml`, we will add `resource-file` to copy the `colors.xml` into t
</platform>
```

### See Also
**See Also:**

- [Android icon guide](https://developer.android.com/guide/practices/ui_guidelines/icon_design_adaptive)
- [Android Adaptive icons - User theming](https://developer.android.com/develop/ui/views/launch/icon_design_adaptive#user-theming)
- [Android - Supporting multiple screens](https://developer.android.com/guide/practices/screens_support.html)
Expand All @@ -152,43 +148,54 @@ In the `config.xml`, we will add `resource-file` to copy the `colors.xml` into t
Icons are not applicable to the Browser platform.

## iOS

```xml
<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" />
<!-- Spotlight Icon -->
<icon src="res/ios/icon-40.png" width="40" height="40" />
<!-- Notifications on iPhone, iPad Pro, iPad, iPad mini -->
<icon src="res/ios/icon-38@2x.png" width="76" height="76" />
<icon src="res/ios/icon-38@3x.png" width="114" height="114" />

<!-- Settings on iPhone, iPad Pro, iPad, iPad mini -->
<icon src="res/ios/icon-29@1x.png" width="29" height="29" />
<icon src="res/ios/icon-29@2x.png" width="58" height="58" />
<icon src="res/ios/icon-29@3x.png" width="87" height="87" />

<!-- Spotlight on iPhone, iPad Pro, iPad, iPad mini -->
<icon src="res/ios/icon-40@1x.png" width="40" height="40" />
<icon src="res/ios/icon-40@2x.png" width="80" height="80" />
<!-- iOS 6.1 -->
<!-- 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" />
<!-- iPad Pro -->
<icon src="res/ios/icon-167.png" width="167" height="167" />
<!-- 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" />
<icon src="res/ios/icon-small@3x.png" width="87" height="87" />
<!-- 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" />
<!-- iTunes Marketing Image -->

<!-- Home Screen on iPad, iPad mini -->
<icon src="res/ios/icon-76@2x.png" width="152" height="152" />

<!-- Home Screen on iPad Pro -->
<icon src="res/ios/icon-83.5@2x.png" width="167" height="167" />

<!-- Home Screen on iPhone -->
<icon src="res/ios/icon-60@1x.png" width="60" height="60" />
<icon src="res/ios/icon-60@2x.png" width="120" height="120" />
<icon src="res/ios/icon-60@3x.png" width="180" height="180" />

<!-- macOS app icons -->
<icon src="res/ios/icon-16.png" width="16" height="16" />
<icon src="res/ios/icon-32.png" width="32" height="32" />
<icon src="res/ios/icon-64.png" width="64" height="64" />
<icon src="res/ios/icon-128.png" width="128" height="128" />
<icon src="res/ios/icon-256.png" width="256" height="256" />
<icon src="res/ios/icon-512.png" width="512" height="512" />

<!-- App Store Icon and another macOS app icons -->
<icon src="res/ios/icon-1024.png" width="1024" height="1024" />
</platform>
```
### See Also
- [App Icons on iPad and iPhone](https://developer.apple.com/library/content/qa/qa1686/_index.html)

**Notes:**

- Alpha channel is not supported for any iOS icons.

**References:**

- [Apple Developer - Configuring your app icon](https://developer.apple.com/documentation/xcode/configuring-your-app-icon/)
- [Apple Developer - Human Interface Guidelines > App icons](https://developer.apple.com/design/human-interface-guidelines/app-icons)

[splashscreen_plugin]: ../reference/cordova-plugin-splashscreen/

Expand Down
2 changes: 2 additions & 0 deletions www/docs/en/12.x-2025.01/config_ref/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -325,12 +325,14 @@ android-compileSdkVersion<br/>{% cdv_vartype number %} {% cdv_platform android %
android-buildToolsVersion<br/>{% cdv_vartype semver %} {% cdv_platform android %} | *Default: [Dependent on cordova-android Version][android-api-level-support]* <br/> Expects a full version string eg. "32.0.0". Changing this may also requires changing the PATH environment variable to find the proper build tools.<br/><br/>This preference is primarily for cordova development, for testing upcoming versions of the Android SDK. Changing this has a high risk of breaking builds as newer build tools frequently introduce breaking changes.
GradleVersion<br/>{% cdv_vartype string %} {% cdv_platform android %} | *Default: [Dependent on cordova-android Version][android-api-level-support]* <br/> Sets the gradle wrapper version to use.<br/> <br/>This preference is primarily for cordova development, for testing upcoming versions of the Android SDK. Changing this has a high risk of breaking builds as newer build tools frequently introduce breaking changes.
AndroidGradlePluginVersion<br/>{% cdv_vartype semver %} {% cdv_platform android %} | *Default: [Dependent on cordova-android Version][android-api-level-support]* <br/> Sets the Android Gradle Plugin version to use.<br/> <br/>This preference is primarily for cordova development, for testing upcoming versions of the Android SDK. Changing this has a high risk of breaking builds as newer build tools frequently introduce breaking changes.
AndroidShowDeprecations<br />{% cdv_vartype boolean %} {% cdv_platform android %} | *Default: false* <br />Prints deprecation warnings for the android platform in the build output.<br /><br />This preference is primarily intended for cordova core and plugin development.
AndroidXAppCompatVersion<br/>{% cdv_vartype semver %} {% cdv_platform android %} | *Default: [Dependent on cordova-android Version][android-api-level-support]* <br/> Overrides Android App Compat library version.
AndroidXWebKitVersion<br/>{% cdv_vartype semver %} {% cdv_platform android %} | *Default: [Dependent on cordova-android Version][android-api-level-support]* <br/>Overrides Android WebKit library version.
AppendUserAgent<br/>{% cdv_vartype string %} {% cdv_platform android %} {% cdv_platform ios %} | If set, the value will append to the end of old UserAgent of webview. When using with OverrideUserAgent, this value will be ignored.
AutoHideSplashScreen<br/> {% cdv_vartype boolean %} {% cdv_platform android %} {% cdv_platform ios %} | *Default: true* <br/> Indicates whether to hide splash screen automatically or not. The splash screen is hidden after the amount of time specified in the `SplashScreenDelay` preference.
BackgroundColor<br/>{% cdv_vartype string %} {% cdv_platform android %} {% cdv_platform ios %} | Sets 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.
CordovaWebViewEngine<br/>{% cdv_vartype string %} {% cdv_platform ios %} | *Default: CDVWebViewEngine* <br/> This sets the WebView engine plugin to be used to render the host app. The plugin must conform to the CDVWebViewEngineProtocol protocol. The 'value' here should match the 'feature' name of the WebView engine plugin that is installed. This preference usually would be set by the WebView engine plugin that is installed, automatically.
CrashRecoveryBehavior<br/>{% cdv_vartype string %} {% cdv_platform ios %} | *Default: refresh* <br/> Allowed values: refresh, reload <br/> Specifies the crash recovery behavior for the iOS web view. The `reload` option will cause the web view to reload the starting URL for the app, whereas `refresh` will attempt to restore the current URL state.
DefaultVolumeStream<br/>{% cdv_vartype string %} {% cdv_platform android %} | *Default: default* <br/> Added in cordova-android 3.7.0, This preference sets which volume the hardware volume buttons link to. By default this is "call" for phones and "media" for tablets. Set this to "media" to have your app's volume buttons always change the media volume. Note that when using Cordova's media plugin, the volume buttons will dynamically change to controlling the media volume when any Media objects are active.
DisallowOverscroll<br/>{% cdv_vartype boolean %} {% cdv_platform ios %} {% cdv_platform android %} | *Default: false* <br/> Set to **true** if you don't want the interface to display any feedback when users scroll past the beginning or end of content. 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. <br/>
EnableViewportScale<br/>{% cdv_vartype boolean %} {% cdv_platform ios %} | *Default: false* <br/> Set to true to allow a viewport meta tag to either disable or restrict the range of user scaling, which is enabled by default. Place a viewport such as the following in the HTML to disable scaling and fit content flexibly within the rendering WebView: <br/> ```<meta name='viewport' content='width=device-width, initial-scale=1, user-scalable=no' />```
Expand Down
58 changes: 55 additions & 3 deletions www/docs/en/12.x-2025.01/guide/appdev/allowlist/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,7 @@ By default navigations are only allowed to `file://` URLs. To allow others URLs,
to the host, or as a suffix to the path -->
<allow-navigation href="*://*.example.com/*" />

<!--
<!--
A wildcard can be used to allow the entire network, over HTTP and HTTPS.
This is *NOT RECOMMENDED*
-->
Expand Down Expand Up @@ -141,10 +141,54 @@ Note: `allow-navigation` takes precedence over `allow-intent`. Allowing navigati

## Content Security Policy (CSP)

Controls which network requests (images, XHRs, etc) are allowed to be made (via webview directly).
The [**Content Security Policy (CSP)**](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) `<meta>` tag is a very powerful mechanism that allows you to control trusted sources of content. You can restrict various content types and domains from which content can be loaded from. Unsafe and risky HTML and JavaScript can also be disabled to further increase the security of your app.

The CSP `<meta>` tag should be placed in your app's index.html file.

On Android and iOS, the network request allow list (see above) is not able to filter all types of requests (e.g. `<video>` & WebSockets are not blocked). So, in addition to the allow list, you should use a [Content Security Policy](http://content-security-policy.com/) `<meta>` tag on all of your pages.

> **Note**: If your app has multiple HTML files and navigates between them using the browser's navigation features, you should include the CSP in each file. If your app is a single-page application, you only need to include the CSP on `index.html`.

### Cordova's Default Template Content Security Policy

The CSP that Cordova's default template uses looks like this (indented for clarity):

```html
<meta http-equiv="Content-Security-Policy"
content="default-src 'self' data: https://ssl.gstatic.com 'unsafe-eval';
style-src 'self' 'unsafe-inline';
media-src *;
img-src 'self' data: content:;">
```

The above snippet enforces the following:

**Default Source (`default-src`):**

As a fallback, all other network requests are restricted to:

* The same origin as the app itself (`'self'`).
* Resources loaded via `data:` URIs.
* Resources from the specified external domain `https://ssl.gstatic.com`.
* JavaScript methods such as `eval()` (and similar) are permitted with `'unsafe-eval'`.

**Style Source (`style-src`):**

* Styles can only be loaded from the same origin (`'self'`).
* Inline styles (`'unsafe-inline'`) are also allowed, meaning styles can be directly applied using the `style` attribute on elements or within `<style>` tags.

**Media Source (`media-src`):**

* Media can be loaded from any source.

**Image Source (`img-src`):**

* Images can only be loaded from the same origin (`'self'`).
* Allows loading images from `data:` URIs.
* Allows loading images from `content:` URIs, typically used within the Android ecosystem.

### Example Content Security Policy Declarations

Here are some example CSP declarations for your `.html` pages:

```html
Expand All @@ -159,7 +203,7 @@ Here are some example CSP declarations for your `.html` pages:
<!-- Allow everything but only from the same origin and foo.com -->
<meta http-equiv="Content-Security-Policy" content="default-src 'self' foo.com">

<!-- This policy allows everything (eg CSS, AJAX, object, frame, media, etc) except that
<!-- This policy allows everything (eg CSS, AJAX, object, frame, media, etc) except that
* CSS only from the same origin and inline styles,
* scripts only from the same origin and inline styles, and eval()
-->
Expand All @@ -172,6 +216,14 @@ Here are some example CSP declarations for your `.html` pages:
<meta http-equiv="Content-Security-Policy" content="default-src 'self'; frame-src 'self' https://cordova.apache.org">
```

You should fully understand the CSP tag and the various directives that can be specified. More documentation is available at [Content Security Policy](https://web.dev/articles/csp) (via Google Developers) and Mozilla's [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) article.

> **Tip**: If you're using web sockets, include `ws:` (`wss:` if using SSL) in the `connect-src` directive.

### Debugging Content Security Policy

When adding a CSP to your app, it's likely you'll encounter some issues. Fortunately, both Google Chrome's Developer Tools and Safari's Web Inspector make it very clear when a CSP violation occurs. Watch the console for any violation messages, which are typically quite detailed, specifying exactly which resource was blocked and why. Address each violation as they appear to ensure your CSP is properly configured.

## Other Notes

[Application Transport Security (ATS)](https://developer.apple.com/library/prerelease/ios/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html#//apple_ref/doc/uid/TP40009251-SW33) is new in iOS 9 (Xcode 7). This new feature acts as an allow list for your app. Cordova CLI will automatically convert the `<access>` and `<allow-navigation>` tags to the appropriate ATS directives.
Expand Down
Loading