Filestack iOS SDK

We re-built our iOS library from the ground up in order to incorporate all of the features available in the standard javascript library as well as to take advantage of our robust image conversions supported by our processing engine.

Requirements

The Filestack iOS SDK supports the following platforms:

  • iOS 8.4 or later
  • Mac OS X 10.9 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 "Filestack", "~> 0.2.10"

Next, run the following command:

$ pod install

Usage

Available methods:

- initWithApiKey:
- initWithApiKey:delegate:
- pickURL:completionHandler:
- remove:completionHandler:
- stat:withOptions:completionHandler:
- download:completionHandler:
- storeURL:withOptions:completionHandler:
- store:withOptions:progress:completionHandler:
- transformURL:transformation:security:completionHandler:
        

Delegate methods:

// FSFilestackDelegate
- filestackTransformSuccess:
- filestackTransformSuccessJSON:
- filestackStatSuccess:
- filestackDownloadSuccess:
- filestackRequestError:
- filestackPickURLSuccess:
- filestackStoreSuccess:
- filestackRemoveSuccess
        

Examples

// pickURL Example
Filestack *filestack = [[Filestack alloc] initWithApiKey:@"MYAPIKEY"];
NSString *url = @"https://example.com/image.png"

[filestack pickURL:url completionHandler:^(FSBlob *blob, NSError *error) {
    NSLog(@"blob: %@", blob);
    NSLog(@"error: %@", error);
}];

// stat Example
Filestack *filestack = [[Filestack alloc] initWithApiKey:@"MYAPIKEY"];
FSBlob *blob = [[FSBlob alloc] initWithUrl:@"https://cdn.filestackcontent.com/FILEHANDLER"]
]
[filestack stat:blob withOptions:nil completionHandler:^(FSMetadata *metadata, NSError *error) {
    NSLog(@"metadata: %@", metadata);
    NSLog(@"error: %@", error);
}];

// or...
NSString *url = @"https://example.com/image.png"
[filestack pickURL:url completionHandler:^(FSBlob *blob, NSError *error) {
    if (error) {
        NSLog(@"error: %@", error);
    } else {
        NSLog(@"blob: %@", blob);
        FSStatOptions *options = [[FSStatOptions alloc] initWithDictionary:@{@"mimetype": @YES, @"md5": @YES};
        [filestack stat:blob withOptions:options completionHandler:^(FSMetadata *metadata, NSError *error) {
            NSLog(@"metadata: %@", metadata);
            NSLog(@"error: %@", error);
        }];
    }
}];

// store image
Filestack *filestack = [[Filestack alloc] initWithApiKey:@"MYAPIKEY"];

UIImage *image = ... // image you'd like to upload.
NSData *imageData = UIImageJPEGRepresentation(image);

FSStoreOptions *storeOptions = [[FSStoreOptions alloc] init];
storeOptions.fileName = "filename.jpg";

[filestack store:imageData withOptions:storeOptions progress:^(NSProgress *uploadProgress) {
    NSLog(@"progress: %f", uploadProgress.fractionCompleted);
} completionHandler:^(FSBlob *blob, NSError *error) {
    NSLog(@"blob: %@", blob);
}];
      

FSblob

Filestack's "blob" Object available in the completionHandler of most of the available methods after a successful request. The format is standard JSON and contains information about the file, serialized to this class.

Blob Properties:
url
NSString
url

The most critical part of the file, the url points to where the file is stored and acts as a sort of "file path".

filename
NSString
fileName

The name of the file, if available.

mimetype
NSString
mimeType

The mimetype of the file, if available.

size
NSInteger
size

The size of the file in bytes, if available.

key
NSString
key

If the file was stored in one of the file stores you specified or configured (S3, Rackspace, Azure, etc.), this parameter will tell you where in the file store this file was written.

container
NSString
container

If the file was stored in one of the file stores you specified or configured (S3, Rackspace, Azure, etc.), this parameter will tell you in which container this file was put.

path
NSString
path

The path indicates the position of the file in the hierarchy of files uploaded.

writeable
NSNumber
writeable

This flag specifies whether the underlying file is writeable. In most cases this will be true, but if a user uploads a photo from Facebook, for instance, the original file cannot be written to. This will return either 0, 1 or nil if the flag is unknown or wasn't returned from the request.

s3url
NSString, readonly
writeable

("Experimental") The direct path to the file on S3, if available. This will return an invalid link if the file was stored using a different storage solution than S3.

FSmetadata

"Read-only" class available in completionHandler of stat:withOptions:completionHandler: or in filestackStatSuccess: delegate method if request was successful.

Properties you can access:

  • size (NSInteger)
  • mimeType (NSString)
  • fileName (NSString)
  • width (NSInteger)
  • height (NSInteger)
  • uploaded (NSInteger)
  • writeable (NSNumber)
  • md5 (NSString)
  • location (NSString)
  • path (NSString)
  • container (NSString)
  • s3url (NSString, experimental)

FSStatOptions class

Convenience class to create an options object for the stat:withOptions:completionHandler: method. An optional object that specifies what metadata you want back. By default, we return any metadata we get without having to run over the contents of the file (currently: size, mimetype, filename, uploaded, writeable, location, path, container). FSStatOptions can be initialized with either NSDictionary or by default [[FSStatOptions alloc] init] and then setting the values "by hand". All variables are BOOL.

// Example
FSStatOptions *options = [[FSStatOptions alloc] init];
options.mimeType = YES;
options.md5 = YES;

// Example
FSStatOptions *options = [[FSStatOptions alloc] initWithDictionary:@{@"mimetype": @YES, @"md5": @YES};
        
Available dictionary keys (and properties):
size
String
size

Specify that you want the size of the file returned. This property is a number in bytes.

mimetype
String
mimetype or mimeType if get/set as property

Specify that you want the type of the file returned. This property is a string.

filename
String
filename or fileName if get/set as property

Specify that you want the name of the file returned. This property is a string.

width
Integer
width

Specify that you want the width of the image returned. This property is a number in pixels. If the file is not an image then width is set to 0.

height
Integer
height

Specify that you want the height of the image returned. This property is a number pixels. If the file is not an image then height is set to 0.

uploaded
Timestamp
uploaded

Specify that you want the timestamp of when the file was uploaded to Filestack. This property is a UNIX Timestamp to milliseconds (13 digit long).

writeable
Boolean
writeable

Specify that you want whether the file is writeable. This property is a BOOL.

md5
String
md5

Specify that you want to know the md5 hash of the file returned. This property is a string.

location
String
location

Specify that you want to know the storage location (S3, etc.) of a stored file if available. This property is a string.

path
String
path

Specify that you want to know the storage path of a stored file if available. This property is a string.

container
String
container

Specify that you want to know the storage container of a stored file if available. This property is a string.

FSStoreOptions class

Convenience class to create options object for store:withOptions:completionHandler: and storeURL:withOptions:completionHandler: methods. An optional object that configure how to store the 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;
options.fileName = @"myFile.png";

// Example
FSStoreOptions *options = [[FSStoreOptions alloc] initWithDictionary:@{@"location": FSStoreLocationS3, @"filename": @"myFile.png"};
        
Available dictionary keys (and properties):
filename
NSString
filename or fileName if get/set as property

The name of the file as it will be stored. If this isn't provided, we do the best we can to come up with one.

mimetype
NSString
mimetype or mimeType if get/set as property

Unavailable in storeURL method. Set the mimetype for the file as it is stored. If this isn't provided, we do the best we can, defaulting to "application/octet-stream" if you give us raw data.

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 SDK including how to use it for image transformations, please consult the documentation in the open source github repository.