iCloud Design Guide

About Incorporating iCloud into Your App

Important: This is a preliminary document that includes descriptions of OS X technology in development. This information is subject to change, and software implemented according to this document should be tested with final operating system software and final documentation.

iCloud is a free service that lets users access their personal content on all their devices—wirelessly and automatically via Apple ID. iCloud does this by combining network-based storage with dedicated APIs, supported by full integration with the operating system. Apple provides server infrastructure, backup, and user accounts, so you can focus on building great iCloud-enabled apps.

The core idea behind iCloud is to eliminate explicit synchronization between devices. A user never needs to think about syncing, and your app never interacts directly with iCloud servers. When you adopt iCloud storage APIs as described in this document, changes appear automatically on all the devices attached to an iCloud account. Your users get safe, consistent, and transparent access to their personal content everywhere.

At a Glance

iCloud is all about content, so your integration effort focuses on the model layer of your app. Because instances of your app running on a user’s other devices can change the local app instance’s data model, you design your app to handle such changes. You might also need to modify the user interface for presenting iCloud-based files and information.

In one important case, Cocoa adopts iCloud for you: A document-based app for OS X v10.8 or later requires very little iCloud adoption work, thanks to the capabilities of the NSDocument class.

There are many different ways you can use iCloud storage, and a variety of technologies available to access it. This document introduces all the iCloud storage APIs and offers guidance in how to design your app in the context of iCloud.

iCloud Supports User Workflows

Adopting iCloud in your app lets your users begin a workflow on one device and finish it on another.

Say you provide a podcast app. A commuter subscribes to a podcast on his iPhone and listens to the first 20 minutes on his way to work. At the office, he launches your app on his iPad. The episode automatically downloads and the play head advances to the point he was listening to.

Or say you provide a drawing app for iOS and OS X. In the morning, an architect creates some sketches on her iPad while visiting a client. On returning to her studio, she launches your app on her iMac. All the new sketches are already there, waiting to be opened and worked on.

To store state information for the podcast app in iCloud, you’d use iCloud key-value storage. To store the architectural drawings in iCloud, you’d use iCloud document storage.

Prepare for iCloud with Provisioning and Entitlements

The first two steps in adopting iCloud for your app are to obtain an appropriate provisioning profile for your development device and to request the appropriate entitlements in your Xcode project.

Note: iCloud entitlements are available only to apps submitted to the App Store or to the Mac App Store.

Entitlements are key-value pairs that request capabilities for your app—such as the capability to use iCloud. Your iCloud entitlement values define where your app can place data, and they ensure that only your apps are allowed to access that data. You request separate entitlements for document storage and key-value storage. When you code sign your app, these requests become part of your app’s code signature.

How to Use This Document

Whether you are developing for iOS, OS X, or both, and no matter which sort of app you are developing, start by reading the entire iCloud Fundamentals chapter to get the foundation that all iCloud developers need.

The iOS and OS X document architectures automatically provide most of the iCloud functionality needed by document-based apps. If your app works with file-based information, you’ll want to read Designing for Documents in iCloud.

See Also

This document describes the pieces you need to support iCloud in your app but does not teach you how to develop apps. For that, start with Start Developing iOS Apps Today or Start Developing Mac Apps Today, and read the following documents: