cordova.diagnostic.plugin

v4.0.10

Published

3 years ago

Cordova/Phonegap plugin to check the state of Location/WiFi/Camera/Bluetooth device settings.

Downloads

215

0High
0Medium
0Low

tylerkuster

ecosystem:cordova cordova android ios windows phonegap diagnostic wifi location gps camera bluetooth settings

Cordova diagnostic plugin

Overview

This Cordova/Phonegap plugin for iOS, Android and Windows 10 UWP is used to manage device settings such as Location, Bluetooth and WiFi. It enables management of run-time permissions, device hardware and core OS features.

The plugin is registered in on npm as cordova.plugins.diagnostic

I dedicate a considerable amount of my free time to developing and maintaining this Cordova plugin, along with my other Open Source software. To help ensure this plugin is kept updated, new features are added and bugfixes are implemented quickly, please donate a couple of dollars (or a little more if you can stretch) as this will help me to afford to dedicate time to its maintenance. Please consider donating if you're using this plugin in an app that makes you money, if you're being paid to make the app, if you're asking for new features or priority bug fixes.

Important notes

Native environment required

Note that this plugin is intended for use in a native mobile environment. It will NOT work in a browser-emulated Cordova environment, for example by running cordova serve or using the Ripple emulator.

Building for Android

In order to avoid build problems with Android, please make sure you have the latest versions of the following Android SDK components installed:

Android SDK Tools
Android SDK Platform-tools
Android SDK Build-tools
Target SDK Platform - e.g. Android 6.0 (API 23)
Android Support Repository
Android Support Library
Google Repository

Also make sure you have the latest release of the cordova-android platform installed. You can check if the Android platform in your Cordova project is up-to-date using cordova platform check android and if it's not, update it using cordova platform rm android && cordova platform add android@latest.

Phonegap Build uses should use the latest available CLI version (listed here) by specifying using the phonegap-version tag in your config.xml, for example:

<preference name="phonegap-version" value="cli-6.4.0" />

Gradle version collisions

This plugin uses the Android Support Library and pins the major version to align with the target SDK version of the cordova-android platform in its latest release to npm. If your build fails with an error such as this:

Attribute meta-data#android.support.VERSION@value value=(26.0.0-alpha1) from [com.android.support:support-v4:26.0.0-alpha1] AndroidManifest.xml:27:9-38
is also present at [com.android.support:appcompat-v7:25.3.1] AndroidManifest.xml:27:9-31 value=(25.3.1).

Then it's likely that the build failure is due to a collision caused by another plugin requesting a different version of the Android Support Library (see #212, #211, #205, etc.).

Depending what other plugins you have installed in your project, you may need to specify a different version of the Support Library than that specified by this plugin to make your build succeed.

If building locally, one way to do this is to install cordova-android-support-gradle-release into your project. This attempts to override the Android Support Library version specified by other plugins (including this plugin) with a specified version. For example:

cordova plugin add cordova-android-support-gradle-release --variable ANDROID_SUPPORT_VERSION=25.+

Note: cordova-android-support-gradle-release will not work in Phonegap Build (or other cloud-build environments) that do not support Cordova Hook Scripts.

Installation

Using the Cordova/Phonegap/Ionic CLI

$ cordova plugin add cordova.plugins.diagnostic
$ phonegap plugin add cordova.plugins.diagnostic
$ ionic cordova plugin add cordova.plugins.diagnostic

For example, to install for the Android platform

$ plugman install --plugin=cordova.plugins.diagnostic --platform=android --project=platforms/android --plugins_dir=plugins

PhoneGap Build

Add the following xml to your config.xml to use the latest version of this plugin from npm:

<plugin name="cordova.plugins.diagnostic" source="npm" />

Specifying modules

Since cordova.plugins.diagnostic@4 the plugin is split into optional functional modules. The reason for this is so you can choose to install only those parts of the plugin you'll use and therefore not install redundant code/components/frameworks.

By default, all the modules will be added to your project when you install the plugin.

You can specify which modules are installed by adding a <preference> to your config.xml which specifies the modules you wish to add as a space-separated list. Module names should be capitalised.

The preference takes the form:

<preference name="cordova.plugins.diagnostic.modules" value="[list of modules]" />

For example, to explicitly include all optional modules:

<preference name="cordova.plugins.diagnostic.modules" value="LOCATION BLUETOOTH WIFI CAMERA NOTIFICATIONS MICROPHONE CONTACTS CALENDAR REMINDERS MOTION NFC EXTERNAL_STORAGE" />

To install only the core module and no optional modules, leave the preference value blank:

<preference name="cordova.plugins.diagnostic.modules" value="" />

Available modules

The following optional modules are currently supported by the plugin:

LOCATION - Android, iOS, Windows 10 UWP
BLUETOOTH - Android, iOS, Windows 10 UWP
WIFI - Android, iOS, Windows 10 UWP
CAMERA - Android, iOS, Windows 10 UWP
NOTIFICATIONS - Android, iOS
MICROPHONE - Android, iOS
CONTACTS - Android, iOS
CALENDAR - Android, iOS
REMINDERS - iOS
MOTION - iOS
NFC - Android
EXTERNAL_STORAGE - Android

IMPORTANT: It's vital that the preference be added to your config.xml before you install the plugin, otherwise the preference will not be applied and all modules will be added. This is because, due to limitations of the Cordova CLI hooks, this plugin must use the npm install process to apply the module preferences and this runs before the Cordova CLI when installing a plugin. If you change the modules specified in the preference, you'll need to uninstall then re-install the plugin to your project to apply the changes.

Usage

The core plugin module is exposed via the global cordova.plugins.diagnostic object and it aliases all functions and properties of the other optional modules. If a function is called on the core module for an optional module which is not installed, a JS error will be raised by the core module.

