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

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

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

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. You must then reload the add-in before you can run code that uses the device capabilities. For example, you can call window.location.reload() to reload your add-in. If the user had previously granted permission to access the requested device capabilities, false is returned in the asyncResult.value property. 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 the requested device capabilities, Office.AsyncResultStatus.Failed is returned in the asyncResult.status property.

Returns

void

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.

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. You must then reload the add-in before you can run code that uses the device capabilities. For example, you can call window.location.reload() to reload your add-in. If the user had previously granted permission to access the requested device capabilities, false is returned in the asyncResult.value property. 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 the requested device capabilities, Office.AsyncResultStatus.Failed is returned in the asyncResult.status property.

Returns

void

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