Filestack iOS Picker

We re-built our iOS library from the ground up in order to incorporate all of the features available in the standard javascript library. This is the new more stable version of the iOS picker.

Requirements

The Filestack iOS SDK supports the following platforms:

  • iOS 8.4 or later

Installation

Using CocoaPods

We suggest using CocoaPods as the easiest way to start developing with Filestack.

$ gem install cocoapods

To integrate Filestack into your Xcode project using CocoaPods, specify it in your Podfile:

pod "FSPicker", "~> 1.0.6"

Next, run the following command:

$ pod install

The FSPicker relies on the iOS Filestack Pod, it will be installed automatically when you specify FSPicker in your podfile.

Usage

Basic Initialization:

First you need to import the module:

#import <FSPicker/FSPicker.h>
// or
@import FSPicker;
        

Initialize the config, include the optional theme and store options if you want, and then finally the FSPickerController:

FSConfig *config = [[FSConfig alloc] initWithApiKey:@"YOUR_API_KEY"];

FSStoreOptions *storeOptions = [[FSStoreOptions alloc] init];
storeOptions.location = FSStoreLocationS3;

config.storeOptions = storeOptions;

FSTheme *theme = [FSTheme filestackTheme];

FSPickerController *fsPickerController = [[FSPickerController alloc] initWithConfig:config theme:theme];
fsPickerController.fsDelegate = self;

// present the controller
[self presentViewController:fsPickerController animated:YES completion:nil];

// Or for FSSaveController

// configure the data
NSString *testImagePath = [[NSBundle mainBundle] pathForResource:@"test" ofType:@"png"];
NSURL *testImageURL = [NSURL URLWithString:testImagePath];

config.dataMimeType = FSMimeTypeImagePNG;
config.localDataURL = testImageURL;
config.proposedFileName = @"newimage";

// present the controller
FSSaveController *fsSaveController = [[FSSaveController alloc] initWithConfig:config theme:theme];
fsSaveController.fsDelegate = self;
[self presentViewController:fsSaveController animated:YES completion:nil];
        

FSPickerDelegate

// Called when user dismisses the picker controller.
- (void)fsPickerDidCancel:(FSPickerController *)picker;

// Called when picking of a single file resulted in error.
// This does not mean that picking of the rest of the files (in case of multiple files available) is interrupted.
// All files of multiple files pick, that resulted in error will call this method.
- (void)fsPicker:(FSPickerController *)picker pickingDidError:(NSError *)error;

// Called when picking of a single file completed with success.
// If you are picking multiple files this will be called for each of successfully picked file.
- (void)fsPicker:(FSPickerController *)picker pickedMediaWithBlob:(FSBlob *)blob;

// Called when "files picking" is finished. Blobs array will contain blobs of all successfully picked files.
- (void)fsPicker:(FSPickerController *)picker didFinishPickingMediaWithBlobs:(NSArray<FSBlob *> *)blobs;
        

FSSaveDelegate

// Called when user dismisses the save controller.
- (void)fsSaveControllerDidCancel:(FSSaveController *)saveController;

// Called when saving of data resulted in error.
- (void)fsSaveController:(FSSaveController *)saveController savingDidError:(NSError *)error;

// Called when saving of data completed with success.
- (void)fsSaveController:(FSSaveController *)saveController didFinishSavingMediaWithBlob:(FSBlob *)blob;
        

FSConfig

Available Properties:

NSString *apiKey;
NSArray<NSString *> *sources;

// FSPickerController
NSArray<FSMimeType> *mimeTypes;
NSInteger maxFiles;
BOOL selectMultiple;
BOOL defaultToFrontCamera;
// BOOL shouldDownload; TODO
// BOOL shouldUpload; TODO
FSStoreOptions *storeOptions;

// FSSaveController
NSData *data;
NSURL *localDataURL;
FSMimeType dataMimeType;
NSString *dataExtension;
NSString *proposedFileName;
        
Config Property Definitions:
API key
NSString
apikey

The most important property is the apiKey. It is the only property you need to provide in order for FSPicker to actually work. You can find your application's api key in your developer portal.

Sources
NSArray
apikey

The sources array allows you to configure the sources you would like to have available in your application. You can find the source names below. If no array or an empty array is set, all the sources are displayed in the picker.

Mimetypes
NSArray
mimeTypes

The mimeTypes array is used for constraining the displayed files to certain types. There are typedefs defined for your convenience. If this property is not provided, all file types will be available for uploading (/).

Multiple Mode
Boolean
selectMultiple

Set to YES by default. If set to NO, FSPicker will automatically upload the first file that is selected, otherwise it will wait until the upload button is selected.

Max Files
NSInteger
maxFiles

Sets the maximum number of files you can upload simultaneously. No limit is set by default.

Front Camera
Boolean
defaultToFrontCamera

Set this option to YES if you want to open the "Camera" source with the front camera by default.

Data
NSData
data

Path to the Data to export. You must have this property or the localDataURL property set, in order to use FSSaveController.

Data URL
NSUrl
localDataURL

URL to local data. You must have either this property or the data property set, in order to use FSSaveController.

Data Mimetype
FSMimeType
dataMimeType

Mimetype to set for the files you would like to export. This setting is not required, but it is recommended that you provide it or the dataExtension setting.

Data Extension
NSString
dataExtension

Extension to set for the files you would like to export. You can use it interchangeably with the dataMimeType option.

Proposed Filename
NSString
proposedFileName

