This SDK provides access to the Box V2 API. It currently supports file and folder operations.
We have built several sample applications with the V2 SDK.
The easiest way to add the Box SDK to your project is as a dependent XCode project.
-
Clone this repository into your project's directory. You can use git submodules if you want.
-
Open your project in XCode.
-
Drag BoxSDK.xcodeproj into the root of your project explorer.
-
Link with QuartzCore.framework and Security.framework.
-
Add the
-ObjC
linker flag. This is needed to load categories defined in the SDK. -
#import <BoxSDK/BoxSDK.h>
See our sample applications for examples of integrating the V2 SDK. Check out the documentation hosted on Github which is also included in the source.
Set your client ID and client secret on the SDK client:
[BoxSDK sharedSDK].OAuth2Session.clientID = @"YOUR_CLIENT_ID";
[BoxSDK sharedSDK].OAuth2Session.clientSecret = @"YOUR_CLIENT_SECRET";
One way to complete the OAuth2 flow is to have your app to register a
custom URL scheme in order to receive an OAuth2 authorization code.
In your Info.plist
, register the following URL scheme:
boxsdk-YOUR_CLIENT_ID
Note: When setting up your service on Box, leave the OAuth2 reditrect URI blank. The SDK will provide a custom redirect URI when issuing OAuth2 calls; doing so requires that no redirect URI be set in your service settings.
To authenticate your app with Box, you need to use OAuth2. The authorization flow
happens in a UIWebView
. To get started, you can present the sample web view the
SDK provides:
UIViewController *authorizationController = [[BoxAuthorizationViewController alloc] initWithAuthorizationURL:[[BoxSDK sharedSDK].OAuth2Session authorizeURL] redirectURI:nil];
[self presentViewController:authorizationController animated:YES completion:nil];
On successful authentication, your app will receive an "open in" request using the custom URL scheme you registered earlier. In your app delegate:
- (BOOL)application:(UIApplication *)application
openURL:(NSURL *)url
sourceApplication:(NSString*)sourceApplication
annotation:(id)annotation
{
[[BoxSDK sharedSDK].OAuth2Session performAuthorizationCodeGrantWithReceivedURL:url];
return YES;
}
You can listen to notifications on [BoxSDK sharedSDK].OAuth2Session
to be notified
when a user becomes successfully authenticated.
All SDK API calls are asynchronous. They are scheduled by the SDK on an NSOperationQueue
.
To be notified of API responses and errors, pass blocks to the SDK API call methods. These
blocks are triggered once the API response has been received by the SDK.
Note: callbacks are not triggered on the main thread. Wrap updates to your app's
UI in a dispatch_sync
block on the main thread.
BoxCollectionBlock success = ^(BoxCollection *collection)
{
// grab items from the collection, use the collection as a data source
// for a table view, etc.
};
BoxAPIJSONFailureBlock failure = ^(NSURLRequest *request, NSHTTPURLResponse *response, NSError *error, NSDictionary *JSONDictionary)
{
// handle errors
};
[[BoxSDK sharedSDK].foldersManager folderItemsWithID:folderID requestBuilder:nil success:success failure:failure];
BoxFileBlock success = ^(BoxFile *file)
{
// manipulate the BoxFile.
};
BoxAPIJSONFailureBlock failure = ^(NSURLRequest *request, NSHTTPURLResponse *response, NSError *error, NSDictionary *JSONDictionary)
{
// handle errors
};
[[BoxSDK sharedSDK].filesManager fileInfoWithID:folderID requestBuilder:nil success:success failure:failure];
To send data via the API, use a request builder. If we wish to move a file and change its name:
BoxFileBlock success = ^(BoxFile *file)
{
// manipulate the BoxFile.
};
BoxAPIJSONFailureBlock failure = ^(NSURLRequest *request, NSHTTPURLResponse *response, NSError *error, NSDictionary *JSONDictionary)
{
// handle errors
};
BoxFilesRequestBuilder *builder = [BoxFilesRequestBuilder alloc] init];
builder.name = @"My awesome file.txt"
builder.parentID = BoxAPIFolderIDRoot;
[[BoxSDK sharedSDK].filesManager editFileWithID:folderID requestBuilder:builder success:success failure:failure];
BoxFileBlock fileBlock = ^(BoxFile *file)
{
// manipulate resulting BoxFile
};
BoxAPIJSONFailureBlock failureBlock = ^(NSURLRequest *request, NSHTTPURLResponse *response, NSError *error, NSDictionary *JSONDictionary)
{
// handle failed upload
};
BoxAPIMultipartProgressBlock progressBlock = ^(unsigned long long totalBytes, unsigned long long bytesSent)
{
// indicate progress of upload
};
BoxFilesRequestBuilder *builder = [[BoxFilesRequestBuilder alloc] init];
builder.name = @"Logo_Box_Blue_Whitebg_480x480.jpg";
builder.parentID = folderID;
NSString *path = [[NSBundle mainBundle] pathForResource:@"Logo_Box_Blue_Whitebg_480x480.jpg" ofType:nil];
NSInputStream *inputStream = [NSInputStream inputStreamWithFileAtPath:path];
NSDictionary *fileAttributes = [[NSFileManager defaultManager] attributesOfItemAtPath:path error:nil];
long long contentLength = [[fileAttributes objectForKey:NSFileSize] longLongValue];
[[BoxSDK sharedSDK].filesManager uploadFileWithInputStream:inputStream contentLength:contentLength MIMEType:nil requestBuilder:builder success:fileBlock failure:failureBlock progress:progressBlock];
NSOutputStream *outputStream = [NSOutputStream outputStreamToFileAtPath:path append:NO];
BoxDownloadSuccessBlock successBlock = ^(NSString *downloadedFileID, long long expectedContentLength)
{
// handle download, preview download, etc.
};
BoxDownloadFailureBlock failureBlock = ^(NSURLRequest *request, NSHTTPURLResponse *response, NSError *error)
{
// handle download failure
};
BoxAPIDataProgressBlock progressBlock = ^(long long expectedTotalBytes, unsigned long long bytesReceived)
{
// display progress
};
[[BoxSDK sharedSDK].filesManager downloadFileWithID:fileID outputStream:outputStream requestBuilder:nil success:successBlock failure:failureBlock progress:progressBlock];
An easy way to integrate Box into your app is to use the folder picker widget included in the SDK. The folder picker provides a folder browser that users can use to select a file or folder from their account. You can use this folder to then make API calls. You can find folder picker brand assets such as buttons here.
The folder picker looks like this:
See our sample app that utilizes the folder picker.
In addition to the installation steps above, you must do two more things in XCode to include the folder picker assets and icons in your app.
- Add BoxSDKResources as a dependent target.
- Copy the resource bundle during your app's copy files build phase.
This SDK contains unit tests that are runnable with ./bin/test.sh
.
Pull requests will not be accepted unless they include test coverage.
Documentation for this SDK is generated using appledoc.
Documentation can be generated by running ./bin/generate-documentation.sh
. This script
depends on the appledoc
binary which can be downloaded using homebrew (brew install appledoc
).
Documentation is hosted on this repo's github page.
Pull requests will not be accepted unless they include documentation.
- There is no support for manipulating files in the trash.
- Only the files and folders endpoints are supported.