Office.DevicePermission interface

Requests permission from a user to access their device capabilities, such as a camera or microphone.

All the requested permissions are displayed in a single modal dialog to the user. The dialog includes options to Allow, Allow once, or Deny the requested permissions.

This method returns a promise. Use it with Excel, PowerPoint, and Word add-ins.

If a user grants access to a device capability for the first time, the promise resolves with true. You must then reload the add-in before you can run code that uses the device capability. For example, you can call window.location.reload() to reload your add-in. If a user had previously granted access to a device capability, the promise resolves with false. You don't need to reload your add-in to run code that uses the device capability, as the permission is already set. If a user denies access to a device capability, the promise rejects with a "User denied the permission request" error message.

requestPermissions(permissions: Office.DevicePermissionType[]): Promise<boolean>;

Parameters

Returns

Remarks

Important:

• This method isn't supported in Outlook add-ins. Use the requestPermissionsAsync method instead.

• If your add-in uses the same code for both Office on the web and Office desktop clients, verify the platform on which the add-in is running before calling requestPermissions. Use Office.context.platform and verify that it returns Office.PlatformType.OfficeOnline. Otherwise, the requestPermissions call will return an error.

• If a user selects Allow from the dialog, the permission persists until the add-in is uninstalled or until the cache of the browser on which the add-in is running is cleared. If a user wants to change an add-in’s access to their camera or microphone, they must uninstall the add-in or clear their browser cache.

• If a user selects Allow Once from the dialog, the permission persists until the browser tab or window in which the add-in is running is closed.

• If a user selects Deny from the dialog, the user will be requested for permissions again the next time the add-in requires access to the user's device capabilities.

Examples

// Request permission from a user to access their camera and microphone.
if (Office.context.platform === Office.PlatformType.OfficeOnline) {
    const deviceCapabilities = [
        Office.DevicePermissionType.camera,
        Office.DevicePermissionType.microphone
    ];
    Office.devicePermission
        .requestPermissions(deviceCapabilities)
        .then((isGranted) => {
            if (isGranted) {
                console.log("Permission granted.");
                // Reload your add-in before you run code that uses the device capabilities.
                location.reload();
            } else {
                console.log("Permission has been previously granted and is already set in the iframe.");

                // Since permission has been previously granted, you don't need to reload your add-in.

                // Do something with the device capabilities.
            }
        })
        .catch((error) => {
            console.log("Permission denied.");
            console.error(error);

            // Do something when permission is denied.
        });
}

Requests permission from a user to access their device capabilities, such as a camera, geolocation, or microphone.

All the requested permissions are displayed in a single modal dialog to the user. The dialog includes options to Allow, Allow once, or Deny the requested permissions.

This method accepts a callback function. Use it with Outlook add-ins.

requestPermissionsAsync(permissions: Office.DevicePermissionType[], options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<boolean>) => void): void;

Parameters

Returns

Remarks

Important:

• For Excel, PowerPoint, and Word add-ins, use the requestPermissions method instead.

• If your add-in uses the same code for both Office on the web and Office desktop clients, verify the platform on which the add-in is running before calling requestPermissionsAsync. Use Office.context.mailbox.diagnostics.hostName and verify that it returns OutlookWebApp. Otherwise, the requestPermissionsAsync call will return an error.

• If a user selects Allow from the dialog, the permission persists until the add-in is uninstalled or until the cache of the browser on which the add-in is running is cleared. If a user wants to change an add-in’s access to their camera or microphone, they must uninstall the add-in or clear their browser cache.

• If a user selects Allow Once from the dialog, the permission persists until the browser tab or window in which the add-in is running is closed.

• If a user selects Deny from the dialog, the user will be requested for permissions again the next time the add-in requires access to the user's device capabilities.

• If your add-in implements event-based activation, browser permissions to device capabilities aren't inherited and the requestPermissionsAsync method isn't supported.

Requests permission from a user to access their device capabilities, such as a camera, geolocation, or microphone.

All the requested permissions are displayed in a single modal dialog to the user. The dialog includes options to Allow, Allow once, or Deny the requested permissions.

This method accepts a callback function. Use it with Outlook add-ins.

requestPermissionsAsync(permissions: Office.DevicePermissionType[], callback: (asyncResult: Office.AsyncResult<boolean>) => void): void;

Parameters

Returns

Remarks

Important:

• For Excel, PowerPoint, and Word add-ins, use the requestPermissions method instead.

• If your add-in uses the same code for both Office on the web and Office desktop clients, verify the platform on which the add-in is running before calling requestPermissionsAsync. Use Office.context.mailbox.diagnostics.hostName and verify that it returns OutlookWebApp. Otherwise, the requestPermissionsAsync call will return an error.

• If a user selects Allow from the dialog, the permission persists until the add-in is uninstalled or until the cache of the browser on which the add-in is running is cleared. If a user wants to change an add-in’s access to their camera or microphone, they must uninstall the add-in or clear their browser cache.

• If a user selects Allow Once from the dialog, the permission persists until the browser tab or window in which the add-in is running is closed.

• If a user selects Deny from the dialog, the user will be requested for permissions again the next time the add-in requires access to the user's device capabilities.

• If your add-in implements event-based activation, browser permissions to device capabilities aren't inherited and the requestPermissionsAsync method isn't supported.

Examples

// Request permission from a user to access their camera, geolocation, and microphone.
if (Office.context.mailbox.diagnostics.hostName === "OutlookWebApp") {
    const deviceCapabilities = [
        Office.DevicePermissionType.camera,
        Office.DevicePermissionType.geolocation,
        Office.DevicePermissionType.microphone
    ];

    Office.devicePermission.requestPermissionsAsync(deviceCapabilities, (asyncResult) => {
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
            console.log("Permission denied.");

            // Do something when permission is denied.
        } else {
            if (asyncResult.value) {
                console.log("Permission granted.");
                // Reload your add-in before you run code that uses the device capabilities.
                location.reload();
            } else {
                console.log("Permission has been previously granted and is already set in the iframe.");
                
                // Since permission has been previously granted, you don't need to reload your add-in.

                // Do something with the device capabilities.
            }
        }
    });
}