Core module

Purpose: Generic and miscellaneous functionality.

Platforms: Android, iOS and Windows 10 UWP

Configuration name: N/A - always installed, regardless of whether the module preference key is present in config.xml.

switchToSettings()

Platforms: Android and iOS

Opens settings page for this app.

On Android, this opens the "App Info" page in the Settings app.

On iOS, this opens the app settings page in the Settings app. This works only on iOS 8+ - iOS 7 and below will invoke the errorCallback.

cordova.plugins.diagnostic.switchToSettings(successCallback, errorCallback);

Parameters

{Function} successCallback - The callback which will be called when switch to settings is successful.
{Function} errorCallback - The callback which will be called when switch to settings encounters an error. The function is passed a single string parameter containing the error message.

Example usage

cordova.plugins.diagnostic.switchToSettings(function(){
    console.log("Successfully switched to Settings app");
}, function(error){
    console.error("The following error occurred: "+error);
});

switchToWirelessSettings()

Platforms: Android

Switches to the wireless settings page in the Settings app. Allows configuration of wireless controls such as Wi-Fi, Bluetooth and Mobile networks.

cordova.plugins.diagnostic.switchToWirelessSettings();

switchToMobileDataSettings()

Platforms: Android and Windows 10 UWP

Displays mobile settings to allow user to enable mobile data.

cordova.plugins.diagnostic.switchToMobileDataSettings();

permissionStatus constants

Platforms: Android and iOS

Both Android and iOS define constants for requesting and reporting the various permission states.

cordova.plugins.diagnostic.permissionStatus

Android

The following permission states are defined for Android:

NOT_REQUESTED - App has not yet requested access to this permission. App can request permission and user will be prompted to allow/deny.
GRANTED - User granted access to this permission, the device is running Android 5.x or below, or the app is built with API 22 or below.
DENIED - User denied access to this permission (without checking "Never Ask Again" box). App can request permission again and user will be prompted again to allow/deny again.
DENIED_ALWAYS - User denied access to this permission and checked "Never Ask Again" box. App can never ask for permission again. The only way around this is to instruct the user to manually change the permission on the app permissions settings page.

iOS

The following permission states are defined for iOS:

NOT_REQUESTED - App has not yet requested access to this permission. App can request permission and user will be prompted to allow/deny.
DENIED - User denied access to this permission. App can never ask for permission again. The only way around this is to instruct the user to manually change the permission in the Settings app.
RESTRICTED - Permission is unavailable and user cannot enable it. For example, when parental controls are in effect for the current user.
GRANTED - User granted access to this permission. For location permission, this indicates the user has granted access to the permission "always" (when app is both in foreground and background).
GRANTED_WHEN_IN_USE - Used only for location permission. Indicates the user has granted access to the permission "when in use" (only when the app is in the foreground).

Example

if(somePermissionStatus === cordova.plugins.diagnostic.permissionStatus.GRANTED){
    // Do something
}

getPermissionAuthorizationStatus()

Platforms: Android

Returns the current authorisation status for a given permission.

Note: this is intended for Android 6 / API 23 and above. Calling on Android 5 / API 22 and below will always return GRANTED status as permissions are already granted at installation time.

Parameters

{Function} successCallback - function to call on successful retrieval of status. The function is passed a single string parameter which defines the current permission status
{Function} errorCallback - function to call on failure to retrieve authorisation status. The function is passed a single string parameter containing the error message.
{String} permission - permission to request authorisation status for, defined as a runtime permission constant.

Example usage

cordova.plugins.diagnostic.getPermissionAuthorizationStatus(function(status){
    switch(status){
        case cordova.plugins.diagnostic.permissionStatus.GRANTED:
            console.log("Permission granted to use the camera");
            break;
        case cordova.plugins.diagnostic.permissionStatus.NOT_REQUESTED:
            console.log("Permission to use the camera has not been requested yet");
            break;
        case cordova.plugins.diagnostic.permissionStatus.DENIED:
            console.log("Permission denied to use the camera - ask again?");
            break;
        case cordova.plugins.diagnostic.permissionStatus.DENIED_ALWAYS:
            console.log("Permission permanently denied to use the camera - guess we won't be using it then!");
            break;
    }
}, function(error){
    console.error("The following error occurred: "+error);
}, cordova.plugins.diagnostic.permission.CAMERA);

getPermissionsAuthorizationStatus()

Platforms: Android

Returns the current authorisation status for multiple permissions.

Note: this is intended for Android 6 / API 23 and above. Calling on Android 5 / API 22 and below will always return GRANTED status as permissions are already granted at installation time.

Parameters

{Function} successCallback - function to call on successful retrieval of status. The function is passed a single object parameter which defines a key/value map, where the key is the requested runtime permission, and the value is the current permission status.
{Function} errorCallback - function to call on failure to retrieve authorisation status. The function is passed a single string parameter containing the error message.
{Array} permissions - list of permissions to request authorisation statuses for, defined as runtime permission constants.

Example usage

cordova.plugins.diagnostic.getPermissionsAuthorizationStatus(function(statuses){
    for (var permission in statuses){
        switch(statuses[permission]){
            case cordova.plugins.diagnostic.permissionStatus.GRANTED:
                console.log("Permission granted to use "+permission);
                break;
            case cordova.plugins.diagnostic.permissionStatus.NOT_REQUESTED:
                console.log("Permission to use "+permission+" has not been requested yet");
                break;
            case cordova.plugins.diagnostic.permissionStatus.DENIED:
                console.log("Permission denied to use "+permission+" - ask again?");
                break;
            case cordova.plugins.diagnostic.permissionStatus.DENIED_ALWAYS:
                console.log("Permission permanently denied to use "+permission+" - guess we won't be using it then!");
                break;
        }
    }
}, function(error){
    console.error("The following error occurred: "+error);
},[
    cordova.plugins.diagnostic.permission.ACCESS_FINE_LOCATION,
    cordova.plugins.diagnostic.permission.ACCESS_COARSE_LOCATION
]);

