Scribd
Upload
54 views5 pages

Box OneCloud For Android.v1.1

The document provides instructions for apps to integrate with Box using the OneCloud SDK to allow sharing of files between the Box app and partner apps. It describes downloading the SDK, implementing a BroadcastReceiver to handle callbacks from Box, and using the OneCloudData object to access file metadata and streams to read from or write back to Box. The SDK allows partners to create workflows like editing Box files, viewing Box files, or uploading new files from their app to Box.

Uploaded by

vbresan
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
54 views5 pages

Box OneCloud For Android.v1.1

The document provides instructions for apps to integrate with Box using the OneCloud SDK to allow sharing of files between the Box app and partner apps. It describes downloading the SDK, implementing a BroadcastReceiver to handle callbacks from Box, and using the OneCloudData object to access file metadata and streams to read from or write back to Box. The SDK allows partners to create workflows like editing Box files, viewing Box files, or uploading new files from their app to Box.

Uploaded by

vbresan
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 5

[Android] OneCloud AppToApp Setup Guide

Owner: Rico Yao

Purpose
Steps to becoming a OneCloud Partner
Workflows
Getting Started
Download the SDK
Import the SDK into your project
Implement BoxOneCloudReceiver
Enable the receiver in your AndroidManifest
Configure Proguard
Customizing your Integration
Callback Methods
Note: You do not call these - you respond to Box calling them
OneCloudData Object
Security Best Practices
Sample App
Recommended Post-development Activities

Purpose
Box has produced a special OneCloud SDK (separate from our normal Android SDK) that allows partner applications on Android to integrate with
Box with minimal effort. This document serves as a technical setup guide. Note that you must contact the Box Platform team to become an
official OneCloud partner.

Steps to becoming a OneCloud Partner


1. Review this documentation and learn about the technical requirements, with assistance from our program coordinator
2. Incorporate the OneCloud SDK into your application, implementing a few methods and including some iconography
3. Ensure you are tracking referral codes from the Android marketplaces so we can measure the success of our partnership
4. Provide marketing materials to the program coordinator for use in joint press releases, launch activities, and more

This document describes the SDK itself and the work needed to integrate it into your application.

Workflows
The SDK exists to facilitate data transfer between the Box cloud (as accessed through the Box application) and your application. It currently
supports the following data access scenarios, with additional workflows to follow.

1. Box asks the OneCloud app to view a document in a read-only mode.


2. Box asks the OneCloud app to edit a file and save it back to Box. Depending on the scenario, the OneCloud app may choose to save the
file as a new version on Box, or to upload a new file entirely.
3. Box asks the OneCloud app to create a new document and save it back to Box.
4. Box asks the OneCloud app to simply launch.
5. The OneCloud app asks Box to upload a file.
6. The OneCloud app launches the Box app.

Getting Started
Download the SDK
The OneCloud SDK is distributed in the same repository as our general Android SDK. It can be downloaded here:

https://github.com/box/box-android-sdk/tree/master/OneCloudAppToApp

Import the SDK into your project


Add the OneCloudAppToApp SDK into your app by referencing it as an Android Library Project. If you need help with this, see here:

http://developer.android.com/guide/developing/projects/projects-eclipse.html#ReferencingLibraryProject

Implement BoxOneCloudReceiver
Create a class that extends BoxOneCloudReceiver. This is a BroadcastReceiver that will receive messages broadcasted by Box and translate
them into simple callbacks for you. If you are using an IDE such as Eclipse, you can simply set up a class and then ask Eclipse to "add
unimplemented methods". This will leave you with a class with several method stubs that you can fill in, in order to implement your OneCloud
integration. Here is an example of an implemented BoxOneCloudReceiver from our sample OneCloud partner app:
https://github.com/box/box-android-sdk/blob/master/OneCloudAppToAppSample/src/com/box/onecloud/android/sample/MyReceiver.java

Enable the receiver in your AndroidManifest


In order for this receiver to actually register itself with the operating system, you must add certain entries in your Android manifest. Here is an
example:

<receiver android:name="com.my.application.MyReceiver">
<intent-filter>
<action android:name="com.box.android.EDIT_FILE"/>
<action android:name="com.box.android.CREATE_FILE"/>
<action android:name="com.box.android.VIEW_FILE"/>
<data android:mimeType="text/*"/>
<data android:mimeType="image/*"/>
<category android:name="android.intent.category.DEFAULT"/>
</intent-filter>
<intent-filter>
<action android:name="com.box.android.LAUNCH"/>
<category android:name="android.intent.category.DEFAULT"/>
</intent-filter>
</receiver>

The elements in red represent things that you should modify to suit your own app. You should modify the <receiver>'s android:name attribute to
match the name of the receiver you created in the previous step. You can also modify/add mimeType attributes to signal that your app only
handles files of a particular type. The example above illustrates what an app might declare if it can only handle text files and image files.

NOTES:

