Learn tips for keeping your app's on-disk storage as organized and optimized as possible. See how to enable direct access to documents in your app using the new Files app in iOS 11. Gain insights into how to take inventory of your app's files and make the most of the storage capacity available to your app.
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.
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
or on our Developer Forums.
Thanks for watching!
Looking for something specific? Enter a topic above and jump straight to the good stuff.
An error occurred when submitting your query. Please check your Internet connection and try again.