Office.DevicePermission interface

Package:

office

Provides methods for an add-in to request permission from a user to access their device capabilities. A user's device capabilities include their camera, geolocation, and microphone.

Remarks

Applications: This API is supported by the following Office applications when running in Chromium-based browsers, such as Microsoft Edge and Google Chrome.

• Excel on the web

• Outlook on the web

• PowerPoint on the web

• Word on the web

It's also supported in new Outlook on Windows (preview).

Requirement set: DevicePermission 1.1

Methods

requestPermissions(permissions)	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.
requestPermissionsAsync(permissions, options, callback)	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, callback)	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.

Method Details

requestPermissions(permissions)

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.

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

Parameters

permissions

Office.DevicePermissionType[]

An array of device capabilities to which an add-in is requesting access. In web versions of Excel, PowerPoint, and Word, add-ins can only request access to a user's camera and microphone. Access to a user's geolocation is blocked.

Returns

Promise<boolean>

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 the user allows access to their camera or microphone, the add-in must be reloaded in the browser for the permissions to take effect. For example, you can call window.location.reload() to reload your add-in.

• 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.");

                // Do something when permission is granted.
            } else {
                console.log("Permission denied.");

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

requestPermissionsAsync(permissions, options, callback)

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

permissions

Office.DevicePermissionType[]

An array of device capabilities to which an add-in is requesting access. In Outlook on the web, an add-in can request access to a user's camera, geolocation, and microphone.

options

Office.AsyncContextOptions

An object literal that contains the asyncContext property. Assign any object you wish to access in the callback function to the asyncContext property.

callback

(asyncResult: Office.AsyncResult<boolean>) => void

When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an Office.AsyncResult object. If the user grants permission to access the requested device capabilities, true is returned in the asyncResult.value property.

Returns

void

Remarks

Important:

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

• If the user allows access to their camera, geolocation, or microphone, the add-in must be reloaded in the browser for the permissions to take effect. For example, you can call window.location.reload() to reload your add-in.

• 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.

requestPermissionsAsync(permissions, callback)

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

permissions

Office.DevicePermissionType[]

An array of device capabilities to which an add-in is requesting access. In Outlook on the web, an add-in can request access to a user's camera, geolocation, and microphone.

callback

(asyncResult: Office.AsyncResult<boolean>) => void

When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an Office.AsyncResult object. If the user grants permission to access the requested device capabilities, true is returned in the asyncResult.value property.

Returns

void

Remarks

Important:

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

• If the user allows access to their camera, geolocation, or microphone, the add-in must be reloaded in the browser for the permissions to take effect. For example, you can call window.location.reload() to reload your add-in.

• 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 (asyncResult.error.message);
            return;
        }

        if (asyncResult.value) {
            console.log("Permission granted.");

            // Do something when permission is granted.
        } else {
            console.log("Permission denied.");

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