Cordova diagnostic plugin

• Overview
  • Important notes
    • Native environment required
    • Version 3.2 for iOS 10
    • Version 3.1 backward-incompatibility
    • Version 3 backward-incompatibility
    • Building for Android
• Installation
  • Using the Cordova/Phonegap CLI
  • Using Cordova Plugman
  • PhoneGap Build
• Usage
  • Android, iOS and Windows 10 Mobile
    • isLocationAvailable()
    • isWifiAvailable()
    • isWifiEnabled()
    • isCameraAvailable()
    • isBluetoothAvailable()
  • Android and Windows 10 Mobile only
    • switchToLocationSettings()
    • switchToMobileDataSettings()
    • switchToBluetoothSettings()
    • switchToWifiSettings()
    • setWifiState()
    • setBluetoothState()
  • Android and iOS
    • permissionStatus constants
    • bluetoothState constants
    • cpuArchitecture constants
    • enableDebug()
    • getArchitecture()
    • isLocationEnabled()
    • isLocationAuthorized()
    • getLocationAuthorizationStatus()
    • requestLocationAuthorization()
    • isCameraPresent()
    • isCameraAuthorized()
    • isRemoteNotificationsEnabled()
    • getCameraAuthorizationStatus()
    • requestCameraAuthorization()
    • isMicrophoneAuthorized()
    • getMicrophoneAuthorizationStatus()
    • requestMicrophoneAuthorization()
    • isContactsAuthorized()
    • getContactsAuthorizationStatus()
    • requestContactsAuthorization()
    • isCalendarAuthorized()
    • getCalendarAuthorizationStatus()
    • requestCalendarAuthorization()
    • switchToSettings()
    • getBluetoothState()
    • registerBluetoothStateChangeHandler()
    • registerLocationStateChangeHandler()
  • Android only
    • locationMode constants
    • isGpsLocationAvailable()
    • isGpsLocationEnabled()
    • isNetworkLocationAvailable()
    • isNetworkLocationEnabled()
    • isDataRoamingEnabled()
    • getLocationMode()
    • getPermissionAuthorizationStatus()
    • getPermissionsAuthorizationStatus()
    • requestRuntimePermission()
    • requestRuntimePermissions()
    • isRequestingPermission()
    • registerPermissionRequestCompleteHandler()
    • isBluetoothEnabled()
    • hasBluetoothSupport()
    • hasBluetoothLESupport()
    • hasBluetoothLEPeripheralSupport()
    • isExternalStorageAuthorized()
    • getExternalStorageAuthorizationStatus()
    • requestExternalStorageAuthorization()
    • getExternalSdCardDetails()
    • switchToWirelessSettings()
    • switchToNFCSettings()
    • isNFCPresent()
    • isNFCEnabled()
    • isNFCAvailable()
    • isADBModeEnabled()
    • isDeviceRooted()
    • restart()
    • registerNFCStateChangeHandler()
    • NFCState constants
  • iOS only
    • isCameraRollAuthorized()
    • getCameraRollAuthorizationStatus()
    • requestCameraRollAuthorization()
    • remoteNotificationType constants
    • isRegisteredForRemoteNotifications()
    • getRemoteNotificationTypes()
    • getRemoteNotificationsAuthorizationStatus()
    • requestRemoteNotificationsAuthorization()
    • isRemindersAuthorized()
    • getRemindersAuthorizationStatus()
    • requestRemindersAuthorization()
    • isBackgroundRefreshAuthorized()
    • getBackgroundRefreshStatus()
    • requestBluetoothAuthorization()
    • motionStatus constants
    • isMotionAvailable()
    • isMotionRequestOutcomeAvailable()
    • requestMotionAuthorization()
    • getMotionAuthorizationStatus()
• Platform Notes
  • Android
    • Android permissions
  • Windows
    • Supported Windows versions
    • Windows 10 Mobile permissions
  • iOS
    • iOS usage description messages
• Example project
  • Screenshots
    • Android
    • iOS
• Release notes
• Credits
• License

Overview

This Cordova/Phonegap plugin for iOS, Android and Windows 10 Mobile 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.

Version 3.2 for iOS 10

[email protected] adds support for the new UserNotifications framework added in iOS 10. To build using v3.2.0, you will need to use XCode 8+ because there's no way to conditionally include a framework using the <framework> tag in the plugin.xml.

