Box Android SDK

Building

Eclipse

The Android SDK depends on the Box Java SDK, so you must first import it into your workspace and make sure it builds. Import the Android SDK second and make the Java SDK a build dependency.

Ant

First clone the Box Java SDK and follow the instructions in its readme on how to build it. Copy the the built BoxJavaLibraryV2.jar to BoxAndroidLibraryV2/libs. You can then use Ant to build the project like you would with any other Android library. The simplest way to do this is by running ant debug.

Gradle (Experimental)

There is also experimental support for Gradle, allowing you to use the SDK with Android Studio. You must have Gradle 1.6 installed.

Before the Android SDK can be built, you must first install the Box Java SDK to your local Maven repository. This can be done by following the Gradle build instructions included in the Java SDK's readme.

The Android SDK also depends on the Android Support Library. Unfortunately, telling Gradle to look for the android-support JAR directly will likely result in dex merge conflicts if more than one project uses the support library. The easiest way to get around this is by also installing android-support-v4.jar to your local Maven repo. Run the following command, where $ANDROID_HOME points to your Android SDK root (you must have Maven installed).

mvn install:install-file \
-Dfile=$ANDROID_HOME/extras/android/support/v4/android-support-v4.jar \
-DgroupId=com.google.android \
-DartifactId=support-v4 \
-Dversion=r13 \
-Dpackaging=jar

You can now run gradle build to build the SDK. However, building the library by itself isn't very useful. To reference the SDK from another Android Gradle project, add the following to your list of dependencies:

dependencies {
	...
	compile project(':box-android-sdk-private:BoxAndroidLibraryV2')
}

You can refer to the Android Gradle guide on multi project setups here .

API Calls Quickstart

Authenticate

Authenticate the client with OAuth. See the authentication section below for more information.

boxClient.authenticate(oAuthView, autoRefreshToken, listener);

Our sdk auto refreshes OAuth access token when it expires. You will want to listen to the refresh events and update your stored token after refreshing.

boxClient.addOAuthRefreshListener(OAuthRefreshListener listener) {
    new OAuthRefreshListener() {
        @Override
        public void onRefresh(IAuthData newAuthData) {
            // TODO: save the auth data.
        }						       
    }
}

After you exit the app and return back, you can use the stored oauth data to authenticate:

boxClient.authenticate(loadStoredAuthData);

Get Default File Info

BoxFile boxFile = boxClient.getFilesManager().getFile(fileId, null);

Get Additional File Info

Get default file info plus its description and SHA1.

BoxDefaultRequestObject requestObj =
  (new BoxDefaultRequestObject()).addField(BoxFile.FIELD_SHA1);
  	.addField(BoxFile.FIELD_DESCRIPTION);
BoxFile boxFile = boxClient.getFilesManager().getFile(fileId, requestObj);

Get Folder Children

Get 30 child items, starting from the 20th one, requiring etag, description, and name to be included.

BoxFolderRequestObject requestObj = 
	BoxFolderRequestObject.getFolderItemsRequestObject(30, 20)
		.addField(BoxFolder.FIELD_NAME)
		.addField(BoxFolder.FIELD_DESCRIPTION)
		.addField(BoxFolder.FIELD_ETAG);
BoxCollection collection = 
	boxClient.getFoldersManager().getFolderItems(folderId, requestObj);

Upload a New File

BoxFileUploadRequestObject requestObj = 
	BoxFileUploadRequestObject.uploadFileRequestObject(parent, "name"�, file);
BoxFile bFile = boxClient.getFilesManager().uploadFile(requestObj);

Upload a File with a Progress Listener

BoxFileUploadRequestObject requestObj = 
	BoxFileUploadRequestObject.uploadFileRequestObject(parent, "name", file)
		.setListener(listener));
BoxFile bFile = boxClient.getFilesManager().uploadFile(requestObj);

Download a File

boxClient.getFilesManager().downloadFile(fileId, null);

Delete a File

Delete a file, but only if the etag matches.

BoxFileRequestObject requestObj =
	BoxFileRequestObject.deleteFileRequestObject().setIfMatch(etag);
boxClient.deleteFile(fileId, requestObj);

Authentication

You can find a full example of how to perform authentication in the sample app.

Basic Authentication

The easiest way to authenticate is to use the OAuthActivity, which is included in the SDK. Add it to your manifest to use it.

Intent intent = OAuthActivity.createOAuthActivityIntent(this, clientId, 
	clientSecret);
startActivityForResult(intent);

@Override
public void onActivityResult(int requestCode, int resultCode, Intent data) {
	if (resultCode == Activity.RESULT_CANCELED) {
		// Get the error message for why authentication failed.
		String failMessage = data.getStringExtra(OAuthActivity.ERROR_MESSAGE);
		// Implement your own logic to handle the error.
	   handleFail(failMessage);
	} else {
		// You will get an authenticated oath token object back upon success.
		BoxAndroidOAuthData oauth = data.getParcelableExtra(OAuthActivity.BOX_CLIENT_OAUTH);
                BoxAndroidClient client = new BoxAndroidClient(clientId, clientSecret, null, null);
                client.authenticate(oauth);
		youOwnMethod(client);
	}
}

Advanced Authentication

Alternatively, you can use your own custom login activity with a WebView for authentication.

oauthView = (OAuthWebView) findViewById(R.id.oauthview);
oauthView.initializeAuthFlow(this, clientId, clientSecret);
boxClient.authenticate(oauthView, autoRefreshOAuth, getOAuthFlowListener());

// Create a listener listening to OAuth flow. The most important part you need
// to implement is onAuthFlowEvent and catch the OAUTH_CREATED event. This event
// indicates that the OAuth flow is done, the BoxClient is authenticated and
// that you can start making API calls. 
private OAuthWebViewListener getOAuthFlowListener() {
	return new OAuthWebViewListener() {
		@Override
		public onAuthFlowEvent(final IAuthEvent event,
			final IAuthFlowMessage message) {

			// Authentication is done, you can start using your BoxClient
			// instance.
		}
	}
}

// You can get a BoxOAuthToken and use it to authenticate the client at a later
// time or in a different activity.
BoxOAuthToken oauthObject = boxClient.getAuthData();

// Re-authenticate using the previously obtained OAuth object.
boxClient.authenticate(oauthObject);