requestRuntimePermission()

Platforms: Android

Requests app to be granted authorisation for a runtime permission.

Note: this is intended for Android 6 / API 23 and above. Calling on Android 5 / API 22 and below will have no effect as the permissions are already granted at installation time.

Parameters

{Function} successCallback - function to call on successful request for runtime permission. The function is passed a single string parameter which defines the resulting permission status
{Function} errorCallback - function to call on failure to request authorisation. The function is passed a single string parameter containing the error message.
{String} permission - permission to request authorisation for, defined as a runtime permission constant.

Example usage

cordova.plugins.diagnostic.requestRuntimePermission(function(status){
    switch(status){
        case cordova.plugins.diagnostic.permissionStatus.GRANTED:
            console.log("Permission granted to use the camera");
            break;
        case cordova.plugins.diagnostic.permissionStatus.NOT_REQUESTED:
            console.log("Permission to use the camera has not been requested yet");
            break;
        case cordova.plugins.diagnostic.permissionStatus.DENIED:
            console.log("Permission denied to use the camera - ask again?");
            break;
        case cordova.plugins.diagnostic.permissionStatus.DENIED_ALWAYS:
            console.log("Permission permanently denied to use the camera - guess we won't be using it then!");
            break;
    }
}, function(error){
    console.error("The following error occurred: "+error);
}, cordova.plugins.diagnostic.permission.CAMERA);

requestRuntimePermissions()

Platforms: Android

Requests app to be granted authorisation for multiple runtime permissions.

Note: this is intended for Android 6 / API 23 and above. Calling on Android 5 / API 22 and below will always return GRANTED status as permissions are already granted at installation time.

Parameters

{Function} successCallback - function to call on successful request for runtime permissions. The function is passed a single object parameter which defines a key/value map, where the key is the runtime permission to request, and the value is the current permission status.
{Function} errorCallback - function to call on failure to request authorisation. The function is passed a single string parameter containing the error message.
{Array} permissions - list of permissions to request authorisation for, defined as runtime permission constants.

Example usage

cordova.plugins.diagnostic.requestRuntimePermissions(function(statuses){
    for (var permission in statuses){
        switch(statuses[permission]){
            case cordova.plugins.diagnostic.permissionStatus.GRANTED:
                console.log("Permission granted to use "+permission);
                break;
            case cordova.plugins.diagnostic.permissionStatus.NOT_REQUESTED:
                console.log("Permission to use "+permission+" has not been requested yet");
                break;
            case cordova.plugins.diagnostic.permissionStatus.DENIED:
                console.log("Permission denied to use "+permission+" - ask again?");
                break;
            case cordova.plugins.diagnostic.permissionStatus.DENIED_ALWAYS:
                console.log("Permission permanently denied to use "+permission+" - guess we won't be using it then!");
                break;
        }
    }
}, function(error){
    console.error("The following error occurred: "+error);
},[
    cordova.plugins.diagnostic.permission.ACCESS_FINE_LOCATION,
    cordova.plugins.diagnostic.permission.ACCESS_COARSE_LOCATION
]);

isRequestingPermission()

Platforms: Android

Indicates if the plugin is currently requesting a runtime permission via the native API. Note that only one request can be made concurrently because the native API cannot handle concurrent requests, so the plugin will invoke the error callback if attempting to make more than one simultaneous request. Multiple permission requests should be grouped into a single call since the native API is setup to handle batch requests of multiple permission groups.

var isRequesting = cordova.plugins.diagnostic.isRequestingPermission();

Example usage

var isRequesting = cordova.plugins.diagnostic.isRequestingPermission();
if(!isRequesting){
    requestSomePermissions();
}else{
    cordova.plugins.diagnostic.registerPermissionRequestCompleteHandler(function(statuses){
        cordova.plugins.diagnostic.registerPermissionRequestCompleteHandler(null); // de-register handler after single call
        requestSomePermissions();
    });
}

registerPermissionRequestCompleteHandler()

Platforms: Android

Registers a function to be called when a runtime permission request has completed. Pass in a falsey value to de-register the currently registered function.

cordova.plugins.diagnostic.registerPermissionRequestCompleteHandler(successCallback);

Parameters

{Function} successCallback - The callback which will be called when a runtime permission request has completed. The function is passed a single object parameter which defines a key/value map, where the key is the permission requested (defined as a value in cordova.plugins.diagnostic.permission) and the value is the resulting authorisation status of that permission as a value in cordova.plugins.diagnostic.permissionStatus.

Example usage

function onPermissionRequestComplete(statuses){
    console.info("Permission request complete");
    for (var permission in statuses){
        switch(statuses[permission]){
            case cordova.plugins.diagnostic.permissionStatus.GRANTED:
                console.log("Permission granted to use "+permission);
                break;
            case cordova.plugins.diagnostic.permissionStatus.NOT_REQUESTED:
                console.log("Permission to use "+permission+" has not been requested yet");
                break;
            case cordova.plugins.diagnostic.permissionStatus.DENIED:
                console.log("Permission denied to use "+permission);
                break;
            case cordova.plugins.diagnostic.permissionStatus.DENIED_ALWAYS:
                console.log("Permission permanently denied to use "+permission);
                break;
        }
    }
    cordova.plugins.diagnostic.registerPermissionRequestCompleteHandler(null); // de-register handler
}
cordova.plugins.diagnostic.registerPermissionRequestCompleteHandler(onPermissionRequestComplete);

isDataRoamingEnabled()

Platforms: Android

Checks if the device data roaming setting is enabled. Returns true if data roaming is enabled.

