cordova-diagnostic-plugin

The cordova.plugins.diagnostic.permissionStatus object contains constants used to represent the state of a requested permission.

Android States

• NOT_REQUESTED: App has not yet requested access.
• DENIED_ONCE: User denied access without checking "Never Ask Again". The app can request again.
• DENIED_ALWAYS: User denied access and checked "Never Ask Again". The app cannot request again via dialog; the user must manually change settings.
• GRANTED: User granted access (or device is Android 5.x or below).

Note: The plugin uses HTML5 local storage to distinguish between NOT_REQUESTED and DENIED_ALWAYS on Android, as the native API returns the same value for both. Clearing local storage will reset this distinction.

iOS States

• NOT_REQUESTED: App has not yet requested access.
• DENIED_ALWAYS: User denied access. Manual settings change required.
• RESTRICTED: Permission is unavailable (e.g., due to parental controls).
• GRANTED: Permission granted.
• GRANTED_WHEN_IN_USE: (Location only) Permission granted for foreground use only.
• PROVISIONAL: (Notifications only) Provisionally authorized for non-interruptive notifications.
• EPHEMERAL: (Notifications only) Authorized for a limited time.

Common States

• UNKNOWN: Returned when the OS has not yet provided a concrete status (e.g., a timeout). Treat this as transient and retry.

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

On Android, only one permission request can be active at a time. If you attempt to make a second request while one is already in progress, the plugin will trigger the error callback.

To handle this, use isRequestingPermission() to check the current state. If a request is active, you can use registerPermissionRequestCompleteHandler() to wait for it to finish before starting your own request.

Methods:

• isRequestingPermission(): Returns true if a request is currently in progress.
• registerPermissionRequestCompleteHandler(successCallback): Registers a callback for when a request completes. Pass null to de-register the handler.

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

On Android 11+, users can select "Only this time", which grants permission for the current session but revokes it upon app restart. Because Android's programmatic state for a revoked permission is the same as a permission never requested (NOT_REQUESTED/DENIED_ALWAYS), the plugin may incorrectly report DENIED_ALWAYS due to its internal tracking.

Workaround: If the device is running Android 11+ (API level 30+) and the status is DENIED_ALWAYS, you should treat it as DENIED_ONCE and attempt to request it again, as the user might have simply selected the temporary option in the previous session.

let diagnostic, deviceOS;
let cameraDeniedAlwaysAfterRequesting = false;

function onDeviceReady(){
    diagnostic = cordova.plugins.diagnostic;
    diagnostic.getDeviceOSVersion(function(osDetails){
        deviceOS = osDetails;
        checkCameraPermission();
    })
}

function checkCameraPermission(){
    diagnostic.getPermissionAuthorizationStatus(function(status){

        // Workaround for Android 11+ 'Only this time' option
        if(deviceOS.apiLevel >= 30 && status === diagnostic.permissionStatus.DENIED_ALWAYS && !cameraDeniedAlwaysAfterRequesting){
            status = diagnostic.permissionStatus.DENIED_ONCE;
        }

        switch(status){
            case diagnostic.permissionStatus.GRANTED:
                console.log("Camera permission is allowed")
                break;
            case diagnostic.permissionStatus.NOT_REQUESTED:
                console.log("Camera permission not requested yet - requesting...")
                requestCameraPermission();
                break;
            case diagnostic.permissionStatus.DENIED_ONCE:
                console.log("Camera permission denied but can still request - requesting...")
                requestCameraPermission();
                break;
            case diagnostic.permissionStatus.DENIED_ALWAYS:
                console.log("Camera permission permanently denied - can't request");
                break;
        }
    }, console.error, diagnostic.permission.CAMERA)
};

function requestCameraPermission(){
    diagnostic.requestRuntimePermission(function(status){
        if(status === diagnostic.permissionStatus.DENIED_ALWAYS){
            cameraDeniedAlwaysAfterRequesting = true;
        }
        checkCameraPermission();
    }, console.error, diagnostic.permission.CAMERA);
}

document.addEventListener("deviceready", onDeviceReady, false);

The plugin is split into optional functional modules. To avoid installing redundant code, you can specify exactly which modules you need via a <preference> in your config.xml.

Important: You must add the preference to config.xml before installing the plugin. If you need to change modules after installation, you must uninstall and re-install the plugin.

1. Add preference to config.xml

Use the cordova.plugins.diagnostic.modules preference with a space-separated list of capitalized module names.

To include only specific modules:

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

To install only the core module (no optional modules):

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

2. Re-install the plugin

If the plugin is already installed, run:

cordova plugin rm cordova.plugins.diagnostic --nosave && cordova plugin add cordova.plugins.diagnostic --nosave

Supported Modules

• LOCATION (Android & iOS)
• BLUETOOTH (Android & iOS)
• WIFI (Android & iOS)
• CAMERA (Android & iOS)
• NOTIFICATIONS (Android & iOS)
• MICROPHONE (Android & iOS)
• CONTACTS (Android & iOS)
• CALENDAR (Android & iOS)
• REMINDERS (iOS only)
• MOTION (iOS only)
• NFC (Android only)
• EXTERNAL_STORAGE (Android only)

On iOS 14+ and Android 12+, users can grant location access with reduced accuracy. Use these methods to manage and check that state.

Check current accuracy: Use getLocationAccuracyAuthorization() to get the current state from locationAccuracyAuthorization constants.

Request temporary full accuracy (iOS 14+ only): If your app has been granted reduced accuracy but needs high-accuracy GPS (e.g., for navigation), call requestTemporaryFullAccuracyAuthorization(purpose, successCallback, errorCallback).

Requirements for iOS: You must define a purpose key in your *-Info.plist under NSLocationTemporaryUsageDescriptionDictionary.

Example config.xml setup:

<platform name="ios">
  <config-file target="*-Info.plist" parent="NSLocationTemporaryUsageDescriptionDictionary">
    <dict>
      <key>navigation</key>
      <string>This app requires access to your exact location in order to provide SatNav route navigation.</string>
    </dict>
  </config-file>
</platform>

cordova.plugins.diagnostic.requestTemporaryFullAccuracyAuthorization("navigation", function(accuracyAuthorization){
    switch(accuracyAuthorization){
        case cordova.plugins.diagnostic.locationAccuracyAuthorization.FULL:
            console.log("Full accuracy authorized");
            break;
        case cordova.plugins.diagnostic.locationAccuracyAuthorization.REDUCED:
            console.log("Full accuracy denied");
            break;
    }
}, function(error){
    console.error(error);
});