iOS image and video upload
Cloudinary provides support for uploading media directly from your mobile application to your Cloudinary account, without going through your servers first. This method allows for faster uploading and a better user experience. It also reduces load on your servers and reduces the complexity of your applications.
You can also take advantage of upload presets for predefining upload parameters. For details on all the available upload parameters, see the Media upload documentation and the Upload method of the Upload API Reference.
For security reasons, mobile applications shouldn't contain your Cloudinary account credentials. You can use a signed upload, but that requires generating an authentication signature on your backend. In most cases, you will probably use unsigned uploads that generally provide all the functionality you need for your mobile application, while restricting upload options that require more security.
Upload method
The upload request is managed by the upload
method, which accepts the file to upload as its only parameter. The file can be specified as either a url
or data
object.
cloudinary.createUploader().upload(url: fileUrl)
// or
cloudinary.createUploader().upload(data: data)
The OS attempts to initiate the upload immediately but the upload may be rescheduled depending on the system's current network, memory and cpu needs. The upload results are dispatched asynchronously and callbacks can be defined per request.
The following simple example uploads an image called imageFile.jpg
using the default settings:
The result of the upload API call is a CLDUploadResult
object that provides information about the uploaded image, including the assigned public ID of the image and its URL.
Signed upload
To implement signed uploads from an iOS device to your Cloudinary account you must:
- Provide a signature generated on your backend.
- Add the signature and timestamp to the upload options with the
setSignature
method. - Call the
signedUpload
method to upload the file.
For example, to upload an image called imageFile.jpg
, set the publicId to newId
, and sign the upload request:
let params = CLDUploadRequestParams() .setPublicId("newId") var mySig = MyFunction(params) // your own function that returns a signature generated on your backend params.setSignature(CLDSignature(signature: mySig.signature, timestamp: mySig.timestamp)) let request = cloudinary.createUploader().signedUpload( url: "imageFile.jpg", params: params)
Unsigned upload
Unsigned upload is an option for performing upload without the need to generate a signature on your backend. Unsigned upload options are controlled by an upload preset: to use this feature, you first need to enable unsigned uploading for your Cloudinary account from the Upload Settings page.
An upload preset is used to define which upload options will be applied to media assets that are uploaded unsigned with that preset specified. You can edit the preset at any point in time (or create additional upload presets).
Upload options
You can pass an instance of CLDUploadRequestParams
, with any extra parameters you'd want to pass, as part of the upload request. For example, to upload an image called imageFile.jpg
using an upload preset called samplePreset
:
let params = CLDUploadRequestParams() .setUploadPreset("samplePreset") let request = cloudinary.createUploader().upload( url: "imageFile.jpg", params: params)
If you want to include more than one upload parameter in the request you can chain them together. For example, to upload an image called dog.jpg
, set the publicId to MyDog
, and add the tag animal
:
let params = CLDUploadRequestParams() .setUploadPreset("samplePreset").setPublicId("MyDog").setTags("animal") let request = cloudinary.createUploader().upload( url: "dog.jpg", params: params)
Chunked upload
The SDK includes the uploadLarge
method which offers more tolerance for network issues. This method uploads a large file to the cloud in chunks, and is required for any files that are larger than 100 MB. By default, the chunk size is set to 20 Megabytes but can be set to as low as 5 Megabytes with the chunkSize
parameter. For example, uploading a large video file called myVid.mp4
and setting the chunk size to 6 Megabytes:
let params = CLDUploadRequestParams() .setResourseType("video").setUploadPreset("samplePreset") let request = cloudinary.createUploader().uploadLarge( url: "myVid.mp4", params: params, chunkSize: 6 * 1024 * 1024)
Cancel an upload
If you need to cancel an upload in progress, you can use the cancel
method:
let request = cloudinary.createUploader().signedUpload(url: fileUrl, params:params); ... request.cancel();
Callbacks
You can track the upload progress by passing a progress
closure as part of the upload request, that is called periodically during the data transfer. For Example:
let request = cloudinary.createUploader().upload( url: fileUrl, uploadPreset: "samplePreset", progress: { (bytes, totalBytes, totalBytesExpected) in // Handle progress })
You can also handle the response by adding a completionHandler
closure to be called once the upload request has finished. For example:
// pass a closure using the response method let request = cloudinary.createUploader().upload( url: fileUrl, uploadPreset: "samplePreset") .response( { response, error in // Handle response } )
// pass a closure as an additional parameter of the upload method let request = cloudinary.createUploader().upload( url: fileUrl, uploadPreset: "samplePreset", { (response, error) in // Handle response })
// pass a closure as a trailing closure of the upload method let request = cloudinary.createUploader().upload( url: fileUrl, uploadPreset: "samplePreset") { (response, error) in // Handle response }
Preprocess image uploads
You can pass an instance of CLDImagePreprocessChain
, with any steps for preprocessing the image before uploading, as part of the upload request. The following types of processing steps are currently available:
Step Type | Parameter | Description |
---|---|---|
limit | (width, height) | Scales down the image to fit within a bounding box of the given dimensions. |
dimensionsValidator | (minWidth, maxWidth, minHeight, maxHeight) | Verifies the minimum and maximum dimensions for the image. Throws an error if the image does not fit within these dimensions. |
customImageEncoder | (format, quality) | Saves the image using the given format (JPEG or PNG) and quality. |
For example, to limit an image to a size of 500x500 pixels, make sure that the image is at least 10x10 pixels in size and change the format to PNG with a quality of 70:
let preprocessChain = CLDImagePreprocessChain() .addStep(CLDPreprocessHelpers.limit(width: 500, height: 500)) .addStep(CLDPreprocessHelpers.dimensionsValidator(minWidth: 10, maxWidth: 500, minHeight: 10, maxHeight: 500) .setEncoder(CLDPreprocessHelpers.customImageEncoder(format: EncodingFormat.PNG, quality: 70)) let request = cloudinary.createUploader().upload( url: file, uploadPreset: "samplePreset", preprocessChain: preprocessChain) .response({ (response, error) in // handle response })
CLDProcessStep
closure with the addStep
method.