cordova-plugin-windows-webview

A webview implementation for the 'windows' platform in cordova. With this plugin you can load an external site and make use of the cordova functionality.

• Installation
• Server configuration
  • Plugin configuration
    • Add plugins
    • Exceptions
      • cordova-plugin-file
• Client configuration
• Functions
  • navigate
  • goBack
  • interceptBackButton
  • onNavigation
  • handlePermissionRequest
  • getPermissionRequests
  • onPermissionRequested
  • offPermissionRequested
• Classes
  • WWPermissionRequest
• Supported platforms
• Credits

Installation

cordova plugin add cordova-plugin-windows-webview

Server configuration

Firstly you will need to copy the cordova.js, cordova_plugins.js and the plugins directory from the windows platform to your server. After that you will need to copy the files, located in the \server directory of this plugin, to the same location as you have copied the cordova.js file.

The order in which to include the cordova files is as follows:

1. cordova-windows-native-override.js (This file overrides any references in cordova.js to native Windows functions)
2. cordova.js
3. (Optional) cordova_plugins.js (This file should automatically be included by cordova.js, but can be added manually)

Plugin configuration

In the cordova_plugins.js you will need to add the WindowsWebviewExec.js as a plugin. Important! This needs to be added to the top of the list.

{
	"file": "plugins/cordova-plugin-windows-webview/www/WindowsWebviewExec.js",
	"id": "cordova-plugin-windows-webview.exec",
	"clobbers": [
		"cordova.exec",
		'Cordova.exec'
	]
},

Add plugins

To use any of the plugins you downloaded or created, they need to be present on the server and be included in the cordova_plugins.js file. You should copy the plugin files from the cordova generated project and put them in the same directory structure and relative to the location of your cordova_plugins.js file.

Note: Some plugins will not automatically work, including original cordova ones. Report any issues you might find.

For example in the case of the device plugin it would look like this:

www/
└── js/
    ├── cordova.js
    ├── cordova_plugins.js
    └── plugins/
        └── cordova-plugin-device/
            └── www/
                └── device.js

And your cordova_plugins.js file would include this:

{
    "file": "plugins/cordova-plugin-device/www/device.js",
    "id": "cordova-plugin-device.device",
    "pluginId": "cordova-plugin-device",
    "clobbers": [
        "device"
    ]
},

To make sure you are using the correct plugin file, open it and confirm that the file begins with cordova.define. In the case of the device plugin it would look similar to this:

cordova.define("cordova-plugin-device.device", function (require, exports, module) {

Important!

You should remove all references to proxy files. For example for the device plugin you can remove this:

{
    "file": "plugins/cordova-plugin-device/src/windows/DeviceProxy.js",
    "id": "cordova-plugin-device.DeviceProxy",
    "pluginId": "cordova-plugin-device",
    "merges": [
        ""
    ]
}

You can also remove the actual proxy file located in the plugins directory. In the case of the device plugin you can remove this file:

plugins/cordova-plugin-device/src/windows/DeviceProxy.js

Exceptions

For the following plugins extra entries in the cordova_plugins.js are required, they need to be added underneath the WindowsWebviewExec.js entry.

Note: Only add these if you use the respective plugin

cordova-plugin-file

Important!

You need to exclude the original cordova-plugin-file.fileSystems plugin entry and include the original cordova-plugin-file.FileSystem plugin entry after the entries below.

{
	"file": "plugins/cordova-plugin-windows-webview/www/cordova-plugin-file/fileSystems.js",
	"id": "cordova-plugin-file.fileSystems",
	"pluginId": "cordova-plugin-windows-webview",
	"runs": true
},
{
	"file": "plugins/cordova-plugin-windows-webview/www/cordova-plugin-file/FileSystem.js",
	"id": "cordova-plugin-windows-webview.FileSystem",
	"pluginId": "cordova-plugin-windows-webview",
	"runs": true
},

Client configuration

Important!

The website you want to navigate to and use cordova with must be included in the cordova white-list like so:

<access origin="https://*.google.com/*" subdomains="true" />

It also has to use a secure origin (https://) Your website will not be able to communicate with the native cordova otherwise.

You will receive a warning like this if it is not included in the white-list:

Unable to receive a ScriptNotify event from: 'https://mywebsite.com'. The website attempted to send a ScriptNotify event to the app from a WebView URI that is not included in the ApplicationContentUriRules ...

When developing and using a test server, you will have to create a self-signed certificate and include it manually in the cordova generated Visual Studio projects' .appxmanifest files.

<Extensions>
<Extension Category="windows.certificates">
  <Certificates>
    <Certificate StoreName="TrustedPeople" Content="www\certificates\mycertificate.cer" />
    <SelectionCriteria AutoSelect="true" />
  </Certificates>
</Extension>
</Extensions>

If you want the webview to immediately navigate to your website add the following to the config.xml of your project:

<windows-webview>
  <url>https://mywebsite.com</url>
  <http-method>POST</http-method>
  <headers>
    <header name="cache-control" value="no-store" />
  </headers>
  <refresh>false</refresh>
  <fingerprint>2B 24 1B E0 D0 8C A6 41 68 C2 BB E3 60 0A DF 55 1A FC A8 45</fingerprint>
  <max-connection-attempts>3</max-connection-attempts>
  <preference name="interceptbackbutton" value="false"/>
</windows-webview>

• url: The url to navigate to

• http-method: The Http method with which to perform request

• header: A header to add to the request. You can add as many request headers as you like. To add multiple values to one header, add a header node with the same name and a different value.

• refresh: {boolean} Indicates the webview will be refreshed, clearing the cache, before navigating to the provided url. Defaults to false.

• fingerprint: The SHA fingerprint used to check the validity of the SSL certificate of the url. Used to prevent 'Man in the Middle' attacks. For more information refer to: SSLCertificateChecker-PhoneGap-Plugin Defaults to null. No validation is performed.

• max-connection-attempts: The maximum number of connection attempts made checking the validity of the SSL certificate before failing. Defaults to 1. Only 1 attempt is made.

• preferences:

  • interceptbackbutton: {boolean} Indicates the back button press should be intercepted. Set this to true if you want to listen for the 'backbutton' event. Defaults to false.

Events

webviewready

Before calling any of the functions below you will want to wait until the webview is ready like so:

document.addEventListener('webviewready', function(){
    // Execute your function
});

Functions

cordova.plugins.WindowsWebview.navigate

Navigates the webview to the specified url.

cordova.plugins.WindowsWebview.navigate(url, httpMethod, headers, refresh, fingerprint, maxConnectionAttempts, success, fail);

• url: {string} The url to navigate to

• http-method: {string} The Http method with which to perform request

• headers: {Array} Optional. The headers to add to the request.

  The array should include objects with the following properties:

  • name: Name of the header (ex. Cache-Control)

  • value: Value to append to the header (ex. no-cache)}

  Note: To add multiple values to one header, add a header object with the same name and a different value to the array.

• refresh: {boolean: false} Optional. Indicates the webview will be refreshed, clearing the cache, before navigating to the provided url.

• fingerprint: {string} Optional. The SHA fingerprint used to check the validity of the SSL certificate of the url. Used to prevent 'Man in the Middle' attacks. For more information refer to: SSLCertificateChecker-PhoneGap-Plugin

• max-connection-attempts: {number: 1} Optional. The maximum number of connection attempts made checking the validity of the SSL certificate before failing.

• success: {Function} Optional. The success callback, called when the webview has navigated successfully. Only useful in native scripts.

• fail: {Function(message)} Optional. The fail callback, called when the webview has failed to navigate or when using the fingerprint option and validation fails. Only useful in native scripts.

cordova.plugins.WindowsWebview.goBack

Traverses backward once in the navigation stack of the webview if possible.

cordova.plugins.WindowsWebview.goBack();

cordova.plugins.WindowsWebview.interceptBackButton

Indicates whether or not the back button press should be intercepted

cordova.plugins.WindowsWebview.interceptBackButton(intercept);

• intercept: {boolean: false} Set this to true if you want to listen for the 'backbutton' event. Defaults to false.

cordova.plugins.WindowsWebview.onNavigation

Executes the provided callbacks when the webview navigates successfully or fails. Note: This is only useful in native scripts, scripts executed in the webview will never be able to listen to webview events.

cordova.plugins.WindowsWebview.onNavigation(success, fail, once);

• success: {Function} Optional. The callback function to execute when the webview successfully navigated.

• fail: {Function} Optional. The callback function to execute when the webview fails to navigate for whatever reason.

• once: {boolean} Optional. Indicates the provided callback functions should only be executed once.

cordova.plugins.WindowsWebview.handlePermissionRequest

Handles the permission request with the provided id by allowing or denying it depending on the provided 'allow' argument.

cordova.plugins.WindowsWebview.handlePermissionRequest(id, allow, success, fail);

• id: {number} The id of the permission request to handle. For possible values see: WebViewPermissionType enumeration

• allow: {boolean} Indicates the permission request should be granted. Set to false to deny the permission request.

• success: {Function} Optional. The callback function to execute when the permission with the provided is among the unhandled requests.

• fail: {Function} Optional. The callback function to execute when the permission with the provided is not among the unhandled requests.

cordova.plugins.WindowsWebview.getPermissionRequests

Returns all the outstanding permission requests.

cordova.plugins.WindowsWebview.getPermissionRequests(success, fail);

• success: {Function(requests: WWPermissionRequest[])} Optional. The callback function to execute when requests have been returned.

• fail: {Function} Optional. The callback function to execute when failing to get the requests.

cordova.plugins.WindowsWebview.onPermissionRequested

Creates an event handler and registers it to the permission requested event.

cordova.plugins.WindowsWebview.onPermissionRequested(callback);

• callback: {Function(request: WWPermissionRequest)} {returns: Function} The callback function to execute when the permission requested event is fired. Returns the created event handler which can be used to unregister the event handler.

cordova.plugins.WindowsWebview.offPermissionRequested

Unregisters the provided event handler from the permission requested event.

cordova.plugins.WindowsWebview.offPermissionRequested(callback);

• callback: {Function()} The event handler to unregister.

Classes

WWPermissionRequest

Properties

• id: {number} The identifier for the permission request.

• type: {string} The type of permission requested. WebViewPermissionType enumeration

• uri: {string} The Uniform Resource Identifier (URI) of the content where the permission request originated.

Methods

• allow: Grants the requested permission.

• deny: Denies the requested permission.

Supported Platforms

• Windows

Credits

Incorporates the SSLCertificateChecker-PhoneGap-Plugin by Eddy Verbruggen. Uses JSON.prune.js by Canop.