Currently (25 Sep 2016) cloud-based build platforms such as Phonegap Build, Ionic Cloud and Intel XDK are still using an XCode 7 build environment, so building with [email protected] results in a fatal build error framework not found UserNotifications.

Therefore, users of these cloud platforms should specify [email protected] in their config.xml until such time as their cloud platform is updated to use XCode 8+.

Version 3.1 backward-incompatibility

This version contains backwardly-incompatible renaming of some functions in order to logically separate those which check if a device OS setting is enabled (isSomethingEnabled()) vs those which check if hardware/sensor is available for use by the app (device OS setting is enabled AND app has authorisation AND hardware is present - isSomethingAvailable()).

To avoid breaking existing code which uses the prior function names, either fix the version of the plugin in your config.xml to [email protected] or update your code to use the revised names detailed in the release notes.

Version 3 backward-incompatibility

In order to make cross-platform use of the shared plugin functions easier, some backwardly-incompatible changes have been made to existing API functions in v3 of the plugin.

To avoid breaking existing code which uses the old API syntax, you can continue to use the v2 API by specifying the plugin version when adding it: cordova.plugins.diagnostic@2

See the release notes page for details of the backward-incompatible changes.

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.

Building for Android runtime permissions

In order to support Android 6 (API 23) runtime permissions, this plugin must depend on libraries only present in API 23+, so you must build using Android SDK Platform v23 or above. To do this you must have Cordova Android platform@5.0.0 or above installed in your project. You can check the currently installed platform versions with the following command:

cordova platform ls

Note: Attempting to build with API 22 or below will result in a build error.

You must also make sure your build environment has the following Android libraries installed. In a local build environment, you'd install these via the Android SDK Manager:

• Android Support Library - Rev. 23 or above
• Android Support Repository - Rev. 23 or above

Building for API 22 or lower

For users who wish to build against API 22 or below, there is a branch of the plugin repo which contains most of the plugin functionality except Android 6 runtime permissions. This removes the dependency on API 23 and will allow you to build against legacy API versions (22 and below).

The legacy branch is published to npm as cordova.plugins.diagnostic.api-22, so you'll need to use this plugin ID when adding it:

cordova plugin add cordova.plugins.diagnostic.api-22

NOTE: Phonegap Build now supports API 23, so its users may use the main plugin branch (cordova.plugins.diagnostic).

Installation

Using the Cordova/Phonegap CLI

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

NOTE: Make sure your Cordova CLI version is 5.0.0+ (check with cordova -v). Cordova 4.x and below uses the now deprecated Cordova Plugin Registry as its plugin repository, so using a version of Cordova 4.x or below will result in installing an old version of this plugin.

Using Cordova Plugman

$ plugman install --plugin=cordova.plugins.diagnostic --platform=<platform> --project=<project_path> --plugins_dir=plugins

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" />

Usage

The plugin is exposed via the cordova.plugins.diagnostic object and provides the following functions:

Android, iOS and Windows 10 Mobile

isLocationAvailable()

Checks if app is able to access device location.

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

On iOS and Windows 10 Mobile 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);
});

isWifiAvailable()

Checks if Wifi is available. On iOS this returns true if the device is connected to a network by WiFi. On Android and Windows 10 Mobile this returns true if the WiFi setting is set to enabled, and is the same as isWifiEnabled()

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

