Guidelines for accessing OneDrive from an app

Applies to Windows and Windows Phone

Follow these guidelines for designing a Windows Store app that interacts with a Microsoft OneDrive user's files, documents, pictures, videos, folders, albums, or comments.

Dos and don'ts

Users of OneDrive assume that Microsoft works to help protect the security and privacy of their data. They rely on OneDrive to help preserve their important documents, to save their photos, and to share their experiences with friends. Your app can enhance the value of OneDrive for users by providing considerate, well-designed access to their data.

To maintain the trust that users have in OneDrive, have your app follow these design principles.

Let the user opt in

Users want to choose how apps handle their data. They expect an app to ask their permission before connecting to their account. They want to be notified before their data is changed. To meet their expectations, follow these practices:

  • Upload files to OneDrive only in response to an explicit user request or choice.

    An app that connects to OneDrive should include a button that allows users to intentionally upload their files to OneDrive. If your app syncs files to OneDrive as its default, make the user aware of this and provide the opportunity to opt in before any data is saved.

  • Sign users into and out of their account using the Account charm.

    As explained in Signing users into and out of their Microsoft account, your app must give users a way to actively sign into and out of their Microsoft account. (Keep in mind that, if the user has signed into Windows with their Microsoft account, your app can't explicitly sign them out.)

    For more info, see Guidelines for the Microsoft account sign-in experience.

  • Access only files that are owned by the signed-in user.

    Unless your app is meant for sharing files between OneDrive users, ensure it accesses only the signed-in user's files. Your app should access files and folders that have been shared with the user only if the user asks to do so. Conversely, your app should not save files to shared folders unless the user chooses to.

  • Give users a choice about where they want data stored in their OneDrive.

    Your app can use the Windows file picker by using the Windows.Storage.Pickers namespace for opening and saving files to the user's OneDrive. If your app syncs multiple files, consider creating a uniquely named subfolder in the user's folders.

    For more info about how to use a file picker when opening a file from OneDrive, see Folders and files.

Help protect the user's data and privacy

Your app must not undermine the user's trust in their OneDrive. Handle user data discretely. Users assume that their files are shared only with people whom they select. Their important info must be preserved so that they can return to it when they need it.

Important  Once set, your app cannot change the permissions set on a OneDrive object programmatically.

  • Upload files to OneDrive with user-only access as the default.

    Share files with others only if the user specifically requests that the files be shared.

  • Warn the user about sharing links to files with others.

    When users request to share a link to their files, have your app inform them about the consequences of sharing. In particular, if your app allows users to share preauthenticated links to their files, tell them that anyone who received the link can view the files. File permissions are not evaluated for these links and anyone who opens the links can view the content.

    For more info, see OneDrive core concepts.

  • Create links to OneDrive objects intentionally, based upon the use of the link.

    Whenever possible, share embedded, read-only, and read-write links. These links work only for users who have permission to view the file. Provide pre-authenticated links to files only when the user wants to share a folder or file with specific people. File permissions are not evaluated for these links and anyone who opens the links can view the content.

    For more info, see OneDrive core concepts.

  • Alert the user when overwriting an existing file.

    When uploading a file to OneDrive, the default behavior for upload is to overwrite any existing file with the same name. Let the user know that an existing file is going to be overwritten if a conflict occurs. You can add an Overwrite header set to 'false' to prevent a file from being overwritten.

Use OneDrive and Windows as intended

It's tempting to use the storage that's freely available through OneDrive as a catch-all cloud-data solution. Even though it does present a lot of options for a Windows Store app, OneDrive provides the most benefit to your app when used as intended. OneDrive is designed to provide users with access to their documents, photos, and other important info from any device.

  • Use OneDrive for storing, viewing, editing documents, or creating and sharing photo albums.

    OneDrive is not intended as an alternative for storing scalable databases, sharing configuration files, or hosting web applications (as a few examples). It is meant solely for the easy storage and sharing of a user's discrete files.

  • Ensure that the user has space in their OneDrive before uploading a file.

    Each OneDrive user has a limited amount of storage available. If your app attempts to save a file that pushes the user's account over its allotted quota, the call returns an error. It is a best practice to check users' available storage before saving a file to their OneDrive.

    For more info about how to check the available space in OneDrive, see Common tasks.

  • Use the built-in Windows features.

    Whenever possible, use the Windows features and UI to host or interact with OneDrive. For instance, use the file picker provided by the Windows.Storage.Pickers namespace for opening and saving files. As another example, have your app use the Windows application data APIs to save smaller pieces of data across a user's devices.

    For more info about how to use a file picker to open a file from OneDrive, see Folders and files.

    For more info about how to use the Windows application data APIs, see Guidelines for roaming application data and Quickstart: Roaming application data.

Additional usage guidance

OneDrive provides users with a trustworthy and accessible place to store their files in the cloud. Users can access their OneDrive files from any Windows device by signing in with their Microsoft account. OneDrive gives users 7 gigabytes (GB) of free storage that they can use to save and share their photos, documents, videos, and audio files.

Your Windows Store app can provide users with access to the files and folders in their OneDrive. With the connection to OneDrive, your app gives users the ability to open, read, save, and download files from their OneDrive without cluttering their hard drive. The OneDrive APIs are designed to be used from within a Windows Store app and integrate smoothly into your app's design.

App designs for using OneDrive

In a broad sense, OneDrive can play a role for any app that interacts with discrete files. If your app reads or displays files, saves files, or downloads or opens files, you can add OneDrive to the app's design. OneDrive integrates well into the architecture of your Windows Store app, making use of the built-in features of Windows without requiring you to write a lot of extra code.

Important  The OneDrive APIs are in the Live Connect SDK. Before you start developing a Windows Store app that connects to OneDrive, you need to install the Live Connect SDK and add a reference to the SDK in your project.

Signing users into and out of their Microsoft account

Of course, any app that interacts with OneDrive must provide the user with a way to sign in and sign out of the Microsoft account associated with OneDrive. While not an app design in itself, signing users into their account is a critical step in building an app that integrates with OneDrive.

The recommended technique for signing users in is to create an Accounts page and a Privacy statement page in your app's Settings charm. The Accounts page should provide a sign-in and sign-out button that signs users in and out of their account. The WindowsUI handles the rest of the sign-in process for your app.

To learn more, see these resources:

Saving new files or updating existing files in OneDrive

For some users, OneDrive is their 'My Documents'. For users who prefer to use OneDrive for storing their files, your app can provide the option to save their data in OneDrive. For example, when they create new files in your app, you can offer OneDrive as a location to save. When they edit files in your app, they can save the edits back to their OneDrive.

Realistically, any app that lets users to create new files can benefit from giving users access to OneDrive.

  • For guidelines on how to build an app that integrates with OneDrive, see the dos and don'ts section.
  • For more info about how to upload pictures, videos, and audio files from a user's OneDrive, see Albums, photos, videos, audio, and tags.
  • For more info about how to save and update a file in a user's OneDrive, see Folders and files.

Downloading, opening, and viewing files from OneDrive

As we noted earlier, some users keep a lot of their data in the cloud. They expect to be able to view the data contained there. Your app can give users the option to open and read files from OneDrive. The app can download, open, and display the contents of the file for the user to view.

For example, if your app plays videos, you can give users the ability to open movies from their OneDrive folders. Or your app can let users open and view a specific file type, as a reader.

Note  We recommend that your Windows Store app do more than just allow users to view the files contained in their OneDrive. Windows comes with a OneDrive app. Users are more likely to download and install your app if it provides them with a unique experience.

To learn more, have a look at these resources:

  • For guidelines on how to build an app that integrates with OneDrive, see the dos and don'ts.
  • For more info about how to download and view pictures, videos, and audio files from a user's OneDrive, see Albums, photos, videos, audio, and tags.
  • For more info about how to download and open a file from a user's OneDrive, see Folders and files.

Related topics

For designers
OneDrive API
OneDrive core concepts
For developers (HTML)
OneDrive for Developers
Common tasks
Folders and files
JavaScript API
For developers (XAML)
OneDrive for Developers
Folders and files
Managed API

 

 

Show:
© 2014 Microsoft