cordova.plugins.diagnostic.isDataRoamingEnabled(successCallback, errorCallback);

Parameters

{Function} successCallback - The callback which will be called when the operation is successful. The function is passed a single boolean parameter which is TRUE if data roaming is enabled.
{Function} errorCallback - The callback which will be called when operation encounters an error. The function is passed a single string parameter containing the error message.

Example usage

cordova.plugins.diagnostic.isDataRoamingEnabled(function(enabled){
    console.log("Data roaming is " + (enabled ? "enabled" : "disabled"));
}, function(error){
    console.error("The following error occurred: "+error);
});

isADBModeEnabled()

Platforms: Android

Checks if the device setting for ADB(debug) is switched on. Returns true if ADB(debug) setting is switched on.

cordova.plugins.diagnostic.isADBModeEnabled(successCallback, errorCallback);

Parameters

{Function} successCallback - The callback which will be called when operation is successful. The function is passed a single boolean parameter which is TRUE if ADB mode(debug mode) is switched on.
{Function} errorCallback - The callback which will be called when operation encounters an error. The function is passed a single string parameter containing the error message.

Example usage

cordova.plugins.diagnostic.isADBModeEnabled(function(enabled){
    console.log("ADB mode(debug mode) is " + (enabled ? "enabled" : "disabled"));
}, function(error){
    console.error("The following error occurred: "+error);
});

isDeviceRooted()

Platforms: Android

Checks if the device is rooted. Returns true if the device is rooted.

cordova.plugins.diagnostic.isDeviceRooted(successCallback, errorCallback);

Parameters

{Function} successCallback - The callback which will be called when operation is successful. The function is passed a single boolean parameter which is TRUE if the device is rooted.
{Function} errorCallback - The callback which will be called when operation encounters an error. The function is passed a single string parameter containing the error message.

Example usage

cordova.plugins.diagnostic.isDeviceRooted(function(rooted){
    console.log("device is " + (rooted ? "rooted" : "not rooted"));
}, function(error){
    console.error("The following error occurred: "+error);
});

isBackgroundRefreshAuthorized()

Platforms: iOS

Checks if the application is authorized for background refresh.

cordova.plugins.diagnostic.isBackgroundRefreshAuthorized(successCallback, errorCallback);

Parameters

{Function} successCallback - The callback which will be called when operation is successful. The function is passed a single boolean parameter which is TRUE if background refresh access is authorized for use.
{Function} errorCallback - The callback which will be called when operation encounters an error. The function is passed a single string parameter containing the error message.

Example usage

cordova.plugins.diagnostic.isBackgroundRefreshAuthorized(function(authorized){
    console.log("App is " + (authorized ? "authorized" : "not authorized") + " to perform background refresh");
}, function(error){
    console.error("The following error occurred: "+error);
});

getBackgroundRefreshStatus()

Platforms: iOS

Returns the background refresh authorization status for the application.

cordova.plugins.diagnostic.getBackgroundRefreshStatus(successCallback, errorCallback);

Parameters

{Function} successCallback - The callback which will be called when operation is successful. The function is passed a single string parameter which indicates the authorization status as a permissionStatus constant.
{Function} errorCallback - The callback which will be called when operation encounters an error. The function is passed a single string parameter containing the error message.

Example usage

cordova.plugins.diagnostic.getBackgroundRefreshStatus(function(status){
    if(status === cordova.plugins.diagnostic.permissionStatus.GRANTED){
        console.log("Background refresh is allowed");
    }
}, function(error){
    console.error("The following error occurred: "+error);
});

cpuArchitecture constants

Platforms: Android and iOS

Defines constants for the various CPU architectures of the current hardware returned by getArchitecture().

    cordova.plugins.diagnostic.cpuArchitecture

Android

UNKNOWN - Unknown CPU architecture
ARMv6 - ARM v6 or below (32 bit)
ARMv7 - ARM v7 (32 bit)
ARMv8 - ARM v8 (64 bit)
X86 - Intel x86 (32 bit)
X86_64 - Intel x86 (64 bit)
MIPS - MIPS (32 bit)
MIPS_64 - MIPS (64 bit)

iOS

UNKNOWN - Unknown CPU architecture
ARMv6 - ARM v6 or below (32 bit)
ARMv7 - ARM v7 (32 bit)
ARMv8 - ARM v8 (64 bit)
X86 - Intel x86 (32 bit)
X86_64 - Intel x86 (64 bit)

Example usage

See getArchitecture().

getArchitecture()

Platforms: Android and iOS

Returns the CPU architecture of the current device.

cordova.plugins.diagnostic.getArchitecture(successCallback, errorCallback);

Parameters

{Function} successCallback - The callback which will be called when operation is successful. The function is passed a single boolean parameter which indicates the location authorization status as a cpuArchitecture constant.
{Function} errorCallback - The callback which will be called when operation encounters an error. The function is passed a single string parameter containing the error message.

Example usage

cordova.plugins.diagnostic.getArchitecture(function(arch){
    if(arch === cordova.plugins.diagnostic.cpuArchitecture.X86
    || arch === cordova.plugins.diagnostic.cpuArchitecture.X86_64){
        console.log("Intel inside");
    }
}, function(error){
    console.error(error);
});

restart()

Platforms: Android

Restarts the application. By default, a "warm" restart will be performed in which the main Cordova activity is immediately restarted, causing the Webview instance to be recreated.

However, if the cold parameter is set to true, then the application will be "cold" restarted, meaning a system exit will be performed, causing the entire application to be restarted. This is useful if you want to fully reset the native application state but will cause the application to briefly disappear and re-appear.

Note: There is no successCallback() since if the operation is successful, the application will restart immediately before any success callback can be applied.

cordova.plugins.diagnostic.restart(errorCallback, cold);

