dayton1987 / uploadcare-ios

UploadcareKit: iOS SDK for Uploadcare API

Uploadcare for iOS

Uploadcare is a PaaS, providing file handling mechanisms for web sites and mobile applications.

Uploadcare for iOS is an open source Objective-C component that brings Uploadcare features to your iOS apps. It consists of two general parts: UploadcareKit and Uploadcare Widget.

UploadcareKit is a core-level abstract layer, responsible for API communication within upload and download tasks.

Uploadcare Widget, a major component of Uploadcare for iOS, is what a modern, cloud-aware file picker for iOS would be, if iOS had a notion of files. Since iOS doesn't, you can think of Uploadcare Widget as a thing picker – a drop-in component, that allows your users to select and upload their things (photos, documents, whatever you want them to) to your service, via Uploadcare.

Here's what it looks like:

Quickstart

Install

Uploadcare for iOS uses CocoaPods, a library dependency management tool for Objective-C projects. To install Uploadcare for iOS in your project, just add the following line to your Podfile:

pod 'Uploadcare'

Then, run pod install in your project directory.

Make sure to use the .xcworkspace file from now on.

Setup

Environment

Import Uploadcare.h header to your implementation. Set up uploadcare public key as following in your application delegate:

#import <Uploadcare/Uploadcare.h>

/* ... */

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [[UCClient defaultClient] setPublicKey:<#your key#>];
    return YES;
}

iCloud entitlements

Uploadcare widget uses UIDocumentMenuViewController, so you need to enable iCloud in your application. Go to Target -> Capabilities and enable iCloud. Set both Key-value storage and iCloud Documents options enabled:

Custom url scheme

Uploadcare widget uses SFSafariViewController on iOS 9+ and UIWebView on prior versions for authentification. In this case it should handle url callbacks through custom url scheme from application delegate methods:

// IOS 9+
- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<NSString *,id> *)options {
    return [[UCClient defaultClient] handleURL:url];
}

// IOS 8
- (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url {
    return [[UCClient defaultClient] handleURL:url];
}

In order to add custom url scheme, perform the following steps:

• Go to Target -> Info -> URL types
• Add new url scheme with the following format: uc-<public key>
• The final result should look similar to this:

NSPhotoLibraryUsageDescription on iOS 10

Uploadcare widget uses UIImagePickerController to upload files from camera roll. Don't forget to add NSPhotoLibraryUsageDescription key to your project Info.plist file to prevent app from crash in runtime.

Show

Init and present widget

To display the Uploadcare Widget, you must create and initialize an instance of UCMenuViewController by invoking initWithProgress:completion: method:

#import <Uploadcare/Uploadcare.h>

/* ... */

UCMenuViewController *menu = [[UCMenuViewController alloc] initWithProgress:^(NSUInteger bytesSent, NSUInteger bytesExpectedToSend) {
    // handle progress here
} completion:^(NSString *fileId, id response, NSError *error) {
    if (!error) {
        // handle success
    } else {
        // handle error
    }
}];
    
    

Then, present it with presentFrom: method:

[menu presentFrom:self];

Customization

You can easily customize your social networks list apperance by implementing your own menu. In order to receive available social sources, you can use fetchSocialSourcesWithCompletion: method from UCSocialManager. After you receive a list of social sources, you can choose one and use it for instantiating UCGalleryVC with the following method:

- (id)initWithSource:(UCSocialSource *)source
           rootChunk:(UCSocialChunk *)rootChunk
            progress:(UCProgressBlock)progress
          completion:(UCWidgetCompletionBlock)completion;

Core level features only

In order to integrate core level features only, such as local and remote file upload operations, you can use the following subspec:

pod 'Uploadcare/Core'

Please notice, that Uploadcare.h header won't be included in this case, so you'll have to use UploadcareKit.h instead.

Sample App

Please take a look at the Example Project.

Contact

If you have any questions, bug reports or suggestions, drop us a line.

License

Uploadcare iOS is licensed under the MIT license (see LICENSE).