Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Edit improvements #19

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Edit improvements #19

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 42 additions & 42 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,34 +2,36 @@
[ ![Download](https://api.bintray.com/packages/onedrive/Maven/onedrive-picker-android/images/download.svg) ](https://bintray.com/onedrive/Maven/onedrive-picker-android/_latestVersion)
[![Build Status](https://travis-ci.org/OneDrive/onedrive-picker-android.svg)](https://travis-ci.org/OneDrive/onedrive-picker-android)

The picker is the fastest way to integrate your Android app with OneDrive and OneDrive for Business. It provides a set of Java APIs that your app can use to browse, select, open and save files in your user's OneDrive. When opening files from OneDrive, you can also get shareable links to files - great for sending to friends, coworkers, and relatives - and thumbnails of image and video files so you don't have to build them yourself.
The picker is the fastest way to integrate your Android app with OneDrive and OneDrive for Business. It provides a set of Java APIs that your app can use to browse, select, open and save files in your user's OneDrive. When opening files from OneDrive, you can also get shareable links to these files. Links are great for sharing files with friends, coworkers, and relatives. You can also get thumbnails of images and videos, so you don't have to build them yourself.

In this guide, we’ll show you how to get your app quickly [opening](#opening-files) and [saving files](#saving-files) to OneDrive. You can also follow along with our [open picker sample app](PickerSample) and [saver sample app](SaverSample).
In this guide, we’ll show you how to quickly get your app to [open](#open-files) and [save files](#save-files) on OneDrive. You can also follow along with our [open picker sample app](PickerSample) and [saver sample app](SaverSample).

![Preview of the OneDrive Picker in Action](images/android-picker-saver.png)

[Setup](#setup)
[Set up](#setup)

[Opening files](#opening-files)
[Open files](#open-files)

[Saving files](#saving-files)
[Save files](#save-files)

[Supported Android Versions](#supported-android-versions)


## Setup
## Set up

## Compile with the source code

The picker for Android is available as open source on GitHub and includes both open and save capabilities. You can either download the latest version directly or clone the repository:
The picker for Android is available as open source on GitHub, and includes both open and save capabilities. You can either download the latest version directly or clone the repository:

* [Download zip](https://github.com/OneDrive/onedrive-picker-android/archive/master.zip)
* `git clone https://github.com/OneDrive/onedrive-picker-android.git`

For information on configuring your environment to work with the sample applications or the picker SDK see [Configuring your Android Environment](http://developer.android.com/sdk/index.html).
Once you've downloaded the picker for Android, you must configure your environment to work with the sample. For information on configuring your environment to work with sample apps, see [Configuring your Android Environment](http://developer.android.com/sdk/index.html).

## Install AAR via Gradle

Install an Android Archive (AAR) file from Gradle.

```gradle
repositories {
jcenter()
Expand All @@ -42,27 +44,27 @@ dependencies {

### Get an App Id

Register your app [here] (https://account.live.com/developers/applications) to get an App ID (Client ID) to launch the picker.
You must register your app with Microsoft to launch the picker. Register your app [here](https://account.live.com/developers/applications) to get an App ID (Client ID).

### Building the library

#### Android Studio
1. Choose **Import Project...** or **Import Module...**, to import into an existing project.
2. Browse to the location where the SDK is saved and select the root *onedrive-picker-android*
3. If not already installed, follow prompts or go to the *Android SDK Manager* to install Android 4.4.2 (API 19) and associated build tools.
2. Browse to the location where you saved the SDK and select the root *onedrive-picker-android*.
3. If you haven't already installed the *Android SDK Manager*, follow the prompts to install Android 4.4.2 (API 19) and the associated build tools.

#### Eclipse
1. In Eclipse, go to **File** → **Import** → **General** → **Existing Projects into Workspace**.
2. Click **Browse..** to select *onedrive-picker-android*, where you saved the SDK, as your root directory. Make sure at minimum *OneDriveSDK* is checked.
3. If not already installed, from the *Android SDK Manager*, install Android 4.4.2 (API 19).
4. Right-click your project and select **Properties** and go to **Android** in the left side bar.
5. Click **Add..** in *Library* and select *OneDriveSDK* to link it to your project.
2. Click **Browse..** and select *onedrive-picker-android*, where you saved the SDK, as your root directory. Make sure to select the *OneDriveSDK* checkbox.
3. If you haven't already installed the *Android SDK Manager*, install Android 4.4.2 (API 19).
4. Right-click your project and choose **Properties**, then go to **Android** in the left side bar.
5. Click **Add..** in *Library* and choose *OneDriveSDK* to link it to your project.

## Opening files
## Open files

Your app needs to give the user a way to start opening files from OneDrive. This example sets up a click handler that launches the open picker from `onClick()`. In this case, the app is requesting a view-only sharing link type using `LinkType.WebViewLink`.
Your app needs to give the user a way to open files on OneDrive. This example sets up a click handler that launches the open picker. In the following code snippet, the app requests a view-only sharing link by using `LinkType.WebViewLink`.

**Be sure to replace APP_ID with your application's identifier**
**Be sure to replace APP_ID with your app ID**

```java
import android.view.View.OnClickListener;
Expand All @@ -83,16 +85,15 @@ private final OnClickListener mStartPickingListener = new OnClickListener() {
};
```

When the `onClick()` method is invoked, the picker is created and configured for the type of link requested by the user. Then the `startPicking()` method is invoked to launch the picking experience. If the user does not have the OneDrive app installed when `startPicking()` is invoked, they will be prompted to download the app and taken to the app store.
When the `onClick()` method is invoked, the picker is created and configured for the type of link requested by the user. Then the `startPicking()` method launches the user's file picking experience. If the user does not have the OneDrive app installed, they will be prompted to download the app from the app store.

### Link Types
The open picker can be configured to return a URL for the selected file in one of these
formats:
* `LinkType.DownloadLink` - A URL is returned that provides access for 1 hour directly to the contents of the file. You can use this URL to download the file into your application.
* `LinkType.WebViewLink` - A sharing link that provides a web preview of the file is created. The link is valid until the user deletes the shared link through OneDrive. Sharing links are not available for OneDrive for Business files.
### Link types
The open picker returns a URL for the selected file in one of these formats:
* `LinkType.DownloadLink` - A URL that provides download access to the contents of the file. The URL expires after one hour.
* `LinkType.WebViewLink` - A sharing link that provides a web preview of the file. The link is valid until the user deletes the shared link through OneDrive. Sharing links are not available for files on OneDrive for Business.

### Catching the Results
When the user has completed opening a file or has cancelled from the open picker, the `onActivityResult()` method will be called to handle the picker results. In this method you can catch the results and get access to the file selected by the user.
### Catching the results
When the user has completed opening a file, or has cancelled the open picker, the `onActivityResult()` method is called to handle the picker results. The following method catches the results and gets access to the file selected by the user.

```java
protected void onActivityResult(final int requestCode, final int resultCode, final Intent data) {
Expand All @@ -110,10 +111,10 @@ protected void onActivityResult(final int requestCode, final int resultCode, fin
}
```

If the user cancels picking a file, the result object will be null.
If the user cancels the file picker, the result object will be null.

### Picker Result Object
In addition to the filename and link for the file, you can access several other properties on the `IPickerResult` object that provide more details about the file selected:
In addition to the filename and link for the file, you can access several other properties on the `IPickerResult` object:

```java
public static class IPickerResult {
Expand All @@ -134,13 +135,15 @@ public static class IPickerResult {
}
```

Run the [open picker sample app](PickerSample) to see all of this in action.
Run the [open picker sample app](PickerSample) to see this in action.

## Save files

## Saving Files
Your app should provide a way for users to save files on OneDrive. In this code sample, `onClick()` creates a placeholder file named file.txt, located in the app's local folder. The file needs to have a filename and URI on the device to be pass into the saver. It then creates a saver, and `startSaving()` launches the OneDrive saver experience, allowing users to pick a file to upload. If the user does not have the OneDrive app installed, they will be prompted to download the app from the store.

Similar to when opening files, your app should provide a way for the user to save a file to OneDrive. In this code sample, a click handler is used to launch the saver from `onClick()`. Your app needs to have a filename and URI to the file on the device to pass into the saver. This sample code creates a placeholder file in the apps local folder named file.txt as an example.
The saver supports the `content://` and `file://` file URI scheme. If a different URI scheme is used, the saver will return a `NoFileSpecified` error. See below for details about the saver response.

**Be sure to replace APP_ID with your application's identifier**
**Be sure to replace APP_ID with your app ID**

```java
import android.view.View.OnClickListener;
Expand All @@ -166,13 +169,10 @@ private final OnClickListener mStartPickingListener = new OnClickListener() {
};

```
When the `onClick()` method is invoked, the saver is created and then the `startSaving()` method is invoked. This launches the OneDrive saver experience, allowing your users to pick a folder to upload the file. If the user does not have the OneDrive app installed when `startSaving()` is invoked, they will be prompted to download the app from the marketplace.

The saver currently supports the `content://` and `file://` file URI scheme. If a different URI scheme is used, the saver will return a `NoFileSpecified` error. See below for details about the saver response.

### Saver Result
### Saver result

When the user has finished saving a file, or if there was a problem saving, the `onActivityResult()` method will be called to handle the saver result. By using this method, you can check if the file was saved, and if not, you can catch the exception and handle the error.
When the user has finished saving a file, or if there was a problem saving, the `onActivityResult()` method is called to handle the saver result. By using this method, you can check if the file was saved, and if not, you can catch the exception and handle the error.

```java
protected void onActivityResult(final int requestCode, final int resultCode, final Intent data) {
Expand All @@ -187,12 +187,12 @@ protected void onActivityResult(final int requestCode, final int resultCode, fin
}

```
The error message provided by `getDebugErrorInfo()` is primarily for development and debugging and can change at any time. When handling errors, you can use `getErrorType()` to determine the general cause of the error.
The error message provided by `getDebugErrorInfo()` is primarily for development and debugging, and may change at any time. When handling errors, you use `getErrorType()` to determine the general cause of the error.


### Saver Error Types
### Saver error types

When the saver is unable to complete saving a file and throws an exception, it provides a `SaverError` through `getErrorType()` that indicates one of a set of possible error types.
The following error types are defined by `SaverError`:

```java
public enum SaverError {
Expand Down Expand Up @@ -222,12 +222,12 @@ public enum SaverError {

}
```
Run the [saver sample app](SaverSample) to see this all in action.
Run the [saver sample app](SaverSample) to see this in action.

## Supported Android Versions
The OneDrive picker library is supported at runtime for [Android API revision 14](http://source.android.com/source/build-numbers.html) and greater. To build the picker library you need to install Android API revision 19 or greater.

The picker requires the OneDrive app to be installed, in order to function. If the OneDrive app is not installed, the user will be prompted to download the app when either the `startPicking()` or `startSaving()` method is invoked.
You must install the OneDrive app to to use the picker. If the OneDrive app is not installed, the user will be prompted to download the app during the open or save experience.


## Contributing
Expand Down