cordova.plugins.diagnostic.isWifiAvailable(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 WiFi 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.isWifiAvailable(function(available){
    console.log("WiFi is " + (available ? "available" : "not available"));
}, function(error){
    console.error("The following error occurred: "+error);
});

isWifiEnabled()

On iOS this returns true if the WiFi setting is set to enabled (regardless of whether it's connected to a network). On Android and Windows 10 Mobile this returns true if the WiFi setting is set to enabled, and is the same as isWifiAvailable() On Android this requires permission <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

cordova.plugins.diagnostic.isWifiEnabled(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 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.isWifiEnabled(function(enabled){
    console.log("WiFi is " + (enabled ? "enabled" : "disabled"));
}, function(error){
    console.error("The following error occurred: "+error);
});

isCameraAvailable()

Checks if camera is available.

Notes:

• On Android & iOS this returns true if the device has a camera AND the application is authorized to use it.
• On Windows 10 Mobile this returns true if the device has a rear-facing camera.

Notes for Android:

• On Android by default this checks run-time permission for both READ_EXTERNAL_STORAGE and CAMERA because [email protected]+ requires both of these permissions.

• The call signature cordova.plugins.diagnostic.isCameraAvailable(successCallback, errorCallback, externalStorage) is also supported for benefit of the ionic-native Promise API wrapper.

  cordova.plugins.diagnostic.isCameraAvailable(params); cordova.plugins.diagnostic.isCameraAvailable(successCallback, errorCallback, params) cordova.plugins.diagnostic.isCameraAvailable(successCallback, errorCallback, externalStorage)

Parameters

• {Object} params - (optional) 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 camera is present and 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.
  • {Boolean} externalStorage - (Android only) If true, checks permission for READ_EXTERNAL_STORAGE in addition to CAMERA run-time permission. Defaults to true.

Example usage

cordova.plugins.diagnostic.isCameraAvailable({
    successCallback: function(available){
        console.log("Camera is " + (available ? "available" : "not available"));
    },
    errorCallback: function(error){
        console.error("The following error occurred: "+error);
    },
    externalStorage: false
});

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

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

isBluetoothAvailable()

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 Mobile)

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);
});

Android and Windows 10 Mobile only

switchToLocationSettings()

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.

switchToMobileDataSettings()

Displays mobile settings to allow user to enable mobile data.

cordova.plugins.diagnostic.switchToMobileDataSettings();

switchToBluetoothSettings()

Displays Bluetooth settings to allow user to enable Bluetooth.

cordova.plugins.diagnostic.switchToBluetoothSettings();

switchToWifiSettings()

Displays WiFi settings to allow user to enable WiFi.

cordova.plugins.diagnostic.switchToWifiSettings();

setWifiState()

Enables/disables WiFi on the device.

cordova.plugins.diagnostic.setWifiState(successCallback, errorCallback, state);

Requires the following permissions for Android:

<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE"/>

Requires the following capabilities for Windows 10 Mobile:

<DeviceCapability Name="radios" />

Parameters

• {Function} successCallback - function to call on successful setting of WiFi state
• {Function} errorCallback - function to call on failure to set WiFi state.
• {Boolean} state - WiFi state to set: TRUE for enabled, FALSE for disabled.

Example usage

cordova.plugins.diagnostic.setWifiState(function(){
    console.log("Wifi was enabled");
}, function(error){
    console.error("The following error occurred: "+error);
},
true);

setBluetoothState()

Enables/disables Bluetooth on the device.

cordova.plugins.diagnostic.setBluetoothState(successCallback, errorCallback, state);

Requires the following permissions on Android:

<uses-permission android:name="android.permission.BLUETOOTH"/>
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>

Requires the following capabilities for Windows 10 Mobile:

<DeviceCapability Name="radios" />

Parameters

• {Function} successCallback - function to call on successful setting of Bluetooth state
• {Function} errorCallback - function to call on failure to set Bluetooth state.
• {Boolean} state - Bluetooth state to set: TRUE for enabled, FALSE for disabled.

Example usage

cordova.plugins.diagnostic.setBluetoothState(function(){
    console.log("Bluetooth was enabled");
}, function(error){
    console.error("The following error occurred: "+error);
},
true);

Android and iOS

permissionStatus constants

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
}

bluetoothState constants

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);
});

cpuArchitecture constants

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().

enableDebug()

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"));
});

getArchitecture()

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);
});

isLocationEnabled()

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);
});

isLocationAuthorized()

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()

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()

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);
});

isCameraPresent()

Checks if camera hardware is present on device.