You may register multiple receivers to receive OneCloud broadcasts if you wish, and they will all respond to OneCloud requests. It is up
to you to ensure they don't conflict.
For security reasons, the receivers must be registered through the Android Manifest, and not dynamically (e.g. you cannot use
Context.registerReceiver; it will not work).
It is possible to implement the BoxOneCloudReceiver as a static inner class of another class. This may be a convenient way for you to
receive OneCloud callbacks in specific places in your codebase.
Make sure to put the <receiver> object in the correct place in your manifest. It should be added as a child of the <application> element in
your manifest.

Configure Proguard
If you use Proguard to obfuscate your code, you must add the following to your proguard configuration file (usually proguard.cfg):

-keep public class com.box.onecloud.android.OneCloudData


{
public protected private *;
}

Customizing your Integration


As you saw when you implemented your own BoxOneCloudReceiver, there were several abstract methods that you can implement in order to
perform the actual interactions with Box. For example if you want to respond to Box asking your app to edit a particular file, then you can
implement the method onEditFileRequested().

Callback Methods

Note: You do not call these - you respond to Box calling them

These are the methods in BoxOneCloudReceiver which you can implement in order to respond to requests from Box to perform certain actions.
You don't necessarily have to implement them all - only the ones that apply to your app.
/**
* Box has requested that you modify an existing Box file. You should load UI for the user to modify
the file.
*/
public abstract void onEditFileRequested(Context context, OneCloudData oneCloud);

/**
* Box has requested that you create a new file that should be uploaded to Box by calling
uploadNewFile(). You should load UI for the user to create a new
* file of the given type.
*/
public abstract void onCreateFileRequested(Context context, OneCloudData oneCloud);

/**
* Box has requested that you open and show the contents of a file to the user. You should load a
read-only UI for the user to view the file.
*/
public abstract void onViewFileRequested(Context context, OneCloudData oneCloud);

/**
* Box has requested that you launch your app in no particular mode. You should load general UI that
is most appropriate as a starting screen.
*/
public abstract void onLaunchRequested(Context context, OneCloudData oneCloud);

OneCloudData Object

You will notice that several methods listed above provide or consume a OneCloudData object. This represents the OneCloud transaction
between your app and Box. It serves several functions:

1. OneCloudData is Parcelable so you can easily pass it between activities, broadcasts, and services through intent extras.

2. You can read/write Box file data by opening input and output streams. These streams automatically encrypt/decrypt data for you, which is
required for secure transfers between Box and your app.
3. You can get information about the OneCloud transaction you are processing, such as the file name, size and mime type.
4. You can send data to Box. For example, you can upload a file to Box.

Here is some code that demonstrates the points above.


// Your implementation of BoxOneCloud Receiver
public class MyReceiver extends BoxOneCloudReceiver {
@Override
public void onEditFileRequested(Context context, OneCloudData oneCloudData) {
Intent i = new Intent(context, Main.class);
i.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
i.putExtra("one_cloud_data", oneCloudData);
context.startActivity(i);
}
}

// Activity that gets started by your BoxOneCloudReceiver


public class Main extends Activity {
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);

// Get the OneCloudData back from the intent's extras.


OneCloudData ocd = (OneCloudData) getIntent().getParcelableExtra("one_cloud_data");

// Get some information about the Box file we are being asked to edit
String fileName = ocd.getFileName();
String mimeType = ocd.getMimeType();
long fileSize = ocd.getFileSize();

// Get an input stream to the Box file data. You could use this to show the contents of the
file to the user.
InputStream boxInputStream = ocd.getInputStream();

// Get an output stream through which you can write new data to the Box file.
OutputStream boxOutputStream = ocd.getOutputStream();

// ...Add your own application logic to allow the user to view and modify the file.

// Set up an UploadListener so we can monitor the upload (this is optional).


UploadListener uploadListener = new UploadListener() {
@Override
public void onProgress(long bytesTransferred, long totalBytes) {
Log.d("debug", "Upload progress: " + bytesTransferred + " / " + totalBytes);
}
@Override
public void onComplete() {
Log.d("debug", "upload to Box complete");
}
@Override
public void onError() {
Log.d("debug", "upload to Box failed);
}
};

// Upload as a new version of the file to Box.


ocd.uploadNewVersion(uploadListener);

// Or, if you want to upload it as a new file:


// ocd.uploadNewFile("new file name", uploadListener);
}
}

Security Best Practices


Use only OneCloudData objects to access Box file data, and try not to write out the contents to an unencrypted file on the device's SD card
unless absolutely necessary.
Sample App
We provide a sample app which demonstrates a simple interaction where an app can receive requests from Box to edit a file, then zips up the file
and uploads it back to Box. You can download the sample app from here:
https://github.com/box/box-android-sdk/tree/master/OneCloudAppToAppSample

Recommended Post-development Activities


Incorporate a "Save back to Box" icon somewhere in your editing view (icon pending)
Add hooks for Market post-install referral tracking (see a walkthrough here)
Provide us with a support email address or link to forums where we can point users to for support requests

You might also like