Documents Directory: qué es, propósito y acceso a archivos

¿Qué es Documents Directory en iOS?

Documents Directory es un directorio dentro del sandbox de una aplicación iOS diseñado para almacenar datos del usuario que deben persistir entre sesiones y ser accesibles al usuario. Cada aplicación tiene su propio sandbox aislado, y Documents es uno de los directorios clave junto con Caches, tmp y Library.

iOS utiliza un sandbox estricto: una aplicación no tiene acceso al sistema de archivos de otras aplicaciones ni a directorios del sistema sin permisos especiales. Documents Directory es el único directorio cuyo contenido el usuario puede ver a través de iTunes File Sharing (cuando la clave UIFileSharingEnabled está activada en Info.plist).

Según Apple WWDC 2023, más del 85% de las aplicaciones en App Store usan Documents Directory para almacenar al menos un tipo de dato de usuario — desde PDF exportados hasta archivos de juego guardados e imágenes exportadas.

Es importante que el desarrollador entienda: los archivos en Documents se incluyen automáticamente en las copias de seguridad de iCloud e iTunes. Si una aplicación almacena grandes volúmenes de datos recuperables en Documents (por ejemplo, caché de imágenes o archivos temporales), esto conlleva un consumo innecesario del espacio de iCloud del usuario.

Cómo obtener la ruta a Documents Directory

En Swift, la ruta a Documents Directory se obtiene a través de FileManager. Apple recomienda usar la API basada en URL en lugar de la basada en cadenas para una mejor compatibilidad con las capacidades modernas de iOS.

import Foundation

let fileManager = FileManager.default
guard let documentsURL = fileManager.urls(
    for: .documentDirectory,
    in: .userDomainMask
).first else { return }

// Crear archivo en Documents
let fileURL = documentsURL.appendingPathComponent("report.pdf")
let data = Data("Hello, world!".utf8)
try data.write(to: fileURL)

Objective-C usa NSSearchPathForDirectoriesInDomains — un enfoque más antiguo pero aún compatible que devuelve una ruta de cadena en lugar de una URL.

@import Foundation;

NSArray *paths = NSSearchPathForDirectoriesInDomains(
    NSDocumentDirectory,
    NSUserDomainMask,
    YES
);
NSString *documentsPath = paths.firstObject;
NSString *filePath = [documentsPath stringByAppendingPathComponent:@"report.pdf"];

Los proyectos modernos en Swift deben usar FileManager.urls, ya que este método devuelve una URL en lugar de una cadena, lo que reduce el riesgo de errores de codificación de rutas y hace que el código sea más seguro en cuanto a tipos.

Qué datos almacenar en Documents

Documents Directory está destinado a datos creados por el usuario o explícitamente necesarios para el usuario. Apple destaca varias categorías que son apropiadas para este directorio.

Documentos y archivos del usuario

Archivos que el usuario crea o importa — documentos de texto, PDF, imágenes, informes exportados, archivos de copia de seguridad. Estos datos tienen valor directo para el usuario y su pérdida sería crítica.

Partidas guardadas y estado de la aplicación

Partidas guardadas de juegos, archivos de estado de la aplicación, proyectos exportados — todo lo que el usuario espera restaurar después de reinstalar la aplicación. Sin embargo, para datos críticos se recomienda adicionalmente usar iCloud Key-Value Storage o Core Data con sincronización de iCloud.

El criterio clave: si los datos se pueden descargar de nuevo desde la red o se pueden recrear — su lugar está en Caches, no en Documents. Cada gigabyte en Documents es un gigabyte en la copia de seguridad de iCloud del usuario.

Copia de seguridad y sincronización

iOS incluye automáticamente el contenido de Documents Directory en las copias de seguridad cuando el dispositivo se conecta a iTunes o al sincronizar con iCloud. Este comportamiento no se puede desactivar a nivel de directorio — solo por archivo mediante el atributo NSURLIsExcludedFromBackupKey.

A partir de iOS 5.0, Apple comenzó a rechazar aplicaciones que almacenan grandes volúmenes de datos recuperables en Documents. La recomendación de Apple: los archivos que se pueden descargar de nuevo deben almacenarse en Caches Directory con la bandera de exclusión de copia de seguridad.

import Foundation

let documentsURL = FileManager.default
    .urls(for: .documentDirectory, in: .userDomainMask)
    .first!

// Excluir archivo de la copia de seguridad de iCloud
var resourceValues = URLResourceValues()
resourceValues.isExcludedFromBackup = true

var fileURL = documentsURL.appendingPathComponent("cached_data.json")
try fileURL.setResourceValues(resourceValues)

La sincronización de iCloud funciona a través de NSUbiquitousContainer si la aplicación usa iCloud Documents. En este caso, los archivos de Documents Directory se sincronizan automáticamente entre los dispositivos del usuario. Para aplicaciones sin iCloud, la sincronización se limita a la copia de seguridad.

Documents Directory vs Caches Directory

La diferencia entre Documents y Caches es uno de los conceptos erróneos más comunes entre los desarrolladores principiantes de iOS. La diferencia principal: el sistema puede eliminar archivos de Caches en cualquier momento para liberar espacio, pero nunca toca Documents sin el conocimiento del usuario.

Según Apple Developer Documentation (2024), el uso incorrecto de Documents Directory es una de las razones comunes de rechazo de aplicaciones durante la revisión: si una aplicación almacena más de unos pocos megabytes de datos recuperables en Documents, Apple recomienda moverlos a Caches o aplicar NSURLIsExcludedFromBackupKey.

Una regla práctica: si el usuario se molestaría por perder el archivo — guárdalo en Documents. Si el archivo se puede descargar de nuevo o regenerar — guárdalo en Caches.

Mejores prácticas para trabajar con Documents

Los desarrolladores experimentados de iOS han desarrollado varias reglas que ayudan a evitar problemas con Documents Directory en todas las etapas del ciclo de vida de la aplicación — desde el desarrollo hasta la publicación en App Store.

Monitoreo del tamaño del directorio

Regularmente verifica el tamaño de Documents Directory a través de FileManager.enumerator(at:includingPropertiesForKeys:). Si el tamaño supera los 100 MB para datos no pertenecientes al usuario — es motivo para reconsiderar la arquitectura de almacenamiento.

Exclusión de archivos recuperables de la copia de seguridad

Para cualquier archivo que se pueda descargar de nuevo, establece isExcludedFromBackup = true. Esto reduce la carga en el almacenamiento de iCloud del usuario y disminuye el riesgo de rechazo en App Review.

Migración durante actualizaciones

Al cambiar el formato de datos en Documents, planifica la migración: no elimines archivos antiguos hasta que estés seguro de que los nuevos se han creado correctamente. Usa subdirectorios específicos de versión.

import Foundation

let documentsURL = FileManager.default
    .urls(for: .documentDirectory, in: .userDomainMask)
    .first!

let versionDir = documentsURL.appendingPathComponent("v2")
try FileManager.default.createDirectory(
    at: versionDir,
    withIntermediateDirectories: true
)

Seguir estas prácticas reduce el riesgo de pérdida de datos del usuario, disminuye el tamaño de la copia de seguridad de iCloud y simplifica la revisión en App Store.