Directorio de documentos en una aplicación móvil — qué es, propósito y cómo organizar el almacenamiento

¿Qué es el directorio de documentos de la aplicación?

El directorio de documentos es un almacenamiento especializado dentro del sandbox de la aplicación, diseñado para el almacenamiento permanente de archivos de usuario. A diferencia de la caché, los archivos en este directorio se consideran importantes para el usuario: el sistema no los elimina cuando falta espacio, se conservan durante las actualizaciones de la aplicación y se respaldan durante la sincronización del dispositivo. En iOS, el directorio Documents forma parte del contenedor Sandbox y se incluye automáticamente en la copia de seguridad de iCloud. En Android, no existe un equivalente directo — el equivalente es context.filesDir, que también está destinado a archivos permanentes pero no tiene un mecanismo de copia de seguridad integrado.

La diferencia entre el directorio de documentos y el almacenamiento interno en Android es mínima: ambos están ubicados en el sandbox de la aplicación, ambos se eliminan al desinstalar, ambos son inaccesibles para otras aplicaciones. La diferencia principal es semántica: el directorio Documents asume que los archivos son creados o importados por el usuario, mientras que el almacenamiento interno puede contener archivos internos de la aplicación (bases de datos, configuraciones). En iOS, la diferencia es más sustancial: Documents se respalda automáticamente, mientras que Library/Application Support no. Esto afecta la estrategia de almacenamiento: coloca solo lo que el usuario querría restaurar en un nuevo dispositivo en Documents, y los datos internos que la aplicación puede recrear en Application Support.

La arquitectura de sandbox garantiza que otras aplicaciones no puedan acceder al directorio de documentos de tu aplicación. En iOS, acceder a los Documents de otras aplicaciones es imposible sin jailbreak. En Android, el acceso root permite leer el filesDir de cualquier aplicación, por lo que los datos confidenciales (tokens, claves de cifrado) deben protegerse adicionalmente con EncryptedSharedPreferences o EncryptedFile de la librería AndroidX Security.

¿Qué datos se almacenan en el directorio de documentos?

El directorio de documentos debe almacenar datos que son valiosos para el usuario y deben ser accesibles después de reiniciar la aplicación o restaurar el dispositivo. No todos los archivos son adecuados para almacenar en este directorio — la elección depende del tipo de datos y el escenario de uso.

Documentos y archivos del usuario

Los archivos del usuario son el contenido principal del directorio de documentos. Pueden ser documentos de texto creados en un editor, imágenes tomadas con la cámara de la aplicación, informes PDF exportados, grabaciones de audio, notas. Cada uno de estos archivos es creado por el usuario o a petición suya y debe ser accesible en cualquier momento. En iOS, los archivos de Documents se muestran en la aplicación Files del sistema, lo que permite al usuario gestionarlos a través del gestor de archivos estándar. En Android, no existe una visualización similar — la aplicación debe proporcionar ella misma una interfaz para ver los archivos guardados.

Bases de datos y configuraciones de la aplicación

Las bases de datos SQLite y los archivos de configuración generalmente se almacenan cerca del directorio de documentos, pero no dentro de él. En iOS, las bases de datos se colocan en Library/Application Support, ya que no deben aparecer en la aplicación Files ni respaldarse por separado. En Android, las bases de datos se crean por defecto en /data/data/<package>/databases/ a través de Room o SQLiteOpenHelper. Si la base de datos contiene contenido del usuario (notas, diario, registros financieros), se puede colocar en filesDir para garantizar la copia de seguridad del sistema. Room permite especificar un directorio de almacenamiento personalizado para la base de datos a través del callback RoomDatabase.Builder.

val dbFile = File(context.filesDir, "user_database.db")

val db = Room.databaseBuilder<AppDatabase>(
    context,
    dbFile.absolutePath
).build()

Datos exportados e importados

Los archivos que el usuario importa de otras aplicaciones o exporta desde tu aplicación también deben guardarse en el directorio de documentos. En iOS, la importación a través de UIDocumentPickerViewController coloca automáticamente una copia del archivo en Documents cuando se usa el parámetro asCopy: true. En Android, la importación a través del diálogo SAF también crea una copia del archivo en el sandbox de la aplicación. Al exportar datos (por ejemplo, crear un archivo CSV con contactos), guarda el archivo primero en Documents/filesDir y luego ofrece al usuario compartirlo a través de Share Sheet. Esto garantiza que, incluso si el usuario olvida guardar el archivo después de enviarlo, quede una copia en la aplicación para uso posterior.

Cómo trabajar con el directorio de documentos en Android

En Android, la función del directorio de documentos la realiza context.filesDir. Además, está disponible el directorio context.externalFilesDir en la tarjeta SD, pero no garantiza la integridad de los datos. Veamos las principales técnicas para trabajar con estos directorios.

Acceso y gestión de archivos a través de filesDir

filesDir es el directorio principal para archivos permanentes de la aplicación en Android. Está ubicado en el sandbox de la aplicación y se elimina por completo al desinstalar. Para obtener una instancia de File, usa context.filesDir, que devuelve la ruta a /data/data/<package>/files/. Para crear y leer archivos, usa operaciones estándar de Java/Kotlin File o los métodos de Context openFileInput() y openFileOutput(), que toman un nombre de archivo y devuelven FileInputStream/FileOutputStream. El método openFileOutput() crea automáticamente el archivo en filesDir si aún no existe y permite especificar el modo de acceso: MODE_PRIVATE (solo la aplicación actual), MODE_APPEND (añadir) o MODE_WORLD_READABLE (obsoleto, no usado desde API 24+).