Parameters

{Function} errorCallback - The callback which will be called when operation encounters an error. The function is passed a single string parameter containing the error message.
{Boolean} cold - if true the application will be cold restarted. Defaults to false.

Example usage

var onError = function(error){
    console.error("The following error occurred: "+error);
}

// Warm restart
cordova.plugins.diagnostic.restart(onError, false);
    
// Cold restart
cordova.plugins.diagnostic.restart(onError, true);

enableDebug()

Platforms: Android and iOS

Enables debug mode, which logs native debug messages to the native and JS consoles.

For Android, log messages will appear in the native logcat output and in the JS console if Chrome Developer Tools is connected to the app Webview.
For Android, log messages will appear in the native Xcode console output and in the JS console if Safari Web Inspector is connected to the app Webview.
Debug mode is initially disabled on plugin initialisation.
cordova.plugins.diagnostic.enableDebug(successCallback);

Parameters

{Function} successCallback - The callback which will be called when debug has been enabled.

Example usage

cordova.plugins.diagnostic.enableDebug(function(){
    console.log("Debug is enabled"));
});

Location module

Purpose: Location/GPS functionality

Platforms: Android, iOS and Windows 10 UWP

Configuration name: LOCATION

locationMode constants

Platforms: Android

Defines constants for the various location modes on Android.

cordova.plugins.diagnostic.locationMode

Values

HIGH_ACCURACY - GPS hardware, network triangulation and Wifi network IDs (high and low accuracy)
BATTERY_SAVING - Network triangulation and Wifi network IDs (low accuracy)
DEVICE_ONLY - GPS hardware (high accuracy)
LOCATION_OFF - Location services disabled (no accuracy)

Example

cordova.plugins.diagnostic.getLocationMode(function(locationMode){
    switch(locationMode){
        case cordova.plugins.diagnostic.locationMode.HIGH_ACCURACY:
            console.log("High accuracy");
            break;
        case cordova.plugins.diagnostic.locationMode.BATTERY_SAVING:
            console.log("Battery saving");
            break;
        case cordova.plugins.diagnostic.locationMode.DEVICE_ONLY:
            console.log("Device only");
            break;
        case cordova.plugins.diagnostic.locationMode.LOCATION_OFF:
            console.log("Location off");
            break;
    }
},function(error){
    console.error("The following error occurred: "+error);
});

isLocationAvailable()

Platforms: Android, iOS and Windows 10 UWP

Checks if app is able to access device location.

cordova.plugins.diagnostic.isLocationAvailable(successCallback, errorCallback);

On iOS and Windows 10 UWP this returns true if both the device setting is enabled AND the application is authorized to use location. When location is enabled, the locations returned are by a mixture GPS hardware, network triangulation and Wifi network IDs.

On Android, this returns true if Location mode is enabled and any mode is selected (e.g. Battery saving, Device only, High accuracy) AND if the app is authorised to use location. When location is enabled, the locations returned are dependent on the location mode:

Battery saving = network triangulation and Wifi network IDs (low accuracy)
Device only = GPS hardware only (high accuracy)
High accuracy = GPS hardware, network triangulation and Wifi network IDs (high and low accuracy)

Parameters

{Function} successCallback - The callback which will be called when operation is successful. The function is passed a single boolean parameter which is TRUE if location is available for use.
{Function} errorCallback - The callback which will be called when operation encounters an error. The function is passed a single string parameter containing the error message.

Example usage

cordova.plugins.diagnostic.isLocationAvailable(function(available){
    console.log("Location is " + (available ? "available" : "not available"));
}, function(error){
    console.error("The following error occurred: "+error);
});

isLocationEnabled()

Platforms: Android and iOS

Returns true if the device setting for location is on. On Android this returns true if Location Mode is switched on. On iOS this returns true if Location Services is switched on.

cordova.plugins.diagnostic.isLocationEnabled(successCallback, errorCallback);

Parameters

{Function} successCallback - The callback which will be called when operation is successful. The function is passed a single boolean parameter which is TRUE if location setting is enabled.
{Function} errorCallback - The callback which will be called when operation encounters an error. The function is passed a single string parameter containing the error message.

Example usage

cordova.plugins.diagnostic.isLocationEnabled(function(enabled){
    console.log("Location setting is " + (enabled ? "enabled" : "disabled"));
}, function(error){
    console.error("The following error occurred: "+error);
});

isGpsLocationAvailable()

Platforms: Android

Checks if high-accuracy locations are available to the app from GPS hardware. Returns true if Location mode is enabled and is set to "Device only" or "High accuracy" AND if the app is authorised to use location.

cordova.plugins.diagnostic.isGpsLocationAvailable(successCallback, errorCallback);

Parameters

{Function} successCallback - The callback which will be called when operation is successful. The function is passed a single boolean parameter which is TRUE if high-accuracy GPS-based location is available.
{Function} errorCallback - The callback which will be called when operation encounters an error. The function is passed a single string parameter containing the error message.

Example usage

cordova.plugins.diagnostic.isGpsLocationAvailable(function(available){
    console.log("GPS location is " + (available ? "available" : "not available"));
}, function(error){
    console.error("The following error occurred: "+error);
});

isGpsLocationEnabled()

Platforms: Android

Checks if the device location setting is set to return high-accuracy locations from GPS hardware. Returns true if Location mode is enabled and is set to either:

Device only = GPS hardware only (high accuracy)
High accuracy = GPS hardware, network triangulation and Wifi network IDs (high and low accuracy)
cordova.plugins.diagnostic.isGpsLocationEnabled(successCallback, errorCallback);

Parameters

{Function} successCallback - The callback which will be called when operation is successful. The function is passed a single boolean parameter which is TRUE if device setting is set to return high-accuracy GPS-based location.
{Function} errorCallback - The callback which will be called when operation encounters an error. The function is passed a single string parameter containing the error message.

