Documents Directory: o que é, finalidade e acesso a arquivos

O que é Documents Directory no iOS?

Documents Directory é um diretório dentro do sandbox de uma aplicação iOS projetado para armazenar dados do usuário que devem persistir entre as execuções e estar acessíveis ao usuário. Cada aplicação recebe seu próprio sandbox isolado, e Documents é um dos diretórios principais ao lado de Caches, tmp e Library.

O iOS usa um sandbox rigoroso: uma aplicação não tem acesso ao sistema de arquivos de outras aplicações ou a diretórios do sistema sem permissões especiais. Documents Directory é o único diretório cujo conteúdo o usuário pode visualizar através do iTunes File Sharing (quando a chave UIFileSharingEnabled está ativada no Info.plist).

De acordo com a Apple WWDC 2023, mais de 85% das aplicações na App Store usam Documents Directory para armazenar pelo menos um tipo de dado do usuário — desde PDFs exportados até arquivos de jogo salvos e imagens exportadas.

É importante que o desenvolvedor entenda: os arquivos em Documents são automaticamente incluídos nos backups do iCloud e iTunes. Se uma aplicação armazena grandes volumes de dados recuperáveis em Documents (por exemplo, cache de imagens ou arquivos temporários), isso leva a um consumo desnecessário do espaço de armazenamento iCloud do usuário.

Como obter o caminho para Documents Directory

Em Swift, o caminho para Documents Directory é obtido através do FileManager. A Apple recomenda usar a API baseada em URL em vez da baseada em strings para melhor compatibilidade com os recursos modernos do iOS.

import Foundation

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

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

O Objective-C usa NSSearchPathForDirectoriesInDomains — uma abordagem mais antiga mas ainda suportada que retorna um caminho de string em vez de uma URL.

@import Foundation;

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

Projetos modernos em Swift devem usar FileManager.urls, pois este método retorna uma URL em vez de uma string, o que reduz o risco de erros de codificação de caminhos e torna o código mais seguro em termos de tipos.

Quais dados armazenar em Documents

Documents Directory é destinado a dados criados pelo usuário ou explicitamente necessários ao usuário. A Apple destaca várias categorias apropriadas para este diretório.

Documentos e arquivos do usuário

Arquivos que o usuário cria ou importa — documentos de texto, PDFs, imagens, relatórios exportados, arquivos de backup. Estes dados têm valor direto para o usuário e sua perda seria crítica.

Salvamentos de jogos e estado da aplicação

Salvamentos de jogos, arquivos de estado da aplicação, projetos exportados — tudo que o usuário espera restaurar após reinstalar a aplicação. No entanto, para dados críticos, recomenda-se usar adicionalmente iCloud Key-Value Storage ou Core Data com sincronização iCloud.

O critério chave: se os dados podem ser baixados novamente da rede ou recriados — o lugar deles é em Caches, não em Documents. Cada gigabyte em Documents é um gigabyte no backup iCloud do usuário.

Backup e sincronização

iOS inclui automaticamente o conteúdo de Documents Directory nos backups quando o dispositivo é conectado ao iTunes ou ao sincronizar com iCloud. Este comportamento não pode ser desativado ao nível do diretório — apenas por arquivo através do atributo NSURLIsExcludedFromBackupKey.

A partir do iOS 5.0, a Apple começou a rejeitar aplicações que armazenam grandes volumes de dados recuperáveis em Documents. A recomendação da Apple: arquivos que podem ser baixados novamente devem ser armazenados em Caches Directory com a flag de exclusão de backup.

import Foundation

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

// Excluir ficheiro do backup iCloud
var resourceValues = URLResourceValues()
resourceValues.isExcludedFromBackup = true

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

A sincronização iCloud funciona através de NSUbiquitousContainer se a aplicação usar iCloud Documents. Neste caso, os arquivos de Documents Directory são automaticamente sincronizados entre os dispositivos do usuário. Para aplicações sem iCloud, a sincronização é limitada ao backup.

Documents Directory vs Caches Directory

A diferença entre Documents e Caches é um dos equívocos mais comuns entre desenvolvedores iOS iniciantes. A principal diferença: o sistema pode excluir arquivos de Caches a qualquer momento para liberar espaço, mas nunca toca em Documents sem o conhecimento do usuário.

De acordo com a Apple Developer Documentation (2024), o uso inadequado de Documents Directory é uma das razões comuns para rejeição de aplicações durante a revisão: se uma aplicação armazena mais de alguns megabytes de dados recuperáveis em Documents, a Apple recomenda movê-los para Caches ou aplicar NSURLIsExcludedFromBackupKey.

Uma regra prática: se o usuário ficaria chateado ao perder o arquivo — armazene-o em Documents. Se o arquivo pode ser baixado novamente ou regenerado — armazene-o em Caches.

Melhores práticas para trabalhar com Documents

Desenvolvedores iOS experientes desenvolveram várias regras que ajudam a evitar problemas com Documents Directory em todas as fases do ciclo de vida da aplicação — desde o desenvolvimento até a publicação na App Store.

Monitoramento do tamanho do diretório

Regularmente verifique o tamanho de Documents Directory através de FileManager.enumerator(at:includingPropertiesForKeys:). Se o tamanho exceder 100 MB para dados não pertencentes ao usuário — é motivo para reconsiderar a arquitetura de armazenamento.

Exclusão de arquivos recuperáveis do backup

Para quaisquer arquivos que possam ser baixados novamente, defina isExcludedFromBackup = true. Isso reduz a carga no armazenamento iCloud do usuário e diminui o risco de rejeição na App Review.

Migração durante atualizações

Ao alterar o formato de dados em Documents, planeie a migração: não exclua arquivos antigos até ter certeza de que os novos foram criados corretamente. Use subdiretórios específicos de versão.

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áticas reduz o risco de perda de dados do usuário, diminui o tamanho do backup iCloud e simplifica a revisão na App Store.