Cloudinary Blog

Direct Image Upload Made Easy, From Browser or Mobile App to the Cloud

Direct Image Upload From Browser or Mobile App to the Cloud

Handling user uploaded images and other files on your website can be a time consuming task. As images grow larger, uploading and processing them becomes more and more complex. For example, common upload issues for images and other files may relate to browser limitations, server configuration issues, memory and timeout issues. Specifically, handling user uploaded images on your website can be a hassle. In this post, we'll show how Cloudinary's cloud-based image management service can help you turn user uploading into a lightweight operation that bypasses your servers altogether.

How do you handle user file uploads today? If images are uploaded directly to your servers, this requires some heavy server-side processing, bandwidth and storage space. One way to offload images is to transfer them to cloud storage. But if you're handling the upload operation on your own servers (and then transferring them to the cloud), this is still wasteful of server resources.

A smarter option is to enable uploading of images directly from users' browsers to the cloud. In a previous post, we showed how to do this with Cloudinary's cloud-based image management solution, via our jQuery plugin. We also enable this for mobile apps via the iOS and Android SDKs. But this still requires a small server-side component to handle authentication.


Sign up for Cloudinary free today!


Now we're happy to introduce a new option that simplifies the upload process and completely bypasses your servers - Direct unsigned upload. You can now upload directly from the browser or app to Cloudinary with no predefined authentication. Instead, upload options are controlled by centralized configuration. This is easier to implement and is more suitable for modern client-side and mobile apps with a fast, dynamic UI.

Direct unsigned uploading of images to the cloud: how it works

Cloudinary is a cloud-based, end-to-end media management solution that automates and streamlines your entire media asset workflow, from upload to manipulation to delivery via multiple CDNs.

Previously, we required that all images uploaded are signed with your account's API secret. Now, you can call Cloudinary's upload API without signing with your API secret (we call this 'unsigned'). This allows you to perform upload directly from a browser or mobile app without going through your servers at all. For security reasons, not all upload parameters can be specified directly when performing unsigned upload calls.

First, you need to enable unsigned uploading for your Cloudinary account from the Upload Settings page. If you don't have a Cloudinary account already, you can set it up for free.

Enable unsigned upload

Enabling unsigned uploading creates an 'upload preset' with a unique name, which explicitly allows uploading of images without the API secret. The preset also defines which upload options will be applied to images that are uploaded unsigned.

A preset name is randomly generated by default, to ensure uniqueness. You can edit this default name at any point in time, and define which upload parameters should be applied in this preset. The interface allows you to create presets, list them, edit existing presets and delete unused presets. Read more about upload presets in this post: Centralized control for direct image upload.

Now, in order to perform unsigned upload, simply call Cloudinary's upload API while setting the upload_preset parameter to the unique name. No need to set the API Key and Secret credentials of your account.

The following code samples show a direct unsigned upload API call in Objective-C for iOS, Java for Android and Ruby:

Ruby:
Copy to clipboard
Cloudinary::Uploader.unsigned_upload("sample.jpg", "zcudy0uz", :cloud_name => "demo")
iOS-ObjC:
Copy to clipboard
CLCloudinary *cloudinary = [[CLCloudinary alloc] init];
[cloudinary.config setValue:@"demo" forKey:@"cloud_name"];

NSString *imageFilePath = [[NSBundle mainBundle] pathForResource:@"logo" 
  ofType:@"png"];

CLUploader* uploader = [[CLUploader alloc] init:cloudinary delegate:self];
[uploader unsignedUpload:imageFilePath uploadPreset:@"zcudy0uz" options:@{}];
Android:
Copy to clipboard
InputStream getAssetStream(String filename) throws IOException {
  return getInstrumentation().getContext().getAssets().open(filename);
}

Map config = new HashMap();
config.put("cloud_name", "demo");
Cloudinary cloudinary = new Cloudinary(config);

cloudinary.uploader().unsignedUpload(getAssetStream("sample.jpg"), "zcudy0uz", 
  Cloudinary.emptyMap());

Upload options for unsigned image uploads

The 'unsigned upload preset' discussed in the previous section globally controls all upload requests coming directly from user browsers or mobile apps, which are not signed with the account API Secret. For example, you can define via the preset that after upload, Cloudinary should eagerly generate thumbnails, mark images for moderation, detect faces, analyze colors and more - and these operations will be performed after every unsigned image upload.