Example usage

cordova.plugins.diagnostic.isGpsLocationEnabled(function(enabled){
    console.log("GPS location is " + (enabled ? "enabled" : "disabled"));
}, function(error){
    console.error("The following error occurred: "+error);
});

isNetworkLocationAvailable()

Platforms: Android

Checks if low-accuracy locations are available to the app from network triangulation/WiFi access points. Returns true if Location mode is enabled and is set to "Battery saving" or "High accuracy" AND if the app is authorised to use location.

cordova.plugins.diagnostic.isNetworkLocationAvailable(successCallback, errorCallback);

Parameters

{Function} successCallback - The callback which will be called when operation is successful. The function is passed a single boolean parameter which is TRUE if low-accuracy network-based location is available.
{Function} errorCallback - The callback which will be called when operation encounters an error. The function is passed a single string parameter containing the error message.

Example usage

cordova.plugins.diagnostic.isNetworkLocationAvailable(function(available){
    console.log("Network location is " + (available ? "available" : "not available"));
}, function(error){
    console.error("The following error occurred: "+error);
});

isNetworkLocationEnabled()

Platforms: Android

Checks if location mode is set to return low-accuracy locations from network triangulation/WiFi access points Returns true if Location mode is enabled and is set to either:

Battery saving = network triangulation and Wifi network IDs (low accuracy)
High accuracy = GPS hardware, network triangulation and Wifi network IDs (high and low accuracy)
cordova.plugins.diagnostic.isNetworkLocationEnabled(successCallback, errorCallback);

Parameters

{Function} successCallback - The callback which will be called when operation is successful. The function is passed a single boolean parameter which is TRUE if device setting is set to return low-accuracy network-based location.
{Function} errorCallback - The callback which will be called when operation encounters an error. The function is passed a single string parameter containing the error message.

Example usage

cordova.plugins.diagnostic.isNetworkLocationEnabled(function(enabled){
    console.log("Network location is " + (enabled ? "enabled" : "disabled"));
}, function(error){
    console.error("The following error occurred: "+error);
});

getLocationMode()

Platforms: Android

Returns the current location mode setting for the device.

cordova.plugins.diagnostic.getLocationMode(successCallback, errorCallback);

Parameters

{Function} successCallback - The callback which will be called when operation is successful. The function is passed a single string parameter indicating the current location mode as a constant in cordova.plugins.diagnostic.locationMode.
{Function} errorCallback - The callback which will be called when operation encounters an error. The function is passed a single string parameter containing the error message.

Example usage

cordova.plugins.diagnostic.getLocationMode(function(locationMode){
    switch(locationMode){
        case cordova.plugins.diagnostic.locationMode.HIGH_ACCURACY:
            console.log("High accuracy");
            break;
        case cordova.plugins.diagnostic.locationMode.BATTERY_SAVING:
            console.log("Battery saving");
            break;
        case cordova.plugins.diagnostic.locationMode.DEVICE_ONLY:
            console.log("Device only");
            break;
        case cordova.plugins.diagnostic.locationMode.LOCATION_OFF:
            console.log("Location off");
            break;
    }
},function(error){
    console.error("The following error occurred: "+error);
});

isLocationAuthorized()

Platforms: Android and iOS

Checks if the application is authorized to use location.

Notes for Android:

This is intended for Android 6 / API 23 and above. Calling on Android 5 / API 22 and below will always return GRANTED status as permissions are already granted at installation time.
cordova.plugins.diagnostic.isLocationAuthorized(successCallback, errorCallback);

Parameters

{Function} successCallback - The callback which will be called when operation is successful. The function is passed a single boolean parameter. On iOS this will return TRUE if application is authorized to use location either "when in use" (only in foreground) OR "always" (foreground and background). On Android this will return TRUE if the app currently has runtime authorisation to use location.
{Function} errorCallback - The callback which will be called when operation encounters an error. The function is passed a single string parameter containing the error message.

Example usage

cordova.plugins.diagnostic.isLocationAuthorized(function(authorized){
    console.log("Location is " + (authorized ? "authorized" : "unauthorized"));
}, function(error){
    console.error("The following error occurred: "+error);
});

getLocationAuthorizationStatus()

Platforms: Android and iOS

Returns the location authorization status for the application.

Note for Android: this is intended for Android 6 / API 23 and above. Calling on Android 5 / API 22 and below will always return GRANTED status as permissions are already granted at installation time.

cordova.plugins.diagnostic.getLocationAuthorizationStatus(successCallback, errorCallback);

Parameters

{Function} successCallback - The callback which will be called when operation is successful. The function is passed a single string parameter which indicates the location authorization status as a permissionStatus constant.
{Function} errorCallback - The callback which will be called when operation encounters an error. The function is passed a single string parameter containing the error message.

Example iOS usage

cordova.plugins.diagnostic.getLocationAuthorizationStatus(function(status){
   switch(status){
       case cordova.plugins.diagnostic.permissionStatus.NOT_REQUESTED:
           console.log("Permission not requested");
           break;
       case cordova.plugins.diagnostic.permissionStatus.DENIED:
           console.log("Permission denied");
           break;
       case cordova.plugins.diagnostic.permissionStatus.GRANTED:
           console.log("Permission granted always");
           break;
       case cordova.plugins.diagnostic.permissionStatus.GRANTED_WHEN_IN_USE:
           console.log("Permission granted only when in use");
           break;
   }
}, function(error){
    console.error("The following error occurred: "+error);
});

Example Android usage