val fileName = "report.pdf"
val content = "PDF content".toByteArray()

context.openFileOutput(fileName, Context.MODE_PRIVATE).use { stream ->
    stream.write(content)
}

val bytes = context.openFileInput(fileName).use { stream ->
    stream.readBytes()
}

Características de almacenamiento en Android 10+

En Android 10+, el modelo Scoped Storage no afecta a filesDir — el acceso completo al sandbox propio de la aplicación permanece. Todas las operaciones de lectura y escritura dentro de filesDir no requieren permisos adicionales. Sin embargo, si intentas acceder a los archivos de otra aplicación a través de filesDir, obtendrás una excepción. Para compartir archivos, usa FileProvider, que crea un URI de contenido temporal para transferir un archivo a otra aplicación. FileProvider se declara en AndroidManifest.xml mediante la etiqueta <provider> y se configura en un archivo XML de rutas. Este es el mecanismo estándar para transferir archivos entre aplicaciones, utilizado, por ejemplo, al enviar una imagen a través de Intent con ACTION_SEND.

Cómo trabajar con el directorio de documentos en iOS

En iOS, el Documents Directory es parte del contenedor Sandbox de la aplicación con un estatus especial. Los archivos de este directorio se incluyen automáticamente en la copia de seguridad de iCloud, se muestran en la aplicación Files y se conservan durante las actualizaciones de la aplicación a través de la App Store.

Directorio de documentos y copia de seguridad

La copia de seguridad automática de Documents es una ventaja clave de iOS. Cuando el usuario conecta el dispositivo a iTunes o activa iCloud Backup, todos los archivos de Documents/ se copian en la copia de seguridad. Al restaurar en un nuevo dispositivo, el usuario recupera todos sus archivos sin acciones adicionales. Sin embargo, esta ventaja se convierte en desventaja si la aplicación almacena grandes cantidades de datos en Documents: el tiempo de copia de seguridad aumenta y el almacenamiento de iCloud puede agotarse rápidamente. Por lo tanto, Documents solo debe almacenar archivos que el usuario realmente necesite durante la restauración. Los archivos temporales, la caché y los datos recreables deben estar en Caches o Library/Application Support. Apple recomienda excluir de la copia de seguridad los archivos que se pueden volver a descargar de internet, mediante el atributo isExcludedFromBackup.

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

let fileURL = docsURL.appendingPathComponent("notes.txt")
let text = "Contenido de la nota"
try text.write(to: fileURL, atomically: true, encoding: .utf8)

iCloud Drive y sincronización entre dispositivos

iCloud Drive permite sincronizar archivos de Documents entre los dispositivos de un mismo usuario. Para activar la sincronización, la aplicación debe usar las API NSDocument o UIDocument, que gestionan automáticamente el control de versiones y la resolución de conflictos. Un enfoque alternativo es usar iCloud con CloudKit, que proporciona un control más flexible sobre la sincronización, pero requiere configuración en CloudKit Dashboard. Al usar iCloud Drive, asegúrate de manejar correctamente los conflictos de edición (fusionar o último escritor gana) e informar al usuario sobre el estado de sincronización a través de la interfaz de la aplicación. iCloud no garantiza la sincronización instantánea — el retraso puede oscilar entre unos segundos y varios minutos, dependiendo del tamaño del archivo y la calidad de la conexión. Para datos críticos, utiliza escritura transaccional y control de versiones para que, en caso de conflicto, se pueda restaurar la versión anterior del archivo.

Diferencias con el directorio de caché y mejores prácticas

Elegir correctamente entre Documents Directory y Cache Directory determina la fiabilidad del almacenamiento de datos del usuario. Un error en la elección lleva a la pérdida de datos (si los archivos importantes se almacenan en caché) o al desbordamiento de la copia de seguridad (si los archivos temporales se almacenan en Documents).

Las mejores prácticas para usar el directorio de documentos incluyen varias reglas clave. Primero, siempre solicita la confirmación del usuario antes de eliminar archivos de este directorio. A diferencia de la caché, eliminar un documento puede provocar la pérdida irreversible de contenido del usuario. Segundo, implementa el control de versiones de archivos: al sobrescribir un archivo existente, guarda la versión anterior con el sufijo _backup o usa mecanismos de Snapshot. Tercero, proporciona al usuario una interfaz para ver, renombrar, eliminar y exportar archivos del directorio de documentos. En iOS, los archivos de Documents se muestran automáticamente en Files; en Android, debes implementar tu propio gestor de archivos o usar librerías de terceros.

Presta especial atención a la migración de datos durante las actualizaciones de la aplicación. Si la nueva versión cambia la estructura de almacenamiento de archivos (por ejemplo, mueve datos de una subcarpeta a otra o cambia el formato de archivo), implementa una migración única en el primer inicio después de la actualización. Almacena el número de versión del esquema de datos en SharedPreferences y ejecuta la migración si no coinciden. No elimines los archivos antiguos antes de que finalice la migración — en caso de fallo, el usuario no debe perder datos. Si la migración implica una conversión de formato (por ejemplo, pasar de JSON a SQLite), guarda los archivos originales como copia de seguridad en un directorio separado con la fecha de migración. El usuario debe poder revertir los cambios a través de la configuración de la aplicación dentro de los primeros 30 días después de la actualización, según recomienda Apple Human Interface Guidelines.