Cloudinary Blog

Direct 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 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.

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 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:
Cloudinary::Uploader.unsigned_upload("sample.jpg", "zcudy0uz", :cloud_name => "demo")
iOS:
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:
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:
Cloudinary::Uploader.unsigned_upload("sample.jpg", "zcudy0uz", :cloud_name => "demo", 
  :public_id => "user_sample_image_1001", :tags => "ruby_upload")
iOS:
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:
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:
cl_image_tag("user_sample_image_1001.jpg", :height=>100, :gravity=>"face", :width=>150, :crop=>"thumb")
PHP:
cl_image_tag("user_sample_image_1001.jpg", array("height"=>100, "gravity"=>"face", "width"=>150, "crop"=>"thumb"))
Python:
CloudinaryImage("user_sample_image_1001.jpg").image(height=100, gravity="face", width=150, crop="thumb")
Node.js:
cloudinary.image("user_sample_image_1001.jpg", {height: 100, gravity: "face", width: 150, crop: "thumb"})
Java:
cloudinary.url().transformation(new Transformation().height(100).gravity("face").width(150).crop("thumb")).imageTag("user_sample_image_1001.jpg");
JS:
cloudinary.imageTag('user_sample_image_1001.jpg', {height: 100, gravity: "face", width: 150, crop: "thumb"}).toHtml();
jQuery:
$.cloudinary.image("user_sample_image_1001.jpg", {height: 100, gravity: "face", width: 150, crop: "thumb"})
React:
<Image publicId="user_sample_image_1001.jpg" >
  <Transformation height="100" gravity="face" width="150" crop="thumb" />
</Image>
Angular:
<cl-image public-id="user_sample_image_1001.jpg" >
  <cl-transformation height="100" gravity="face" width="150" crop="thumb">
  </cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Height(100).Gravity("face").Width(150).Crop("thumb")).BuildImageTag("user_sample_image_1001.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().height(100).gravity("face").width(150).crop("thumb")).generate("user_sample_image_1001.jpg");
iOS:
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).

<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.

$('.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.

$('.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:
cl_unsigned_image_upload_tag(:photo, "zcudy0uz", :cloud_name => "demo", 
  :tags => "test_upload")
PHP:
<?php echo cl_unsigned_image_upload_tag('zcudy0uz', 
    $upload_preset, array("cloud_name" => "demo", "tags" => "test_upload")); ?>
Node.js:
cloudinary.uploader.unsigned_image_upload_tag('photo', 'zcudy0uz', 
  { cloud_name: 'demo', tags: 'test_upload' });
Java:
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.

The Angular sample project is available as an open source GitHub project.

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!

You can also check out this Visual Web resource on Client-side Image Upload.

Recent Blog Posts

 New Image File Format: FUIF:Lossy, Lossless, and Free

I've been working to create a new image format, which I'm calling FUIF, or Free Universal Image Format. That’s a rather pretentious name, I know. But I couldn’t call it the Free Lossy Image Format (FLIF) because that acronym is not available any more (see below) and FUIF can do lossless, too, so it wouldn’t be accurate either.

Read more
Optimizing Video Streaming and Delivery: Q&A with Doug Sillars

Doug Sillars, a digital nomad and a freelance mobile-performance expert, answers questions about video streaming and delivery, website optimization, and more.

Doug Sillars, a freelance mobile-performance expert and developer advocate, is a Google Developer Expert and the author of O’Reilly’s High Performance Android Apps. Given his extensive travels across the globe—from the UK to Siberia—with his wife, kids, and 11-year-old dog, Max, he has been referred to as a “digital nomad.” So far in 2018, Doug has spoken at more than 75 meetups and conferences!

Read more
Building a Music Discovery Service

In May 2018, Cloudinary sponsored Capitol Music Group’s first hackathon held by its new Capitol360 Innovation Center, which aims at connecting musicians and software technologists to facilitate and stimulate the creation of music. See this interview for details. As a starter project for the hackathon, we built a sample app called Music Discovery Service.

Read more
Once a Hackathon Participant, Now a Judge

Over the past several years, I've had a chance to participate in hackathons, as part of teams that developed a social payment app and helped users decide meals to cook. But it wasn't until last month that I got to experience a hackathon from the other side, as a judge.

Read more
10 Website Videos Mistakes and How to Solve Them

It should come as no surprise that video use on the internet is exploding. You can see the dramatic growth of video on the average site in this SpeedCurve blog post.

With the growth in video comes greater bandwidth use, which is not only costly for your IT budget, but for your visitors as well. Beyond the expense, there is the user experience to consider. The heavier the page, the longer it will take to load, and the greater likelihood visitors will abandon your site. Page load speed is also an important factor in SEO ranking, so clearly video is something we need to take seriously and get right. Video is challenging, presenting terms still unfamiliar to developers - like codecs, bitrate and adaptive bitrate streaming. As a result, mistakes are being made in video implementation.

Read more
Android Data Saver: Optimizing Mobile Data Usage with Cloudinary

Over the life of a mobile device, the cost of a cellular data plan often exceeds that of the device itself. To optimize data usage and purge useless data on their mobile devices, users can enable Data Saver from Android 7.0 (API level 24). To do so, users toggle Data Saver in quick settings under the Notification shade or under Settings > Data usage. With Data Saver enabled, apps that aren't whitelisted cannot use cellular data in the background. They are also directed to consume less data while active.

Read more