cordova.plugins.diagnostic.getLocationAuthorizationStatus(function(status){
    switch(status){
        case cordova.plugins.diagnostic.permissionStatus.NOT_REQUESTED:
            console.log("Permission not requested");
            break;
        case cordova.plugins.diagnostic.permissionStatus.GRANTED:
            console.log("Permission granted");
            break;
        case cordova.plugins.diagnostic.permissionStatus.DENIED:
            console.log("Permission denied");
            break;
        case cordova.plugins.diagnostic.permissionStatus.DENIED_ALWAYS:
            console.log("Permission permanently denied");
            break;
    }
}, function(error){
    console.error(error);
});

requestLocationAuthorization()

Platforms: Android and iOS

Requests location authorization for the application.

Notes for iOS:

Calling this on iOS 7 or below will have no effect, as location permissions are are implicitly granted.
On iOS 8+, authorization can be requested to use location either "when in use" (only in foreground) or "always" (foreground and background).
This should only be called if authorization status is NOT_DETERMINED - calling it when in any other state will have no effect.
When calling this function, the messages contained in the NSLocationWhenInUseUsageDescription and NSLocationAlwaysAndWhenInUseUsageDescription (iOS 11+) / NSLocationAlwaysUsageDescription (iOS 10 and below) .plist keys are displayed to the user when requesting to use location always or when in use, respectively; this plugin provides default messages, but you should override them with your specific reason for requesting access - see the iOS usage description messages section for how to customise them.

Notes for Android:

This is intended for Android 6 / API 23 and above. Calling on Android 5 / API 22 and below will have no effect as the permissions are already granted at installation time.
The successCallback is invoked in response to the user's choice in the permission dialog and is passed the resulting authorization status.
cordova.plugins.diagnostic.requestLocationAuthorization(successCallback, errorCallback, mode);

Parameters

{Function} successCallback - Invoked in response to the user's choice in the permission dialog. It is passed a single string parameter which defines the resulting authorisation status.
{Function} errorCallback - The callback which will be called when operation encounters an error. The function is passed a single string parameter containing the error message.
{String} mode - (iOS-only / optional) location authorization mode specified as a locationAuthorizationMode constant. If not specified, defaults to WHEN_IN_USE.

Example iOS usage

cordova.plugins.diagnostic.requestLocationAuthorization(function(status){
    switch(status){
        case cordova.plugins.diagnostic.permissionStatus.NOT_REQUESTED:
            console.log("Permission not requested");
            break;
        case cordova.plugins.diagnostic.permissionStatus.DENIED:
            console.log("Permission denied");
            break;
        case cordova.plugins.diagnostic.permissionStatus.GRANTED:
            console.log("Permission granted always");
            break;
        case cordova.plugins.diagnostic.permissionStatus.GRANTED_WHEN_IN_USE:
            console.log("Permission granted only when in use");
            break;
    }
}, function(error){
    console.error(error);
}, cordova.plugins.diagnostic.locationAuthorizationMode.ALWAYS);

Example Android usage

cordova.plugins.diagnostic.requestLocationAuthorization(function(status){
    switch(status){
        case cordova.plugins.diagnostic.permissionStatus.NOT_REQUESTED:
            console.log("Permission not requested");
            break;
        case cordova.plugins.diagnostic.permissionStatus.GRANTED:
            console.log("Permission granted");
            break;
        case cordova.plugins.diagnostic.permissionStatus.DENIED:
            console.log("Permission denied");
            break;
        case cordova.plugins.diagnostic.permissionStatus.DENIED_ALWAYS:
            console.log("Permission permanently denied");
            break;
    }
}, function(error){
    console.error(error);
});

registerLocationStateChangeHandler()

Platforms: Android and iOS

Registers a function to be called when a change in Location state occurs. Pass in a falsey value to de-register the currently registered function.

This is triggered when Location state changes so is useful for detecting changes made in quick settings which would not result in pause/resume events being fired.

On Android, this occurs when the Location Mode is changed.

On iOS, this occurs when location authorization status is changed. This can be triggered either by the user's response to a location permission authorization dialog, by the user turning on/off Location Services, or by the user changing the Location authorization state specifically for your app.

cordova.plugins.diagnostic.registerLocationStateChangeHandler(successCallback);

Parameters

{Function} successCallback - function call when a change in location state occurs. On Android, the function is passed a single string parameter defined as a constant in cordova.plugins.diagnostic.locationMode. On iOS, the function is passed a single string parameter indicating the new location authorisation status as a constant in cordova.plugins.diagnostic.permissionStatus.

Example usage

cordova.plugins.diagnostic.registerLocationStateChangeHandler(function(state){
    if((device.platform === "Android" && state !== cordova.plugins.diagnostic.locationMode.LOCATION_OFF)
        || (device.platform === "iOS") && ( state === cordova.plugins.diagnostic.permissionStatus.GRANTED
            || state === cordova.plugins.diagnostic.permissionStatus.GRANTED_WHEN_IN_USE
    )){
        console.log("Location is available");
    }
});

switchToLocationSettings()

Platforms: Android and Windows 10 UWP

Displays the device location settings to allow user to enable location services/change location mode.

cordova.plugins.diagnostic.switchToLocationSettings();

Note: On Android, you may want to consider using the Request Location Accuracy Plugin for Android to request the desired location accuracy without needing the user to manually do this on the Location Settings page.

Bluetooth module

Purpose: Bluetooth functionality to get/set Bluetooth Radio state.

Platforms: Android, iOS and Windows 10 UWP

Configuration name: BLUETOOTH

bluetoothState constants

Platforms: Android and iOS

Defines constants for the various Bluetooth hardware states

    cordova.plugins.diagnostic.bluetoothState

Android

UNKNOWN - Bluetooth hardware state is unknown or unavailable
POWERED_OFF - Bluetooth hardware is switched off
POWERED_ON - Bluetooth hardware is switched on and available for use
POWERING_OFF- Bluetooth hardware is currently switching off
POWERING_ON- Bluetooth hardware is currently switching on

