Cloudinary iOS SDK
Cloudinary is a cloud service that offers a solution to an application's entire image management pipeline.
Features
- Easily upload images and videos to the cloud.
- Automatically perform smart image resizing, cropping and conversion without installing complex software.
- Integrate Facebook or Twitter profile images in a snap, in any dimension and style to match your website’s graphics requirements.
- Media resources are seamlessly delivered through a fast CDN.
and much much more...
Cloudinary offers comprehensive APIs and administration capabilities and is easy to integrate with any web application, existing or new.
Cloudinary provides URL and HTTP based APIs that can be easily integrated with any Web development framework.
For iOS, Cloudinary provides an SDK for simplifying the integration even further.
Requirements
- iOS 8.0+
- Compatible with Swift, tested up to version 5.0.
- Compatible with Objective-C, see usage example.
Integration
CocoaPods
CocoaPods is a dependency manager for Swift and Objective-C Cocoa projects. To install CocoaPods:
sudo gem install cocoapods
If you don't have a Podfile
in your project yet, add it by running the command:
pod init
Add the Cloudinary SDK to your Podfile
:
source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '8.0'
use_frameworks!
target 'MyApp' do
pod 'Cloudinary', '~> 2.0'
end
Then, run the command:
pod install
Working with the Cloudinary iOS SDK Manually
If you prefer not use a dependency manager, you can add Cloudinary manually by adding it as a submodule to your project:
Open Terminal and navigate to your project's top level directory.
If your project is not initialized as a git repository, run the command:
git init
To add cloudinary as a git submodule, run the command:
git submodule add https://github.com/cloudinary/cloudinary_ios.git
Embedded Framework
- Drag
Cloudinary.xcodeproj
into the Project Navigator of your application's Xcode project. It should appear under your application's blue project icon. - Select
Cloudinary.xcodeproj
and make sure the deployment target matches that of your application target. - Select your application project. Under 'TARGETS' select your application, open the 'General' tab, click on the
+
button under the 'Embedded Binaries' and Select 'Cloudinary.framework'.
Usage
Configuration
To use the API, you will need a CLDCloudinary instance, which is initialized with an instance of CLDConfiguration.
The CLDConfiguration must have its cloudName
and apiKey
properties set. Other properties are optional.
See API, URLs and access identifiers for more details.
There are several ways to initialize CLDConfiguration. You can simply call its constructor with the desired params:
let config = CLDConfiguration(cloudName: "CLOUD_NAME", apiKey: "API_KEY")
Another way is by passing a URL of the form: cloudinary://API_KEY:API_SECRET@CLOUD_NAME
let config = CLDConfiguration(cloudinaryUrl: "cloudinary://<API_KEY>:<API_SECRET>@<CLOUD_NAME>")
You can also add the same URL as an environment parameters under CLOUDINARY_URL
, then initialize CLDConfiguration using its static initializer
let config = CLDConfiguration.initWithEnvParams()
Now you can create a CLDCloudinary instance to work with
let cloudinary = CLDCloudinary(configuration: config)
URL generation
The following example generates a URL on an uploaded sample
image:
cloudinary.createUrl().generate("sample.jpg")
// http://res.cloudinary.com/CLOUD_NAME/image/upload/sample.jpg
The following example generates an image URL of an uploaded sample
image while transforming it to fill a 100x150 rectangle:
let transformation = CLDTransformation().setWidth(100).setHeight(150).setCrop(.Crop)
cloudinary.createUrl().setTransformation(transformation).generate("sample.jpg")
// http://res.cloudinary.com/CLOUD_NAME/image/upload/c_fill,h_150,w_100/sample.jpg
Another example, embedding a smaller version of an uploaded image while generating a 90x90 face detection based thumbnail:
let transformation = CLDTransformation().setWidth(90).setHeight(90).setCrop(.Thumb).setGravity(.Face)
cloudinary.createUrl().setTransformation(transformation).generate("sample.jpg")
// http://res.cloudinary.com/CLOUD_NAME/image/upload/c_thumb,g_face,h_90,w_90/sample.jpg
You can provide either a Facebook name or a numeric ID of a Facebook profile or a fan page.
Embedding a Facebook profile to match your graphic design is very simple:
let url = cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(90).setHeight(130).setGravity(.Face).setCrop(.Fill)).setType(.Facebook).generate("billclinton.jpg")
// http://res.cloudinary.com/CLOUD_NAME/image/facebook/c_fill,g_face,h_130,w_90/billclinton.jpg
You can also chain transformations together:
let transformation = CLDTransformation().setWidth(100).setHeight(150).chain().setCrop(.Fit)
let url = cloudinary.createUrl().setTransformation().generate("sample.jpg")
// http://res.cloudinary.com/CLOUD_NAME/image/facebook/h_150,w_100/c_fit/sample.jpg
See our documentation for more information about displaying and transforming images.
Upload
Uploading to your cloud is very straightforward.
In the following example the file located at fileUrl
is uploaded to your cloud:
cloudinary.createUploader().upload(file: fileUrl)
fileUrl
can point to either a local or a remote file.
You can also upload data:
cloudinary.createUploader().upload(data: data)
The uploaded image is assigned a randomly generated public ID, which is returned as part of the response.
You can pass an instance of CLDUploadRequestParams
for extra parameters you'd want to pass as part of the upload request. For example, you can specify your own public ID instead of a randomly generated one.
For a full list of available upload parameters, see the Upload API Reference documentation.
You can also pass a progress
closure that is called periodically during the data transfer, and a completionHandler
closure to be called once the request has finished, holding either the response object or the error.
In the following example, we apply an incoming transformation as part of the upload request, the transformation is applied before saving the image in the cloud. We also specify a public ID and pass closures for the upload progress and completion handler.
let params = CLDUploadRequestParams()
params.setTransformation(CLDTransformation().setGravity(.NorthWest))
params.setPublicId("my_public_id")
let request = cloudinary.createUploader().upload(file: fileUrl, params: params, progress: { (bytes, totalBytes, totalBytesExpected) in
// Handle progress
}) { (response, error) in
// Handle response
}
Every upload request returns a CLDUploadRequest instance, allowing options such as cancelling, suspending or resuming it.
Safe Mobile Requests
You should avoid keeping the sensitive apiSecret
on the mobile device. Instead, if you must perform a signed request, generate the authentication signature on the server side.
You can use any server-side Cloudinary SDK (Ruby on Rails, PHP, Django(Python), Java, .NET, etc.) on your server to generate the signature.
After generating the signature on your server, create a CLDSignature
instance and pass it to the desired secure request.
Download
The SDK provides some convenient methods for downloading files from your cloud:
cloudinary.createDownloader().fetchImage(url)
You can also pass a progress
closure that is called periodically during the data transfer, and a completionHandler
closure to be called once the request has finished, holding either the fetched UIImage or an error.
let request = cloudinary.createDownloader().fetchImage(url, progress: { (bytes, totalBytes, totalBytesExpected) in
// Handle progress
}) { (responseImage, error) in
// Handle response
}
Every download request returns an instance implementing CLDFetchImageRequest, allowing options such as cancelling, suspending or resuming it.
The downloaded image is cached both to the memory and the disk (customizable). The disk cache size is limited and can be changed.
Other APIs
Management APIs are available as well, via CLDManagementApi
cloudinary.createManagementApi()
See out documentation for further details.
Additional resources
Additional resources are available at:
- Website
- Interactive demo
- Features overview
- Documentation
- Knowledge Base
- Image transformations documentation
- Upload API documentation
How to open the example project
To open the example project, follow these steps:
- Open to "Example" folder
- Open the "Cloudinary.xcworkspace"
Support
You can open an issue through GitHub.
Contact us at https://cloudinary.com/contact.
Stay tuned for updates, tips and tutorials: Blog, Twitter, Facebook.
Join the Community
Impact the product, hear updates, test drive new features and more! Join here.
License
Cloudinary is released under the MIT license. See LICENSE for details.
Github
link |
Stars: 131 |
You may find interesting
Releases
Version 2.10.0 - 2021-01-10T14:35:33
New functionality
- Add Upload Widget (#320)
- Add support for crop preprocess action (#263)
- Add support for rotation preprocess action (#264)
- Add support for enhanced quality analysis scores
- Add support for user defined variables and conditional expressions (#238)
- Support array of values for radius (#235)
- Add
eval
parameter to the upload Params. - Add support for accessibility analysis (#260)
- Add option to control url signature algorithm (#256)
- Add support for custom pre-functions (#253)
- Add support for Long signature in URLs (#250)
- Add global timeout support(#251)
- Add OCR support un transformations and Upload APIs.
Other changes
- Add checks to validate responsive transformation.
- Fix space encoding in a generated URL (#274)
- Change local cache-keys encoding to
sha256
- Fix OCR parameter usage in
UploadRequestParamsTests
(#262) - Support urls with mime-type suffix in uploader.
- Update SPM definitions file (#234)
Version 2.9.0 - 2020-04-16T12:58:44
- Remove Alamofire dependency (#229)
- Add Swift Package Manager support.
- Add Carthage support.
- Rearrange workspace (#226)
- Add support for
assist_colorblind
effect. (#227) - Validate URL scheme (#224)
Version 2.9.0-beta.2 - 2020-04-05T16:54:39
- Remove Alamofire dependency (#229)
- Fix Carthage support.
Version 2.7.0 - 2019-04-07T08:46:04
New functionality
- Support swift 5, fix related warnings.
- Bump Alamofire version to 4.8.2
- Add support for fetch layer in transformations. (#197)
- Add support for
quality_analysis
parameter in upload. (#195) - Add support for font antialiasing and hinting in text overlays. (#193)
- Add support for
streaming_profile
param inCLDTransformation
. (#194) - Support excluding the default version from the generated cloudinary-url. (#206)
- Add quality_override parameter to upload/explicit. (#199)
Other changes
- Replace crypto kit files with
CommonCrypto
import. - Fix memory cache limit not getting initially set in
CLDImageCache
(#201) - Fix bas64 string validation in uploader. (#196)
Version 2.6.1 - 2019-01-30T16:38:07
New functionality
- Add support for google storage (
gs://
) urls in uploader. (#184) - Add support for
fps
parameter in Transformations. (#182) - Add format field to responsive breakpoints in upload params (#152)
- Add
removeFromCache
toCLDCloudinary
Other changes
- Bump Alamofire version to 4.8.1
- Fix project setup and tests for swift 4.2 (#191)
- Add device and os data to user agent. (#180)
- Remove duplicate Alamofire reference
Version 2.5.0 - 2018-11-05T16:11:56
- Add String extensions for base64 encoding
- Add
@discardableResult
annotations for uploadLarge methods - Migrate to Swift 4.2
- Fix duplicate upload callbacks when using preprocessing
- Bump Alamofire to version to 4.7.3
Version 2.4.0 - 2018-06-26T08:54:48
New functionality
- Add support for
async
upload parameter - Add support for eager transformation format
- Add support for automatic quality in transformations. (#150)
- Add cache max-memory config (#98)
- Add Keyframe interval transformation parameter (#90)
Other changes
- Refactor CLDBaseParam for compatibility with iOS 11.4
- Remove wrong project config (library search paths)
- Bump Alamofire version to 4.7.2
- Fix Alamofire submodule definition
- Fix signature parameter handling in Management Api. (#161)
- Fix
faceCenter
andfacesCenter
values inCLDGravity
(#159) - Fix calculation of UIImage memory cache cost
Version 2.3.0 - 2018-03-19T10:01:32
- Add access control parameter to upload
Version 2.2.2 - 2018-03-19T10:00:46
- Add baseline Objective-C test.
- Use
@objcMembers
where applies, for improved Objective-C compatibility.
Version 2.2.1 - 2018-03-19T09:58:25
- Fix objective-c compatibility issues with
CLDResponsiveParams
properties.
Version 2.2.0 - 2018-03-19T09:57:46
New functionality
- Add support for responsive image download
- Add
auto
toCLDGravity
Other changes
- Fix synchronization issue when using
cldSetImage()
onUIViews
within view collections.
Version 2.1.0 - 2018-03-19T09:57:18
New functionality
- Add image preprocessing and validations
- Resizing
- Format and quality settings
- Support for custom preprocessors and validators
Other changes
- Remove custom operators
- Update Alamofire to version 4.6.0
Version 2.0.4 - 2018-03-19T09:56:51
- Fix user-agent sdk version
- Replace CommonCrypto wrapper with CryptoKit based code
- Remove autotagging test (behaviour change)
- Support Swift 4
Version 2.0.3 - 2018-03-19T09:56:21
New functionality
- Add support for chunked upload
Other changes
- Update Readme to point to HTTPS URLs of cloudinary.com
- Fix manual installation repository url.
Version 2.0.2 - 2017-06-08T14:02:17
New functionality
- Support SEO suffix for private images.
Other changes
- Escape
|
and=
characters in context values. - Double encode commas and slashes instead of using special UTF-8 values
- Generate CLDCrypto framework in every build. Fixes #80.
- Removing extra CLDCrypto path from podspec
- Update
README.md
Alamo version to 4.1.0 - Add 3 images in PhotoViewController to demonstrate transformations.
- Add progress indicator
- Updated the framework and project deployment target to 8.0, updated podspec deployment target to 8.0
- Fixed signed upload using CLDSignature - Added unit test to test a signed upload using CLDSignature
Version 2.0.1 - 2017-01-24T19:12:23
- Fix pod install issue. Fixes #57.
- Fix shellScript
- Fix URLs in tests
- Increment Alamofire to ~>4.1. Fixes #59.
- Update configuration
Version 2.0.0 - 2017-01-18T15:44:14
New Code, New API, Swift 3.0!