Guides and Sample Code


macOS Human Interface Guidelines



iCloud helps people access the content they care about regardless of which device they’re currently using. When you support iCloud in your app, users can use different instances of your app on different devices to view and edit their content without performing explicit synchronization. To enable this user experience, it’s likely that you’ll need to reexamine the ways in which you store, access, and present information (especially user-created content) in your app. For some tips on ways to structure your app so that it works well with iCloud, and to learn about the iCloud programming interfaces, see iCloud Design Guide.

image: ../Art/icloud_drive_2x.png

A fundamental aspect of the iCloud storage user experience is transparency: Ideally, users don’t need to think about where their content is located or which version of the content they’re currently viewing. The following guidelines can help you provide this user experience in your app.

Respect the user’s iCloud account. It’s important to remember that iCloud storage is a finite resource that users pay for. You should use iCloud storage to store information that users create, and avoid using it to store app resources or content that you can regenerate.

Determine which types of information to store in iCloud storage. In addition to storing documents and other user content, you can also store small amounts of key-value data in iCloud storage. For example, if users choose to sync iCloud Contacts, Mail stores their VIPs and Previous Recipients lists. These preferences are available to them on all Mac computers with macOS v10.8 and later installed.

If you store preferences in iCloud key-value storage, be sure that the preferences are ones that users are likely to want to have applied to all their devices. For example, Mail doesn’t sync users’ Downloads folder because it probably contains large files and users can still access these files through Mail on their other computers as needed. Additionally, it may makes sense for your app to keep track of which files are open, but not the exact window positions of those files. Note that in some cases, it can make sense to store preferences on your app’s server, instead of in the user’s iCloud account, so that the preferences are available regardless of whether iCloud is available.

Make sure that your app behaves reasonably when iCloud storage is unavailable. For example, if users sign out of their iCloud account or aren’t connected to the Internet, iCloud storage becomes unavailable. For document-based apps, the Open dialog shows that a document is Waiting if there are unsaved changes that haven’t yet been stored in iCloud. Your app doesn’t need to inform users that iCloud storage is unavailable. For non-document-based apps, it can be appropriate to show users that the changes they make won’t be visible on other devices until they restore access to iCloud storage.

If appropriate, make it easy for users to enable iCloud storage for your app. On their Mac computers, users sign in to their iCloud account in iCloud Settings, and for the most part, they expect their apps to work with iCloud storage automatically. If you think users might want to choose whether to use iCloud storage with your app, you can provide an option that they set when your app opens. In most cases, a simple choice between using iCloud Storage or not for all user content should be sufficient.

Allow users to choose which documents to store in iCloud. When users have iCloud enabled, their documents are stored in iCloud by default. However, because iCloud storage is finite, users may choose to store content in iCloud on a file-by-file basis. To provide the appropriate user experience, users should be able to save a document on their Mac only, but iCloud should still be the default location.

Warn users about the consequences of deleting a document. When a user deletes a document in an app that uses iCloud storage, the document is removed from the user’s iCloud account and all other devices. It’s appropriate to display an alert that describes this result and to get confirmation before you perform the deletion.

Tell users about conflicts as soon as possible, but only when necessary. For document-based apps, macOS handles conflict resolution for you; you don’t need to do additional work to warn users about conflicts. For other apps, first determine if you can use iCloud storage APIs to resolve the conflict without involving the user. When this isn’t possible, make sure that you detect conflicts as soon as possible so that you can help users avoid wasting time on the wrong version of their content. You need to design an unobtrusive way to show users that a conflict exists; then, make it easy for users to distinguish between versions and make a decision.

Be sure to include the user’s iCloud content in searches. Users with iCloud accounts tend to think of their content as being universally available, and they expect search results to reflect this perception. If your app helps people to search their content, make sure you use the appropriate APIs to extend search to their iCloud accounts. See Searching iCloud and the Desktop to learn more.