iOS

UNKNOWN - Bluetooth hardware state is unknown
RESETTING - Bluetooth hardware state is currently resetting
POWERED_OFF - Bluetooth hardware is switched off
POWERED_ON - Bluetooth hardware is switched on and available for use
UNAUTHORIZED- Bluetooth hardware use is not authorized for the current application

Example

cordova.plugins.diagnostic.getBluetoothState(function(state){
    if(state === cordova.plugins.diagnostic.bluetoothState.POWERED_ON){
        // Do something with Bluetooth
    }
}, function(error){
    console.error(error);
});

isBluetoothAvailable()

Platforms: Android, iOS and Windows 10 UWP

Checks if Bluetooth is available to the app. Returns true if the device has Bluetooth capabilities AND if Bluetooth setting is switched on (same on Android, iOS and Windows 10 UWP)

On Android this requires permission <uses-permission android:name="android.permission.BLUETOOTH" />

cordova.plugins.diagnostic.isBluetoothAvailable(successCallback, errorCallback);

Parameters

{Function} successCallback - The callback which will be called when operation is successful. The function is passed a single boolean parameter which is TRUE if Bluetooth is available.
{Function} errorCallback - The callback which will be called when operation encounters an error. The function is passed a single string parameter containing the error message.

Example usage

cordova.plugins.diagnostic.isBluetoothAvailable(function(available){
    console.log("Bluetooth is " + (available ? "available" : "not available"));
}, function(error){
    console.error("The following error occurred: "+error);
});

Purpose: Bluetooth functionality Platforms: Android, iOS and Windows 10 UWP Configuration name: BLUETOOTH

isBluetoothEnabled()

Platforms: Android

Checks if the device setting for Bluetooth is switched on.

On Android this requires permission <uses-permission android:name="android.permission.BLUETOOTH" />

cordova.plugins.diagnostic.isBluetoothAvailable(successCallback, errorCallback);

Parameters

{Function} successCallback - The callback which will be called when operation is successful. The function is passed a single boolean parameter which is TRUE if Bluetooth is switched on.
{Function} errorCallback - The callback which will be called when operation encounters an error. The function is passed a single string parameter containing the error message.

Example usage

cordova.plugins.diagnostic.isBluetoothEnabled(function(enabled){
    console.log("Bluetooth is " + (enabled ? "enabled" : "disabled"));
}, function(error){
    console.error("The following error occurred: "+error);
});

hasBluetoothSupport()

Platforms: Android

Checks if the device has Bluetooth capabilities. See http://developer.android.com/guide/topics/connectivity/bluetooth.html.

cordova.plugins.diagnostic.hasBluetoothLESupport(successCallback, errorCallback);

Parameters

{Function} successCallback - The callback which will be called when the operation is successful. The function is passed a single boolean parameter which is TRUE if device has Bluetooth capabilities.
{Function} errorCallback - The callback which will be called when the operation encounters an error. The function is passed a single string parameter containing the error message.

Example usage

cordova.plugins.diagnostic.hasBluetoothSupport(function(supported){
    console.log("Bluetooth is " + (supported ? "supported" : "unsupported"));
}, function(error){
    console.error("The following error occurred: "+error);
});

hasBluetoothLESupport()

Platforms: Android

Checks if the device has Bluetooth Low Energy (LE) capabilities. See http://developer.android.com/guide/topics/connectivity/bluetooth-le.html.

cordova.plugins.diagnostic.hasBluetoothLESupport(successCallback, errorCallback);

Parameters

{Function} successCallback - The callback which will be called when the operation is successful. The function is passed a single boolean parameter which is TRUE if device has Bluetooth LE capabilities.
{Function} errorCallback - The callback which will be called when the operation encounters an error. The function is passed a single string parameter containing the error message.

Example usage

cordova.plugins.diagnostic.hasBluetoothLESupport(function(supported){
    console.log("Bluetooth LE is " + (supported ? "supported" : "unsupported"));
}, function(error){
    console.error("The following error occurred: "+error);
});

hasBluetoothLEPeripheralSupport()

Platforms: Android

Checks if the device supports Bluetooth Low Energy (LE) Peripheral mode. See http://developer.android.com/guide/topics/connectivity/bluetooth-le.html#roles.

Parameters

{Function} successCallback - The callback which will be called when the operation is successful. The function is passed a single boolean parameter which is TRUE if device supports Bluetooth LE Peripheral mode.
{Function} errorCallback - The callback which will be called whe

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Cordova diagnostic plugin

Overview

Important notes

Native environment required

Building for Android

Gradle version collisions

Installation

Using the Cordova/Phonegap/Ionic CLI

PhoneGap Build

Specifying modules

Available modules

Usage

Core module

switchToSettings()

Parameters

Example usage

switchToWirelessSettings()

switchToMobileDataSettings()

permissionStatus constants

Android

iOS

Example

getPermissionAuthorizationStatus()

Parameters

Example usage

getPermissionsAuthorizationStatus()

Parameters

Example usage

requestRuntimePermission()

Parameters

Example usage

requestRuntimePermissions()

Parameters

Example usage

isRequestingPermission()

Example usage

registerPermissionRequestCompleteHandler()

Parameters

Example usage

isDataRoamingEnabled()

Parameters

Example usage

isADBModeEnabled()

Parameters

Example usage

isDeviceRooted()

Parameters

Example usage

isBackgroundRefreshAuthorized()

Parameters

Example usage

getBackgroundRefreshStatus()

Parameters

Example usage

cpuArchitecture constants

Android

iOS

Example usage

getArchitecture()

Parameters

Example usage

restart()

Parameters

Example usage

enableDebug()

Parameters

Example usage

Location module

locationMode constants

Values

Example

isLocationAvailable()

Parameters

Example usage