# Swift SDK

## Overview

Filestack Swift SDK allows programmatic file uploading, transformations, and other operations with Filestack URLs directly from your iOS application.

The Filestack Swift SDK supports [iOS 11](https://support.apple.com/en-us/HT208067) and later.

## List of features

- [Multi-part file uploading](https://www.filestack.com/docs/uploads/uploading/#multipart-uploads) directly from your iOS application with [Intelligent Ingestion](https://www.filestack.com/docs/uploads/uploading/#intelligent-ingestion) support.
- Extensive set of [file transformations](https://www.filestack.com/docs/api/processing/) of images, videos and documents.
- [Cloud storage](https://www.filestack.com/docs/uploads/storage/) using the world’s largest cloud storage platforms.
- Deliver content such as audio, video and documents via our [Filestack CDN](https://www.filestack.com/docs/delivery/cdn/).
- Perform operations with Filestack URLs such as downloading, overwriting, deleting or obtaining file metadata.
- Monitor upload progress and cancel any ongoing upload operations.
- Compatible with Swift 4.2 up to 5.0 and Objective-C.

## Quick Example Upload

### Uploading files directly to a storage location

This example uploads a file from the device located at localURL to Filestack’s default storage location.

```
let multiPartUpload = client.multiPartUpload(from: localURL) { response in
    // Try to obtain Filestack handle
    if let json = response?.json, let handle = json["handle"] as? String {
        // Use Filestack handle
    } else if let error = response?.error {
        // Handle error
    }
}
```

## Quick Example Transformation

### Transforming an image

This example applies the following transformations to the Filestack URL pointed by `handle`:

- Resizes image to be exactly 220 x 220 pixels by cropping it in the center.
- Adds a watermark at 50% size and places it at the bottom right.
- Adds a rounded corner with a radius of 20 pixels and applies a slight blur effect.

```
let transformable = client.transformable(handle: "IMAGE-HANDLE")

transformable.add(transform: ResizeTransform().width(220).height(220).fit(.crop).align(.center))
               .add(transform: WatermarkTransform(file: "WATERMARK-HANDLE").size(50).position([.bottom, .right]))
               .add(transform: RoundedCornersTransform().radius(20).blur(0.25))

let storageOptions = StorageOptions(location: .s3, container: "S3-CONTAINER", access: .public)

transformable.store(using: storageOptions, base64Decode: false) { (handle, response) in
      if let handle = handle {
          // TODO: Do something with handle
      } else if let error = response.error {
          // TODO: Handle error
      }
      }
```

## Installation

Our Swift SDK can be installed using any of the methods listed below:

### CocoaPods

[CocoaPods](http://cocoapods.org/) is a dependency manager for Cocoa projects. You can install it with the following command:

```
gem install cocoapods
```

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

```
source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '11.0'
use_frameworks!

target '<Your Target Name>' do
    pod 'FilestackSDK', '~> 2.0'
end
```

Then, run the following command:

```
pod install
```

### Carthage

[Carthage](https://github.com/Carthage/Carthage) is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks.

You can install Carthage with [Homebrew](http://brew.sh/) using the following command:

```
brew update
brew install carthage
```

To integrate FilestackSDK into your Xcode project using Carthage, specify it in your `Cartfile`:

```
github "filestack/filestack-swift" ~> 2.0
```

Run `carthage update` to build the framework and drag the built `FilestackSDK.framework` into your Xcode project. Additionally, add `FilestackSDK.framework`, `Alamofire.framework` and `CryptoSwift.framework` to the embedded frameworks build phase of your app’s target.

### Manually

#### Embedded Framework

Open up Terminal, cd into your top-level project directory, and run the following command “if” your project is not initialized as a git repository:

```
git init
```

Add FilestackSDK and its dependencies as git submodules by running the following commands:

```
git submodule add https://github.com/filestack/filestack-swift.git
git submodule add https://github.com/Alamofire/Alamofire.git
git submodule add https://github.com/krzyzanowskim/CryptoSwift.git
```

Open the new `filestack-swift` folder, and drag the `FilestackSDK.xcodeproj` into the Project Navigator of your application’s Xcode project.

It should appear nested underneath your application’s blue project icon. Whether it is above or below all the other Xcode groups does not matter. Select the `FilestackSDK.xcodeproj` in the Project Navigator and verify the deployment target matches that of your application target.

Next, select your application project in the Project Navigator (blue project icon) to navigate to the target configuration window and select the application target under the “Targets” heading in the sidebar.

In the tab bar at the top of that window, open the “General” panel.

Click on the + button under the “Embedded Binaries” section and choose the `FilestackSDK.framework` for iOS.

Repeat the same process for adding `Alamofire` and `CryptoSwift` dependencies.

## Setup

### Integration into a Swift project

First import the framework into your code:

```
import FilestackSDK
```

And then instantiate a `Client` object:

- Without security options:

```swift
// Initialize your `Client` object by passing a valid API key.
let client = Client(apiKey: "YOUR-API-KEY")
```

- With security options:

```swift
// Initialize a `Policy` with the expiry time and permissions you need.
let oneDayInSeconds: TimeInterval = 60 * 60 * 24 // 24-hour time interval

let policy = Policy(
expiry: Date(timeIntervalSinceNow: oneDayInSeconds), // Set your expiry time
call: [.convert, .read, .runWorkflow, .store]        // Set your policy permissions
)

// Initialize a `Security` object by providing a `Policy` object and your app secret.
// You can find and setup your app secret in the Developer Portal.
guard let security = try? Security(policy: policy, appSecret: "YOUR-APP-SECRET") else { return }

// Initialize your `Client` object by passing a valid API key, and security options.
let client = Client(apiKey: "YOUR-API-KEY", security: security)
```

For more information, please consult our [API Reference](https://filestack.github.io/filestack-swift/).

## Resources

- [Filestack Swift SDK Repository](https://github.com/filestack/filestack-swift)
- [Filestack iOS SDK Repository](https://github.com/filestack/filestack-ios)
- [Filestack Swift SDK API Reference](https://filestack.github.io/filestack-swift/)
- [Filestack iOS SDK API Reference](https://filestack.github.io/filestack-ios/)