Opening Files with the OneDrive File Picker JavaScript SDK v7.0

Note: This version has been replaced by file picker v7.2. New integrations should use the latest version of the file picker SDK.

The following walkthrough shows how to integrate the file picker SDK into your client-side JavaScript application.

Open demo

1. Register your application

To use the OneDrive picker, you need to register your application through the Microsoft Application Registration Portal and receive an Application Id. You also need to add a valid redirect URI for your web application using the picker. This can either be the page hosting the picker SDK or a custom URL you define. For more information see Setting up.

2. Add a reference to the SDK

Embed the OneDrive JavaScript SDK into your page.

<script type="text/javascript" src="https://js.live.net/v7.0/OneDrive.js"></script>

3. Launch the file picker

To open files from OneDrive, your app should provide a button to programmatically open the OneDrive file picker. Because this code will launch a pop-up window in the browser, it needs to be called as part of an explicit user action to avoid being blocked by a pop-up blocker.

As part of the OneDrive.open(...) method, you specify the options for how the picker should behave and how the picker will call back to your code through and options object.

<script type="text/javascript">
  function launchOneDrivePicker(){
    var odOptions = { /* ... specify the desired options ... */ };
    OneDrive.open(odOptions);
  }
</script>
<button onClick="launchOneDrivePicker">Open from OneDrive</button>

Picker options

You can specify how the file picker behaves by providing an object with parameters that control the picker's behavior. This object also includes the callback functions for when the file picker is finished or encounters an error.

Example file picker options

var odOptions = {
  clientId: "INSERT-APP-ID-HERE",
  action: "share | download | query",
  multiSelect: true,
  openInNewWindow: true,
  advanced: {},
  success: function(files) { /* success handler */ },
  cancel: function() { /* cancel handler */ },
  error: function(e) { /* error handler */ }
}

Parameters

Parameter name Description
clientId The application ID generated by the app registration console for your integration.
action The action type being performed with the files selected. You can specify share to generate a sharable URL, download to receive a short-lived URL that downloads the content of the files, or query to return identifiers that can be used with the Microsoft Graph API or OneDrive API.
multiSelect The default value is false, which requires the user to select a single file only, or true to enable the user to select multiple files.
openInNewWindow The default value is true, which opens the OneDrive picking experience in a popup window, or false opens the OneDrive picking experience in the same window.
advanced A collection of additional properties which can further customize the behavior of the picker, but are not necessary for most scenarios. See Advanced Scenarios for more details.
success Called when the user finishes picking files and takes a response object that includes the collection of selected files. This is required if openInNewWindow is true.
cancel Called if the user cancels the picker. This function takes no parameters.
error Called when an error occurred on the server or the user doesn't have permission to get a link to the chosen file. This function takes one parameter, an error object.

Note: If openInNewWindow is false, then all callback functions must be declared globally on the page before the SDK is referenced to guarantee the functions will be called. When registered globally the callback function names are renamed with a prefix of oneDriveFilePicker. For example, success becomes oneDriveFilePickerSuccess.

Types of actions

Using the picker SDK's action parameter you can specify which type of URL should be returned after the user selects a file or folder. The following values are allowed:

Value Description
download Returns a short-lived download URL for the selected files.
share Returns a read-only sharing URL for the selected files that can be shared with other users.
query Returns metadata only for the selected files. Use the API to perform additional actions on the files accordingly.

4. Handling the picker response object

When the user is done picking file(s), the success callback receives response object. This object contains properties, include value property which is a collection of driveItem resources with a subset of the item's properties.

For OneDrive Personal, when multiple files are selected and a sharing link is requested, the response object also includes a webUrl property on the root object. This is a URL points to a webpage that shows all of the selected files.

{
  "webUrl": "https://1drv.ms/link/to/selected/files/page",
  "value": [
    {
      "id": "123456",
      "name": "document1.docx",
      "size": 12340,
      "@microsoft.graph.downloadUrl": "https://contoso-my.sharepoint.com/download.aspx?guid=1231231231a",
      "webUrl": "https://cotoso-my.sharepoint.com/personal/user_contoso_com/documents/document1.docx",
      "thumbnails": [
        {
          "id": "0",
          "small": { "url": "https://sn3302files.onedrive.live.com/..." },
          "medium": { "url": "https://sn3302files.onedrive.live.com/..." },
          "large": { "url": "https://sn3302files.onedrive.live.com/..." }
        }
      ]
    }
  ]
}

Advanced open scenarios

The picker also supports additional advanced scenarios through the query action. This allows the picker to be used alongside the OneDrive API to accomplish advanced scenarios.

The advanced parameter on the options object has the following defined properties:

Parameter name Description
queryParameters A set of additional query parameters as specified by the OneDrive API that define how an item is returned. This typically includes a select and/or expand value.
createLinkParameters Change the parameters used to generate a link for the share action.
redirectUri By default the picker uses the page it was launched from as the redirect uri for authentication. This may not be desirable in all scenarios, so you can set a custom URL to use instead. This URL must be in the same root domain and use the same protocol as the page hosting the picker SDK. The target page must reference the OneDrive Picker SDK in the same fashion as the calling page.
filter A set of file types could be applied to display the specific types only. We support system type 'photo' and 'folder', and custom types of any extension like '.docx'. One applicable filter setting is "folder,.png" which each filter is separated by a ,.

Note: Currently filter type 'photo' is only supported in OneDrive Personal UI.

Using the Picker and API together

You can use the action value query along with setting the queryParameters of the advanced object to return a custom set of properties from the API about the selected object. For example, when a file is picked, to include photo details (if available):

var odOptions = {
  clientId: "INSERT-APP-ID-HERE",
  action: "query",
  multiSelect: false,
  advanced: {
    queryParameters: "select=id,name,size,file,folder,photo,@microsoft.graph.downloadUrl",
    filter: "folder,.png" /* display folder and files with extension '.png' only */
  },
  success: function(files) { /* success handler */ },
  cancel: function() { /* cancel handler */ },
  error: function(e) { /* error handler */ }
}

This tells the picker SDK to select the id, name, size, file, folder, and photo properties in the response.

By default the OneDrive file picker returns a view-only sharing URL when action is set to share. However you can use the createLinkParameters property to change the parameters passed to the createLink action.

var odOptions = {
  clientId: "INSERT-APP-ID-HERE",
  action: "share",
  multiSelect: false,
  advanced: {
    createLinkParameters: { type: "edit", scope: "organization" }
  },
  success: function(files) { /* success handler */ },
  cancel: function() { /* cancel handler */ },
  error: function(e) { /* error handler */ }
}

Using a custom redirect URI

If your app is a large client-side JavaScript app or uses query string parameters to maintain state, it may not be desirable to use the page launching the file picker as the redirect URI. This requires that your whole app is reloaded inside the popup window, which may cause performance issues. You can specify an alternative redirect URI through the advanced object which is used instead.

var odOptions = {
  clientId: "INSERT-APP-ID-HERE",
  action: "download",
  openInNewWindow: true,
  advanced: {
    redirectUri: "https://contoso.com/filePickerRedirect.htm"
  },
  success: function(files) { /* success handler */ },
  cancel: function() { /* cancel handler */ },
  error: function(e) { /* error handler */ }
}

The page you redirect to needs only to load the OneDrive SDK script:

<html>
<script type="text/javascript" src="https://js.live.net/v7.0/OneDrive.js"></script>
</html>

Note: you can only provide a custom redirect URI when using file picker as a popup window (openInNewWindow is true). When using the inline experience the default redirect URI is always used.