File Provider Extension: o que é e como funciona o provedor de arquivos do iOS

O que é File Provider Extension no iOS

File Provider Extension é uma extensão de aplicativo que adiciona novas fontes de documentos ao aplicativo Files. Um serviço em nuvem — Google Drive, Dropbox, OneDrive ou um armazenamento corporativo — pode exibir sua estrutura de arquivos diretamente na interface do sistema, sem abrir um aplicativo separado.

Os usuários trabalham com arquivos remotos da mesma forma que com arquivos salvos no dispositivo: navegam pelo conteúdo das pastas, arrastam e soltam documentos, abrem-nos em qualquer aplicativo compatível e salvam as alterações de volta na nuvem. De acordo com a WWDC 2025, o File Provider Extension suporta até 1000 operações de sincronização simultâneas e se adapta à velocidade da rede através do gerenciamento dinâmico de prioridades.

A extensão funciona em segundo plano — o iOS a inicia quando a sincronização é necessária e pode forçar seu encerramento quando os recursos estão baixos. Todas as operações devem ser idempotentes e suportar retomada a partir de um ponto de verificação.

Arquitetura e mecanismo de sincronização de arquivos

File Provider Extension possui uma arquitetura de três camadas: o processo do sistema Files.app, a extensão provedora e o servidor remoto. O sistema solicita dados à extensão, a extensão traduz as solicitações em chamadas de API do serviço em nuvem e retorna os resultados através do NSFileProviderItem.

Sincronização incremental

Em vez de carregar a estrutura completa de arquivos a cada atualização, a extensão transfere apenas os itens modificados. O NSFileProviderManager fornece métodos para enviar atualizações incrementais — “arquivo A adicionado”, “arquivo B modificado”, “pasta C excluída”. Isso reduz drasticamente o tráfego e acelera a exibição das alterações.

De acordo com a Apple Engineering, a sincronização incremental reduz o volume de dados transferidos em 60–80% em comparação com uma recarga completa. Recomenda-se usar NSFileProviderSyncAnchor para marcar o estado da sincronização e minimizar solicitações duplicadas.

Cache no dispositivo

File Provider Extension pode armazenar arquivos em cache localmente para acesso offline. Quando um arquivo é aberto, o sistema faz uma solicitação à extensão, e a extensão decide se deve baixar o conteúdo do servidor ou retornar uma versão já em cache. O NSFileProviderItem indica o nível de cache através dos campos isDownloaded e isUploaded.

A Apple recomenda configurar políticas de cache com base no tamanho do arquivo: para imagens e documentos — cache completo, para vídeos — apenas visualizações, para arquivos — mediante solicitação do usuário.

NSFileProviderManager: gerenciando o provedor de arquivos

NSFileProviderManager é a classe central através da qual a extensão interage com o sistema. Ela fornece métodos para notificar o sistema sobre alterações, criar novos itens, gerenciar downloads e lidar com erros. Cada instância do NSFileProviderManager está vinculada a um domínio específico.

Métodos principais

signalEnumerator(for:) — notifica o sistema que o conteúdo de uma pasta mudou e precisa ser relido. reimportItem(_:) — reimporta o item especificado após uma alteração no servidor. registerURLSessionTask:forItemWithIdentifier: — associa um download em segundo plano a um arquivo específico para acompanhamento do progresso.

Limitação importante: o NSFileProviderManager funciona apenas dentro do processo da extensão. O aplicativo principal não pode chamar diretamente seus métodos para gerenciar a estrutura de arquivos — a sincronização deve ser iniciada pela extensão ou pelo sistema.

let manager = NSFileProviderManager.default()
manager.signalEnumerator(for: workingSet) { error in
    if let error = error {
        print("Signal failed: \(error)")
    }
}

Gerenciamento de downloads

Para downloads de arquivos em segundo plano, o NSFileProviderManager usa URLSession com configuração em segundo plano. A extensão cria uma tarefa de download e a registra no gerenciador, que a associa ao item correspondente. O sistema rastreia automaticamente o progresso e as prioridades dos downloads com base na atividade do usuário.

Implementando File Provider Extension

Criar uma File Provider Extension começa adicionando um novo target no Xcode com o template File Provider Extension. O Xcode gera automaticamente uma classe que herda de NSFileProviderExtension e um conjunto mínimo de métodos para trabalhar com itens.

NSFileProviderItem e metadados

Cada item na estrutura de arquivos — um arquivo ou pasta — implementa o protocolo NSFileProviderItem. O protocolo define campos obrigatórios: itemIdentifier, parentItemIdentifier, filename, typeIdentifier e capabilities. Adicionalmente, você pode especificar tamanho, data de modificação e flags de download.

struct CloudItem: NSFileProviderItem {
    let itemIdentifier: NSFileProviderItemIdentifier
    let parentItemIdentifier: NSFileProviderItemIdentifier
    let filename: String
    let typeIdentifier: String
    let capabilities: NSFileProviderItemCapabilities
    let documentSize: NSNumber?
}

Manipulação de solicitações de enumeração

O método enumerator(for:) retorna um objeto que implementa NSFileProviderEnumerator, que fornece o conteúdo da pasta mediante solicitação do sistema. O iOS pode solicitar enumeração para a pasta raiz, subpastas e um conjunto de trabalho — este último é usado para exibir arquivos recentes ou favoritos.

A Apple recomenda usar métodos de enumeração assíncronos com paginação através de NSFileProviderPage para não carregar milhares de itens de uma vez. Páginas de 50–100 itens são ideais para desempenho.

Domínios e arquitetura multiconta

NSFileProviderDomain é o mecanismo para separar diferentes contas dentro de uma mesma extensão. Se um usuário autorizou várias contas em um aplicativo — Google Drive pessoal e corporativo — cada conta cria um domínio separado, que aparece como uma fonte separada no aplicativo Files.

Cada domínio tem um identificador único, um nome de exibição e um estado. Os usuários podem desativar temporariamente os domínios ou excluí-los sem afetar outras contas. O sistema inicia um processo de extensão separado para cada domínio ativo, garantindo o isolamento de dados entre contas.

De acordo com a Apple, recomenda-se não criar mais de 10 domínios por extensão — um número excessivo retarda a inicialização do aplicativo Files e aumenta o consumo de memória. Para serviços com um grande número de contas, é recomendável agregá-las em um único domínio com alternância de perfis dentro da extensão.

let domain = NSFileProviderDomain(
    identifier: "work",
    displayName: "Corporate Drive"
)
NSFileProviderManager.add(domain) { error in
    if let error = error {
        print("Failed to add domain: \(error)")
    }
}