In addition to these global parameters in the 'unsigned upload preset', there are certain parameters you can specify for specific unsigned upload requests: public_id to assign a unique identifier to the uploaded image (while not overwriting an existing image with the same ID), tags to add tags, folder to store the image in a folder, context key-value pairs of meta data, and face_coordinates to specify custom coordinates for incoming cropping or further thumbnail generation.

The following code samples show a more advanced example: specifying a custom public ID of user_sample_image_1002, making it possible to later access the uploaded image, and assigning a tag to simplify management of the images. In addition, we show an example of building a dynamic URL that performs an on-the-fly image manipulation: generating a 150x100 face-detection-based thumbnail of the uploaded images for embedding in your application.

Ruby:
Copy to clipboard
Cloudinary::Uploader.unsigned_upload("sample.jpg", "zcudy0uz", :cloud_name => "demo", 
  :public_id => "user_sample_image_1001", :tags => "ruby_upload")
iOS-ObjC:
Copy to clipboard
NSData *imageData = [NSData dataWithContentsOfFile:imageFilePath];

[uploader unsignedUpload:imageData uploadPreset:@"zcudy0uz" options:[NSDictionary dictionaryWithObjectsAndKeys:@"user_sample_image_1002", @"public_id", @"tags", @"ios_upload", nil] withCompletion:^(NSDictionary *successResult, NSString *errorResult, NSInteger code, id context) {

    if (successResult) {

      NSString* publicId = [successResult valueForKey:@"public_id"];
      NSLog(@"Upload success. Public ID=%@, Full result=%@", publicId, successResult);
      CLTransformation *transformation = [CLTransformation transformation];
      [transformation setWidthWithInt: 150];
      [transformation setHeightWithInt: 100];
      [transformation setCrop: @"fill"];
      [transformation setGravity:@"face"];
                
      NSLog(@"Result: %@", [cloudinary url:publicId options:@{@"transformation": transformation, @"format": @"jpg"}]);                

    } else {

      NSLog(@"Upload error: %@, %d", errorResult, code);            

    }

  } andProgress:^(NSInteger bytesWritten, NSInteger totalBytesWritten, NSInteger totalBytesExpectedToWrite, id context) {
    NSLog(@"Upload progress: %d/%d (+%d)", totalBytesWritten, totalBytesExpectedToWrite, bytesWritten);
  }];
Android:
Copy to clipboard
InputStream getAssetStream(String filename) throws IOException {
  return getInstrumentation().getContext().getAssets().open(filename);
}

Map config = new HashMap();
config.put("cloud_name", "demo");
Cloudinary cloudinary = new Cloudinary(config);

cloudinary.uploader().unsignedUpload(getAssetStream("sample.jpg"), "zcudy0uz", 
  Cloudinary.asMap("public_id", "user_sample_image_1001", "tags", "android_upload"));

The response of the API call includes the public ID of the uploaded image, URLs for accessing the image through a CDN and additional details. Here's another example of Cloudinary's dynamic image manipulation: a 150x100 face-detection-based thumbnail of the uploaded image.

Ruby:
Copy to clipboard
cl_image_tag("user_sample_image_1001.jpg", :height=>100, :gravity=>"face", :width=>150, :crop=>"thumb")
PHP v1:
Copy to clipboard
cl_image_tag("user_sample_image_1001.jpg", array("height"=>100, "gravity"=>"face", "width"=>150, "crop"=>"thumb"))
PHP v2:
Copy to clipboard
(new ImageTag('user_sample_image_1001.jpg'))
  ->resize(Resize::thumbnail()->width(150)->height(100)
    ->gravity(Gravity::focusOn(FocusOn::face())));
Python:
Copy to clipboard
CloudinaryImage("user_sample_image_1001.jpg").image(height=100, gravity="face", width=150, crop="thumb")
Node.js:
Copy to clipboard
cloudinary.image("user_sample_image_1001.jpg", {height: 100, gravity: "face", width: 150, crop: "thumb"})
Java:
Copy to clipboard
cloudinary.url().transformation(new Transformation().height(100).gravity("face").width(150).crop("thumb")).imageTag("user_sample_image_1001.jpg");
JS:
Copy to clipboard
cloudinary.imageTag('user_sample_image_1001.jpg', {height: 100, gravity: "face", width: 150, crop: "thumb"}).toHtml();
jQuery:
Copy to clipboard
$.cloudinary.image("user_sample_image_1001.jpg", {height: 100, gravity: "face", width: 150, crop: "thumb"})
React:
Copy to clipboard
<Image publicId="user_sample_image_1001.jpg" >
  <Transformation height="100" gravity="face" width="150" crop="thumb" />