File name that will be set in the "file name field". This should not include an extension. If no name is provided, the end user will be required to provide it.

Store Options
Convenience class
storeOptions

FSStoreOptions is a Convenience class to create an optional object that configures how to store uploaded data. FSStoreOptions can be initialized with either NSDictionary or by default [[FSStoreOptions alloc] init] and then setting the values "by hand".

Source Name Constants:

  • FSSourceBox
  • FSSourceCameraRoll
  • FSSourceDropbox
  • FSSourceFacebook
  • FSSourceGithub
  • FSSourceGmail
  • FSSourceImageSearch
  • FSSourceCamera
  • FSSourceGoogleDrive
  • FSSourceInstagram
  • FSSourceFlickr
  • FSSourcePicasa
  • FSSourceSkydrive
  • FSSourceEvernote
  • FSSourceCloudDrive

mimeTypes typedefs:

typedef NSString * FSMimeType;

FSMimeTypeAll @"*/*"

FSMimeTypeAudioAll @"audio/*"

FSMimeTypeVideoAll @"video/*"
FSMimeTypeVideoQuickTime @"video/quicktime"

FSMimeTypeImageAll @"image/*"
FSMimeTypeImagePNG @"image/png"
FSMimeTypeImageJPEG @"image/jpeg"
FSMimeTypeImageBMP @"image/bmp"
FSMimeTypeImageGIF @"image/gif"
FSMimeTypeImageSVG @"image/svg+xml"
FSMimeTypeImageTIFF @"image/tiff"
FSMimeTypeImagePSD @"image/vnd.adobe.photoshop"

FSMimeTypeApplicationAll @"application/*"
FSMimeTypeApplicationPDF @"application/pdf"
FSMimeTypeApplicationDOC @"application/msword"
FSMimeTypeApplicationDOCX @"application/vnd.openxmlformats-officedocument.wordprocessingml.document"
FSMimeTypeApplicationODT @"application/vnd.oasis.opendocument.text"
FSMimeTypeApplicationXLS @"application/vnd.ms-excel"
FSMimeTypeApplicationXLSX @"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
FSMimeTypeApplicationODS @"application/vnd.oasis.opendocument.spreadsheet"
FSMimeTypeApplicationPPT @"application/vnd.ms-powerpoint"
FSMimeTypeApplicationPPTX @"application/vnd.openxmlformats-officedocument.presentationml.presentation"
FSMimeTypeApplicationODP @"application/vnd.oasis.opendocument.presentation"
FSMimeTypeApplicationAI @"application/illustrator"
FSMimeTypeApplicationJSON @"application/json"

FSMimeTypeTextAll @"text/*"
FSMimeTypeTextHTML @"text/html"
FSMimeTypeTextPlain @"text/plain; charset=UTF-8"
        

FSStoreOptions

Convenience class to create an optional object that configures how to store uploaded data. FSStoreOptions can be initialized with either NSDictionary or by default [[FSStoreOptions alloc] init] and then setting the values "by hand".

// Example
FSStoreOptions *options = [[FSStoreOptions alloc] init];
options.location = FSStoreLocationS3;

// "fileName" and "mimeType" properties are omitted while uploading files using FSPicker.

// Example
FSStoreOptions *options = [[FSStoreOptions alloc] initWithDictionary:@{@"location": FSStoreLocationS3}];
        
Available dictionary keys (and properties):
location
NSString
FSStoreLocation typedef of NSString

Where to store the file. The default is S3 FSStoreLocationS3. Other options are FSStoreLocationAzure, FSStoreLocationDropbox, FSStoreLocationRackspace and FSStoreLocationGoogleCloud. You must have configured your storage in the developer portal to enable this feature.

path
NSString
path

The path to store the file at within the specified file store. For S3, this is the key where the file will be stored at. By default, Filestack stores the file at the root at a unique id, followed by an underscore, followed by the filename, for example "3AB239102DB_myphoto.png". If the provided path ends in a '/', it will be treated as a folder, so if the provided path is "myfiles/" and the uploaded file is named "myphoto.png", the file will be stored at "myfiles/909DFAC9CB12_myphoto.png", for example.

container
NSString
container

The bucket or container in the specified file store where the file should end up. This is especially useful if you have different containers for testing and production and you want to use them both on the same Filestack app. If this parameter is omitted, the file is stored in the default container specified in your developer portal. Note that this parameter does not apply to the Dropbox file store.

access
NSString
FSAccess typedef of NSString

Unavailable in storeURL method. Options are FSAccessPublic or FSAccessPrivate. Indicates that the file should be stored in a way that allows public access going directly to the underlying file store. For instance, if the file is stored on S3, this will allow the S3 url to be used directly. This has no impact on the ability of users to read from the Filestack file URL. Defaults to 'private'.

base64decode
Boolean
base64decode

Specify that you want the data to be first decoded from base64 before being written to the file. For example, if you have base64 encoded image data, you can use this flag to first decode the data before writing the image file.

security
NSString
FSSecurity

If you have security enabled, you'll need to have a valid Filestack.com policy and signature in order to perform the requested call. This allows you to select who can and cannot perform certain actions on your site. Read more about security and how to generate policies and signatures

FSSecurity class

A simple class to store your security policy and signature. FSSecurity instance is a security parameter in FSStoreOptions. Read more about security and how to generate policies and signatures.

- initWithPolicy:signature:

Additional Resources:

For more information on the the iOS Picker including how to set up custom themes, please consult the documentation in the open source github repository.