iCloud Drive and DocumentPicker for iOS 8: Explained

July 15, 2014

iCloud Drive and its associated DocumentPicker are new features of iOS 8 that allow the app you're using to open files created in a different app, import them, move them, or export them right back out again, all without creating any unnecessary steps or complicated workflows. Everything is also automatically synced through iCloud, so changes made in one app won't only be reflected back in the original app that created the file, but on all your devices. It's yet another way inter-app communication has come to the iPhone and iPad. So, how do iCloud Drive and DocumentPicker work?

From work to workflow

One of the design goals of the original iPhone and iPhone OS was to liberate mainstream customers from the legacy and tyranny of the file system — to prevent documents being strewn over a desktop or buried in a hierarchy. Sure, some people loved file systems and others learned to cope with them, but to many more they are simply confusing, inaccessible, and ultimately inhuman.

For the Photos app, Apple provided a fairly flat repository which included the Camera Roll and an ImagePicker so that other apps could pull images out and, eventually, save them back. It was a duplicative procedure, however, and it only worked with photos and videos in that repository.

For other files, you could access and edit them freely from within the app that created them, but they were "private" — invisible to any other app. The best you could do, if you wanted to move a file around, was to go to the original app and, if implemented, use the "Open In..." functionality to export a copy to another app. At that point, however, they were treated as separate files and changes made in one app weren't reflected in the other.

It was maddening and I begged for years for Apple to give us a DocumentPicker equivalent to ImagePicker instead.

Well, with iOS 8, they have.

How iCloud Drive works

There are many different types of files. Text files, documents, spreadsheets, presentations, and images are all common types. The saved state of a chess game, however, is also a file. Anything a person would consider its own discreet entity, and could possibly want to share or do something with can be considered a file.

In iOS, all files created by an app are kept safe and secure inside that app's container. In iOS 8, to make files accessible outside their app's container — without scrapping the security — Apple is allowing developers to make those containers "public" — to make them visible.

So, with iOS 8, when you tap to open a file, and choose iCloud Drive as your source, instead of just the files associated with the app you're in, you'll see folders representing all the other apps installed on your iPhone or iPad that have their containers set to public. Tap on one of the folders and you see the files contained in that app. Tap on one of those files and you punch a hole in the sandbox just big enough to get access to the file.

Once you've access an external file, that file will remain accessible to the current app and to you, right alongside the internal files. iOS keeps its preview thumbnail and name — along with an optional annotation to show which app it comes from — readily available. In other words, your inter-app permission is persistent.

So, of example, if you're in Pages and tap to open a file, then tap iCloud Drive, and you see the Editorial App folder, you can tap on that, and then tap on your Bucket List file. Pages will then open a version of the file and let you work on it. Changes you make will be saved back to the version in Editorial. And Bucket List - Editorial will, from then on, be listed alongside all your local Pages documents.

Same with an image you started in Brushes but want to continue in Prototype, if both apps choose to support it. Same with a chess game you want to email to a friend so they can continue it for you in their version of the same chess app.

Instead of opening files, iCloud Drive can also be used to import them instead. For example, if you wanted to bring slides from one Keynote deck into another, the file with the additional slides could be imported instead of opened. Likewise if you wanted to import an image into a Pages document.

In addition to import, documents can be exported to other apps if you don't want to keep a copy in the current app.

iCloud Drive launches with a grid view that shows you all files stored directly in iCloud Drive, as well as all the apps that have files stored in their own containers in iCloud Drive. Apps are distinguished by their icons placed on top of folders.

That way, as long as you remember which app created the file, you'll have an easy way to find it. If you can't, there's a handy search box. You can also change the view from grid to list, and in list view you can quickly sort by date, name, and even tags.

Yeah. Tags.

Developing for iCloud Drive and DocumentPicker.

With iOS 8, the iCloud daemon has been rewritten on top of CloudKit, Apple's new server-side API. To avoid data loss due to read/write conflicts spanning multiple apps and devices, Apple stresses the importance of using file coordination. (The iCloud daemon makes it impossible to assume there's only ever one process accessing a file at any one time.) This avoids file corruption and data loss for customers, which is paramount.

Apple has provided frameworks to make file coordination easy, including background cues, with high, middle, and low-level options. Unlike the previous, synchronous file coordination APIs, Apple has also provided new, asynchronous APIs. The metadata query API is also easier and faster to use, with "stitching" available, so you don't have to wait long periods of time for the information to move over. Metadata can also be accessed and displayed, even for non-local documents. (And listing documents doesn't require file coordination.)

Document previews are encouraged because they make files more recognizable. iOS 8 makes it much, much easier to generate them as well. Apple lets developers pull an array of 1024x1024 thumbnails for a documents, and when changes are saved, updated thumbnails will be generated and synced across devices.

Apple provides the DocumentPicker interface to handle all the interactions and to keep everything secure. DocumentPicker is what discovers files outside the current app's container, and what people use to grant permission to access and edit those documents.

In order for DocumentPicker to discover files, the app that created those files has to signal that its container is public. If an app's container is public, its icon will show up either inside a folder in the grid view or by itself in the list view. Developers can specify the types of files their app works with, so only those file types are shown in the DocumentPicker. That keeps it focused and makes any given file easier to find.

Once a file from another app container is opened in a new app, Apple provides a document reference as well as metadata. That way developers can list both the local files internal to their app, and the external files made available from other apps, all in the same interface, making it easier to re-open those external files again and again. (However, Apple recommends annotating those files with the name of their originating app, just to keep things clear.

When files are imported rather than opened, iOS makes them available only temporarily. If developers want to hold on to the contents longer, they need to copy them inside the app.

Apple also provides mechanisms for state restoration, including bookmarking. That way, you can leave a document in one app, open it in another, and pick up right where you left off.

iCloud Drive and DocumentPicker security

In iOS, by default, no app can access the container of another app. Getting around that requires an explicit human override, namely opening DocumentPicker and tapping an external document to indicate you want to access it outside its container. DocumentPicker runs "out-of-process" for that reason — so it can see all apps in all public containers.

When you tap on an external file, DocumentPicker returns a "security scoped" URL. That informs the kernel and the current app that it's allowed to open and modify the file.

These security scoped URLs can't be saved and accessed arbitrarily. They'll lose their security if they are. So, Apple provides ways for them to be safely, securely recorded so they can be used for populating lists, restoring state, bookmarking, etc.

Bottom line

iCloud Drive and DocumentPicker are quantum leaps forward when it comes to file handling on iPhone and iPad. I could quibble about thee being no iCloud Drive app, so i can't simply browse all my files, or that there doesn't yet seem to be a way to access DocumentPicker from within the Mail app, like there is the ImagePicker. As a first step, however, both iCloud Drive and DocumentPicker are grand.

Since Extensibility lets third party storage providers like Dropbox and corporate document stores hook in as well, they maintain much of the simplicity of iOS while returning much of the power of computing.

In other words, iCloud Drive and DocumentPicker show we really can have nice things.