cordova.plugins.diagnostic.isCameraPresent(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 camera is present
• {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.isCameraPresent(function(present){
    console.log("Camera is " + (present ? "present" : "absent"));
}, function(error){
    console.error("The following error occurred: "+error);
});

isCameraAuthorized()

Checks if the application is authorized to use the camera.

Notes for Android:

• This is intended for Android 6 / API 23 and above. Calling on Android 5 / API 22 and below will always return TRUE as permissions are already granted at installation time.

• By default this checks run-time permission for both READ_EXTERNAL_STORAGE and CAMERA because [email protected]+ requires both of these permissions.

• The call signature cordova.plugins.diagnostic.isCameraAuthorized(successCallback, errorCallback, externalStorage) is also supported for benefit of the ionic-native Promise API wrapper.

  cordova.plugins.diagnostic.isCameraAuthorized(params); cordova.plugins.diagnostic.isCameraAuthorized(successCallback, errorCallback, params) cordova.plugins.diagnostic.isCameraAuthorized(successCallback, errorCallback, externalStorage)

Parameters

• {Object} params - (optional) 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 camera 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.
  • {Boolean} externalStorage - (Android only) If true, checks permission for READ_EXTERNAL_STORAGE in addition to CAMERA run-time permission. Defaults to true.

Example usage

cordova.plugins.diagnostic.isCameraAuthorized({
    successCallback: function(authorized){
        console.log("App is " + (authorized ? "authorized" : "denied") + " access to the camera");
    },
    errorCallback: function(error){
        console.error("The following error occurred: "+error);
    }, 
    externalStorage: false
});

cordova.plugins.diagnostic.isCameraAuthorized(
    function(authorized){
        console.log("App is " + (authorized ? "authorized" : "denied") + " access to the camera");
    }, function(error){
        console.error("The following error occurred: "+error);
    }, {
        externalStorage: false
    }
);

cordova.plugins.diagnostic.isCameraAuthorized(
    function(authorized){
        console.log("App is " + (authorized ? "authorized" : "denied") + " access to the camera");
    }, function(error){
        console.error("The following error occurred: "+error);
    }, false
);

isRemoteNotificationsEnabled()

Checks if remote (push) notifications are enabled.

On Android, returns whether notifications for the app are not blocked.

On iOS 8+, returns true if app is registered for remote notifications AND "Allow Notifications" switch is ON AND alert style is not set to "None" (i.e. "Banners" or "Alerts"). On iOS <=7, returns true if app is registered for remote notifications AND alert style is not set to "None" (i.e. "Banners" or "Alerts") - same as isRegisteredForRemoteNotifications().

cordova.plugins.diagnostic.isRemoteNotificationsEnabled(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 remote (push) notifications are enabled.
• {Function} errorCallback - The callback which will be called when an error occurs. The function is passed a single string parameter containing the error message.

Example usage

cordova.plugins.diagnostic.isRemoteNotificationsEnabled(function(enabled){
    console.log("Remote notifications are " + (enabled ? "enabled" : "disabled"));
}, function(error){
    console.error("The following error occurred: "+error);
});

getCameraAuthorizationStatus()

Returns the camera authorization status for the application.

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.

• By default this checks run-time permission for both READ_EXTERNAL_STORAGE and CAMERA because [email protected]+ requires both of these permissions.

• The call signature cordova.plugins.diagnostic.getCameraAuthorizationStatus(successCallback, errorCallback, externalStorage) is also supported for benefit of the ionic-native Promise API wrapper.

  cordova.plugins.diagnostic.getCameraAuthorizationStatus(params); cordova.plugins.diagnostic.getCameraAuthorizationStatus(successCallback, errorCallback, params) cordova.plugins.diagnostic.getCameraAuthorizationStatus(successCallback, errorCallback, externalStorage)

Parameters

• {Object} params - (optional) 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.
  • {Boolean} externalStorage - (Android only) If true, checks permission for READ_EXTERNAL_STORAGE in addition to CAMERA run-time permission. Defaults to true.

Example usage

cordova.plugins.diagnostic.getCameraAuthorizationStatus({
    successCallback: function(status){
        if(status === cordova.plugins.diagnostic.permissionStatus.GRANTED){
            console.log("Camera use is authorized");
        }
    },
    errorCallback: function(error){
        console.error("The following error occurred: "+error);
    },
    externalStorage: false
});

cordova.plugins.diagnostic.getCameraAuthorizationStatus(
    function(status){
        if(status === cordova.plugins.diagnostic.permissionStatus.GRANTED){
            console.log("Camera use is authorized");
        }
    }, function(error){
        console.error("The following error occurred: "+error);
    }, {
        externalStorage: false
    }
);

cordova.plugins.diagnostic.getCameraAuthorizationStatus(
    function(status){
        if(status === cordova.plugins.diagnostic.permissionStatus.GRANTED){
            console.log("Camera use is authorized");
        }
    }, function(error){
        console.error("The following error occurred: "+error);
    }, false
);   

requestCameraAuthorization()

Requests camera authorization for the application.

Notes for iOS:

• 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 message contained in the NSCameraUsageDescription .plist key is displayed to the user; this plugin provides a default message, but you should override this with your specific reason for requesting access - see the iOS usage description messages section for how to customise it.

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.

• By default this requests run-time permission for both READ_EXTERNAL_STORAGE and CAMERA because [email protected]+ requires both of these permissions.

• Requested run-time permissions which must be added to AndroidManifest.xml - see Android camera permissions.

• The call signature cordova.plugins.diagnostic.requestCameraAuthorization(successCallback, errorCallback, externalStorage) is also supported for benefit of the ionic-native Promise API wrapper.

  cordova.plugins.diagnostic.requestCameraAuthorization(params); cordova.plugins.diagnostic.requestCameraAuthorization(successCallback, errorCallback, params) cordova.plugins.diagnostic.requestCameraAuthorization(successCallback, errorCallback, externalStorage)

Parameters

• {Object} params - (optional) parameters:
  • {Function} successCallback - The callback which will be called when operation is successful. The function is passed a single string parameter indicating whether access to the camera was granted or denied: cordova.plugins.diagnostic.permissionStatus.GRANTED or cordova.plugins.diagnostic.permissionStatus.DENIED
  • {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} externalStorage - (Android only) If true, requests permission for READ_EXTERNAL_STORAGE in addition to CAMERA run-time permission. Defaults to true.

Example usage

cordova.plugins.diagnostic.requestCameraAuthorization({
    successCallback: function(status){
        console.log("Authorization request for camera use was " + (status == cordova.plugins.diagnostic.permissionStatus.GRANTED ? "granted" : "denied"));
    },
    errorCallback: function(error){
        console.error(error);
    },
    externalStorage: false
});

cordova.plugins.diagnostic.requestCameraAuthorization(
    function(status){
        console.log("Authorization request for camera use was " + (status == cordova.plugins.diagnostic.permissionStatus.GRANTED ? "granted" : "denied"));
    }, function(error){
        console.error("The following error occurred: "+error);
    }, {
        externalStorage: false
    }
);

cordova.plugins.diagnostic.requestCameraAuthorization(
    function(status){
        console.log("Authorization request for camera use was " + (status == cordova.plugins.diagnostic.permissionStatus.GRANTED ? "granted" : "denied"));
    }, function(error){
        console.error("The following error occurred: "+error);
    }, false
);   

isMicrophoneAuthorized()

Checks if the application is authorized to use the microphone.

Notes for Android:

• This is intended for Android 6 / API 23 and above. Calling on Android 5 / API 22 and below will always return TRUE as permissions are already granted at installation time.

Notes for iOS:

• Requires iOS 8+

  cordova.plugins.diagnostic.isMicrophoneAuthorized(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 microphone 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.isMicrophoneAuthorized(function(authorized){
    console.log("App is " + (authorized ? "authorized" : "denied") + " access to the microphone");
}, function(error){
    console.error("The following error occurred: "+error);
});

getMicrophoneAuthorizationStatus()

Returns the microphone authorization status for the application.

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.

Notes for iOS:

• Requires iOS 8+

  cordova.plugins.diagnostic.getMicrophoneAuthorizationStatus(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.getMicrophoneAuthorizationStatus(function(status){
   if(status === cordova.plugins.diagnostic.permissionStatus.GRANTED){
       console.log("Microphone use is authorized");
   }
}, function(error){
    console.error("The following error occurred: "+error);
});

requestMicrophoneAuthorization()

Requests microphone authorization for the application.

Notes for iOS:

• Should only be called if authorization status is NOT_DETERMINED. Calling it when in any other state will have no effect and just return the current authorization status.
• When calling this function, the message contained in the NSMicrophoneUsageDescription .plist key is displayed to the user; this plugin provides a default message, but you should override this with your specific reason for requesting access - see the iOS usage description messages section for how to customise it.
• Requires iOS 7+

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.

• This requests permission for RECORD_AUDIO which must be added to AndroidManifest.xml - see Android permissions.

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

Parameters

• {Function} successCallback - The callback which will be called when operation is successful. The function is passed a single string parameter indicating whether access to the microphone was granted or denied: cordova.plugins.diagnostic.permissionStatus.GRANTED or cordova.plugins.diagnostic.permissionStatus.DENIED
• {Function} errorCallback - The callback which will be called when an error occurs. The function is passed a single string parameter containing the error message.

Example usage

cordova.plugins.diagnostic.requestMicrophoneAuthorization(function(status){
   if(status === cordova.plugins.diagnostic.permissionStatus.GRANTED){
       console.log("Microphone use is authorized");
   }
}, function(error){
    console.error(error);
});

isContactsAuthorized()

Checks if the application is authorized to use contacts (address book).

Notes for Android:

• This is intended for Android 6 / API 23 and above. Calling on Android 5 / API 22 and below will always return TRUE as permissions are already granted at installation time.

  cordova.plugins.diagnostic.isContactsAuthorized(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 contacts 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.isContactsAuthorized(function(authorized){
    console.log("App is " + (authorized ? "authorized" : "denied") + " access to contacts");
}, function(error){
    console.error("The following error occurred: "+error);
});

getContactsAuthorizationStatus()

Returns the contacts authorization status for the application.

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.getContactsAuthorizationStatus(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.getContactsAuthorizationStatus(function(status){
    if(status === cordova.plugins.diagnostic.permissionStatus.GRANTED){
        console.log("Contacts use is authorized");
    }
}, function(error){
    console.error("The following error occurred: "+error);
});

requestContactsAuthorization()

Requests contacts authorization for the application.

Notes for iOS:

• Should only be called if authorization status is NOT_DETERMINED. Calling it when in any other state will have no effect and just return the current authorization status.
• When calling this function, the message contained in the NSContactsUsageDescription .plist key is displayed to the user; this plugin provides a default message, but you should override this with your specific reason for requesting access - see the iOS usage description messages section for how to customise it.

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.

• This requests permission for READ_CONTACTS run-time permission

• Required permissions must be added to AndroidManifest.xml as appropriate - see Android permissions: READ_CONTACTS, WRITE_CONTACTS, GET_ACCOUNTS

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

Parameters

• {Function} successCallback - The callback which will be called when operation is successful. The function is passed a single string parameter indicating whether access to contacts was granted or denied: cordova.plugins.diagnostic.permissionStatus.GRANTED or cordova.plugins.diagnostic.permissionStatus.DENIED
• {Function} errorCallback - The callback which will be called when an error occurs. The function is passed a single string parameter containing the error message.

Example usage

cordova.plugins.diagnostic.requestContactsAuthorization(function(status){
    if(status === cordova.plugins.diagnostic.permissionStatus.GRANTED){
        console.log("Contacts use is authorized");
    }
}, function(error){
    console.error(error);
});

isCalendarAuthorized()

Checks if the application is authorized to use the calendar.

Notes for Android:

• This is intended for Android 6 / API 23 and above. Calling on Android 5 / API 22 and below will always return TRUE as permissions are already granted at installation time.

Notes for iOS:

• This relates to Calendar Events (not Calendar Reminders)

  cordova.plugins.diagnostic.isCalendarAuthorized(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 calendar 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.isCalendarAuthorized(function(authorized){
    console.log("App is " + (authorized ? "authorized" : "denied") + " access to calendar");
}, function(error){
    console.error("The following error occurred: "+error);
});

getCalendarAuthorizationStatus()

Returns the calendar authorization status for the application.

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.

Notes for iOS:

• This relates to Calendar Events (not Calendar Reminders)

  cordova.plugins.diagnostic.getCalendarAuthorizationStatus(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.getCalendarAuthorizationStatus(function(status){
   if(status === cordova.plugins.diagnostic.permissionStatus.GRANTED){
       console.log("Calendar use is authorized");
   }
}, function(error){
    console.error("The following error occurred: "+error);
});

requestCalendarAuthorization()

Requests calendar authorization for the application.

Notes for iOS:

• Should only be called if authorization status is NOT_DETERMINED. Calling it when in any other state will have no effect and just return the current authorization status.
• When calling this function, the message contained in the NSCalendarsUsageDescription .plist key is displayed to the user; this plugin provides a default message, but you should override this with your specific reason for requesting access - see the iOS usage description messages section for how to customise it.
• This relates to Calendar Events (not Calendar Reminders)

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.
• This requests permission for READ_CALENDAR run-time permission
• Required permissions must be added to AndroidManifest.xml as appropriate -