</Image>
Vue.js:
Copy to clipboard
<cld-image publicId="user_sample_image_1001.jpg" >
  <cld-transformation height="100" gravity="face" width="150" crop="thumb" />
</cld-image>
Angular:
Copy to clipboard
<cl-image public-id="user_sample_image_1001.jpg" >
  <cl-transformation height="100" gravity="face" width="150" crop="thumb">
  </cl-transformation>
</cl-image>
.NET:
Copy to clipboard
cloudinary.Api.UrlImgUp.Transform(new Transformation().Height(100).Gravity("face").Width(150).Crop("thumb")).BuildImageTag("user_sample_image_1001.jpg")
Android:
Copy to clipboard
MediaManager.get().url().transformation(new Transformation().height(100).gravity("face").width(150).crop("thumb")).generate("user_sample_image_1001.jpg");
iOS:
Copy to clipboard
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setHeight(100).setGravity("face").setWidth(150).setCrop("thumb")).generate("user_sample_image_1001.jpg")!, cloudinary: cloudinary)
Face detection based thumbnail

Direct uploading from the browser using jQuery

Cloudinary's jQuery plugin allows you to easily add an upload control to your web site, which allows to directly upload an image from their browsers to the cloud. Now you can use dynamic Javascript code to add direct upload controls to your rich client-side web application.

First, include Cloudinary's jQuery plugin and all dependent Javascript files (if you use our server-side client libraries for rendering your pages, there are helper methods for including all required JS files).

Copy to clipboard
<script src='jquery.min.js' type='text/javascript'></script>
<script src='jquery.ui.widget.js' type='text/javascript'></script>
<script src='jquery.iframe-transport.js' type='text/javascript'></script>
<script src='jquery.fileupload.js' type='text/javascript'></script>
<script src='jquery.cloudinary.js' type='text/javascript'></script>

Now you can use the unsigned_upload_tag method to create a new tag specifying an unsigned direct upload. You need to specify the cloud name of your Cloudinary account and the unique name of an unsigned upload preset defined in your account.

Copy to clipboard
$('.upload_form').append($.cloudinary.unsigned_upload_tag("zcudy0uz", 
  { cloud_name: 'demo' }));

Direct uploading is initiated automatically after a file is selected or dragged. An input field is automatically added to your form with the identifier of the uploaded image for referencing in your model.

Further upload options can be specified, and you can bind to upload progress and completion events, to update your application and UI accordingly. In addition, you can transform an existing input file field into an unsigned direct upload widget.

Update (08/17): Make sure your input field includes the name="file" and type="file" attributes.

The following sample Javascript code demonstrates these options. When an 'upload completed' call is received, it dynamically adds an image tag to the page, with a dynamically-generated 150x100 face-detection based thumbnail of the uploaded image, while applying a saturation increase effect.

Copy to clipboard
$('.upload_field').unsigned_cloudinary_upload("zcudy0uz", 
  { cloud_name: 'demo', tags: 'browser_uploads' }, 
  { multiple: true }
).bind('cloudinarydone', function(e, data) {

  $('.thumbnails').append($.cloudinary.image(data.result.public_id, 
    { format: 'jpg', width: 150, height: 100, 
      crop: 'thumb', gravity: 'face', effect: 'saturation:50' } ))}

).bind('cloudinaryprogress', function(e, data) { 

  $('.progress_bar').css('width', 
    Math.round((data.loaded * 100.0) / data.total) + '%'); 

});

Direct uploading from the browser uses modern cross-origin resource sharing (CORS) methods. In order to support old Internet Explorer browsers, you should place cloudinary_cors.html in the root of your web application (or set the callback upload parameter to the correct relative path or URL of this file in your web site).

Server-side upload tag rendering

When we introduced signed direct uploading from the browser a while ago, we added view helper methods for rendering direct file upload input fields from the server-side code of your favorite development frameworks.

If your web pages are rendered on the server-side and you still wish to support unsigned uploads, you can use the following new view helper methods for Ruby on Rails, PHP, Java and Node.js:

Ruby:
Copy to clipboard
cl_unsigned_image_upload_tag(:photo, "zcudy0uz", :cloud_name => "demo", 
  :tags => "test_upload")
PHP:
Copy to clipboard
<?php echo cl_unsigned_image_upload_tag('zcudy0uz', 
    $upload_preset, array("cloud_name" => "demo", "tags" => "test_upload")); ?>
Node.js:
Copy to clipboard
cloudinary.uploader.unsigned_image_upload_tag('photo', 'zcudy0uz', 
  { cloud_name: 'demo', tags: 'test_upload' });
Java:
Copy to clipboard
cloudinary.uploader().unsignedImageUploadTag("image_id", zcudy0uz, 
  Cloudinary.asMap("tags", "test_upload"), Map<String, Object> htmlOptions);

cloudinary.uploader().imageUploadTag("image_id", options, htmlOptions);

Sample client-side web projects

We've updated the sample projects of Cloudinary's client libraries (Ruby on Rails, PHP,  Django, Java) to demonstrate unsigned direct uploading with server-side rendering of the initial upload control.

In addition, to demonstrate direct unsigned uploading in client-side-only apps, we've build a sample photo album project in AngularJS. Our project uses the jQuery plugin to perform direct uploading to Cloudinary, and then uses Cloudinary to list uploaded images, further manipulate images, and deliver them via a fast CDN.

Summary

Direct uploading to the cloud from a browser or mobile app is very powerful. Unsigned uploading makes this much simpler to use in modern apps, while security measures are taken to detect and prevent abuse attempts.

This means that Cloudinary takes care of the entire image management flow - simply call the upload API from your mobile app, or include a single jQuery line in your web app, and images are uploaded directly to Cloudinary. No need for a server-side component at all, you can control upload options using presets from a centralized location, and then dynamically manipulate your images and deliver them from a fast CDN, using nothing but client-side code.

Direct uploading from the browser is one of Cloudinary's most popular features. However, the need to generate server-side signature made usage a bit more complex, especially for modern, dynamic, client-side apps. With our new unsigned upload support, and the new utility methods of the jQuery plugin and other frameworks, we believe direct upload has become much simpler, and you should definitely try it out. Any feedback will be appreciated!

About Cloudinary

Cloudinary provides easy-to-use, cloud-based media management solutions for the world’s top brands. With offices in the US, UK and Israel, Cloudinary has quickly become the de facto solution used by developers and marketers at major companies around the world to streamline rich media management and deliver optimal end-user experiences.

For more information, visit www.cloudinary.com or follow us on Twitter.


Further Reading on File Upload

Recent Blog Posts

WebPerf, Media Optimization, and Core Web Vitals

Optimized media assets have always been essential to website performance. To help developers measure, understand and improve website performance, Google created Core Web Vitals, a subset of Web Vitals that focuses on three aspects of the user experience: loading, interactivity, and visual stability. In June 2021, Google plans to make page experience a ranking factor—so Core Web Vitals and media asset optimization will become even more important.

Read more
Auto-Tag Videos With Cloudinary: A Tutorial

Video is one of the best ways for capturing audience attention. Product demonstrations, property tours, tutorials, and keynotes all make great content—provided that they’re readily searchable by your team and visitors alike. Even though tagging and categorization help organize videos and make them easy to find, the labeling process is labor intensive, taking time away from key tasks like creating new videos.

Read more
Video Uploads With Cloudinary

Setting up the infrastructure for video uploads can go from straightforward to complex real fast. Why? Because many challenges are involved in building a foolproof service for an efficient and smooth process.

Read more
Optimize Media to Get Ready for Google’s Core Web Vitals

For years, Google has been updating its search algorithm to prioritize end-user experience, displaying the most relevant and helpful content at the top of search results. The latest—and maybe the most significant—update so far is Core Web Vitals (CWVs), which are new metrics announced a year ago that will, starting in June, begin determining search rankings. With this update, Google is being abundantly clear that visual experience of webpages is paramount.

Read more
Compressing, Resizing, and Optimizing Videos in Laravel

Videos are large media files—in most cases, at least four times larger than images—and are often created for ads, marketing campaigns, and instructional content to convey as much information as possible in a short time. Ensuring that videos do not buffer all the time and that the user’s data is protected from rapid consumption due to heavy page weight must be the modus operandi for all website builders and e-business owners.

Read more