iOS Storage Best Practices

As an app developer, it's critical that you know exactly what your app is storing on disk, where everything is being stored, and why it's needed. The best way to stay on top of these details is to take inventory of what your app actually stores.

To get started, build and run your app on a device, then exercise all the features that will store things on disk. Once you've done this, it's time to look at what actually got stored, and where. Use the Devices and Simulators window in Xcode to extract your app's container so that we can see what's in it. Select your device in the column on the left, then select your app in the Installed Apps list.

And using the gear icon, choose Download Container, and save it on your Mac.

In the Finder, Control-click on the xcappdata file that was downloaded. Choose Show Package Contents, and go into the App Data folder and start taking inventory. Look through the directories to see what got stored in each one.

For each file, make sure you can identify what it is, and why it's being stored. If you're not sure why something is there, you may be able to get rid of it. You want to verify that you're putting the right files in the appropriate directories, and also consider whether the file should be included in iTunes and iCloud backups. Only you can answer the first two questions, since they relate to your app's functionality. I'll focus on the last two questions and start with where files should be stored. iCloud Drive is the best place to put documents because they become available on all of the user's devices. Because the contents of your app's folder on iCloud Drive is visible, it's important that you only put documents in there that people will recognize and access directly. Your app reads and writes the content locally, and then the operating system will automatically upload those files when the network is available. Since multiple devices may be accessing the files in iCloud Drive at the same time, you do need to use file coordination to avoid any conflicts. So be sure to read the documentation for more details. For locally stored files, the Documents directory is available in your app's container. Like with iCloud Drive, you should only store user-visible documents here. Once you have verified that your Documents directory only contains files that should be exposed, the Files app can show them in the On My iPhone or On My iPad location. To do this, your app should support Open in Place and indicate that file sharing is enabled, both of which are configured in your Info.plist file. In addition to seeing their files in the Files app, people can find their files in Spotlight, and on iPad, drag and drop them to other apps.

Another great benefit of exposing your Documents directory is that people will see their files in the Storage Settings UI and can individually remove items. This makes it much easier to manage disk space, and will reduce the likelihood that your entire app is deleted when space is low. But remember, the only things that should be going into the Documents directory are files that will make sense to people using your app. The critical question you should ask is, "Should my users be able to see this file?" If the answer is yes, then that's fine. But if the answer is no, move it out of the Documents directory and into one of the following locations. The Application Support directory is a good place to store files that might be in your Documents directory but that shouldn't be seen by users. For example, a database that your app needs but that the user would never open manually.

You can store files at the top level, or you can create directories if that helps keep things organized. The directory is completely under your control, and it's persistent. The contents are included in backups by default, but you can opt files out if they don't need to be backed up. And finally, the disk space used in the Application Support directory is reported in the Storage Settings UI under your app's Documents & Data total. The next location available to your app is the Caches directory. You can store files here that can be discarded if space is low. This is a good location for any content that can be re-downloaded when needed. The contents of the Caches directory is not included in backups. When a device is low on disk space, iOS can help by clearing caches. Files will never be removed from your caches directory if your app is running, and the operating system will start by clearing caches for apps that haven't been used in a while. As a bonus to you, files in your caches directory are not reported as part of your app's Documents & Data total. Although they are included in the overall space taken up by apps.

And finally, you can put files that you won't need for any extended period of time in the Temporary directory. Even though the operating system will periodically remove these files when your app is not running, it's best to remove them when you're done with them.

Like the Caches directory, the Temporary directory is not backed up and is not reported in your app's Documents & Data total.

These are all the common locations that your app can store files in. Use iCloud Drive and the Documents directory for files that should be accessible in the Files app, while application support, caches, and temporary directories are all for use by your app privately. Be sure to review where you're storing things and use the right directory. Lastly, a couple best practice tips. If you have files that don't need to be included in iTunes or iCloud backups, use the NSFileManager APIs to set the "IsExcludedFromBackupKey". You also want to be resilient to files that might be restored from an older version of your app. For example, if you had a 32-bit version of your app and its files were backed up, then for a 64-bit version of your app, those older files might get restored and you need to be able to handle that situation. It's best to use a versioning scheme on your files so that you can provide robust compatibility across multiple versions of your app. And be sure that you're only storing files in one location. For example, if you put files into your local Documents directory, don't duplicate those in iCloud Drive. Choose one place and stick to it. For user documents, I suggest preferring a cloud storage location unless you have a specific reason to store files only local to a device.

And finally, some new volume capacity details are available in iOS 11 to help in knowing if it's a good time for your app to take up more disk space.

The first key, Available Capacity For Important Usage, indicates the amount of space that can be made available for things that the user has explicitly requested in your app's UI. For example, if they have chosen to download a video or a new level in a game. If the space you need is greater than what's available, you should let them know that their request cannot be fulfilled. The second key, Available Capacity For Opportunistic Usage, indicates the amount of space available for things that the user is likely to want, but hasn't explicitly requested. This could be something like the next episode in a series of videos that they are watching, or recently updated documents on a server that they might be likely to open. For these types of files, you might store them initially in the Caches directory until they are actually used, at which point you could move them to the Application Support or Documents directory.

After taking inventory and identifying what your app stored, if you found something that wasn't in the right place, then update your code to put it in the appropriate directory. And don't forget to add any necessary migration code to move the files from one place to another. If you don't do this, you might inadvertently leave abandoned files behind. By cleaning up your on-disk storage, you can open up your Documents directory to people in the Files app and they can be even more productive with your app. You can find more information at developer.apple.com or on our Developer Forums. Thanks for watching!