File Provider Extension: cos'è e come funziona il file provider iOS

Cos'è File Provider Extension in iOS

File Provider Extension è un'estensione dell'app che aggiunge nuove fonti di documenti all'app File. Un servizio cloud — Google Drive, Dropbox, OneDrive o un archivio aziendale — può visualizzare la propria struttura file direttamente nell'interfaccia di sistema, senza aprire un'app separata.

Gli utenti lavorano con file remoti esattamente come con i file salvati sul dispositivo: sfogliano il contenuto delle cartelle, trascinano e rilasciano documenti, li aprono in qualsiasi app compatibile e salvano le modifiche nel cloud. Secondo il WWDC 2025, File Provider Extension supporta fino a 1000 operazioni di sincronizzazione simultanee e si adatta alla velocità della rete attraverso la gestione dinamica delle priorità.

L'estensione funziona in background — iOS la avvia quando è necessaria la sincronizzazione e può terminarla forzatamente quando le risorse sono scarse. Tutte le operazioni devono essere idempotenti e supportare la ripresa da un punto di controllo.

Architettura e meccanismo di sincronizzazione file

File Provider Extension ha un'architettura a tre livelli: il processo di sistema Files.app, l'estensione fornitrice e il server remoto. Il sistema richiede dati all'estensione, l'estensione traduce le richieste in chiamate API del servizio cloud e restituisce i risultati tramite NSFileProviderItem.

Sincronizzazione incrementale

Invece di caricare l'intera struttura file a ogni aggiornamento, l'estensione trasferisce solo gli elementi modificati. NSFileProviderManager fornisce metodi per inviare aggiornamenti incrementali — “file A aggiunto”, “file B modificato”, “cartella C eliminata”. Questo riduce drasticamente il traffico e accelera la visualizzazione delle modifiche.

Secondo Apple Engineering, la sincronizzazione incrementale riduce il volume di dati trasferiti del 60–80% rispetto a un ricaricamento completo. Si consiglia di utilizzare NSFileProviderSyncAnchor per contrassegnare lo stato di sincronizzazione e minimizzare le richieste duplicate.

Cache sul dispositivo

File Provider Extension può memorizzare nella cache i file localmente per l'accesso offline. Quando un file viene aperto, il sistema effettua una richiesta all'estensione e l'estensione decide se scaricare il contenuto dal server o restituire una versione già in cache. NSFileProviderItem indica il livello di caching tramite i campi isDownloaded e isUploaded.

Apple consiglia di configurare le politiche di cache in base alla dimensione del file: per immagini e documenti — caching completo, per video — solo anteprime, per archivi — su richiesta dell'utente.

NSFileProviderManager: gestione del file provider

NSFileProviderManager è la classe centrale attraverso cui l'estensione interagisce con il sistema. Fornisce metodi per notificare al sistema le modifiche, creare nuovi elementi, gestire i download e gestire gli errori. Ogni istanza di NSFileProviderManager è legata a un dominio specifico.

Metodi chiave

signalEnumerator(for:) — notifica al sistema che il contenuto di una cartella è cambiato e deve essere riletto. reimportItem(_:) — reimporta l'elemento specificato dopo una modifica lato server. registerURLSessionTask:forItemWithIdentifier: — associa un download in background a un file specifico per il monitoraggio dell'avanzamento.

Limitazione importante: NSFileProviderManager funziona solo all'interno del processo dell'estensione. L'app principale non può chiamare direttamente i suoi metodi per gestire la struttura file — la sincronizzazione deve essere avviata dall'estensione o dal sistema.

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

Gestione download

Per i download di file in background, NSFileProviderManager utilizza URLSession con configurazione in background. L'estensione crea un'attività di download e la registra nel manager, che la associa all'elemento corrispondente. Il sistema tiene traccia automaticamente dell'avanzamento e delle priorità dei download in base all'attività dell'utente.

Implementazione di File Provider Extension

La creazione di una File Provider Extension inizia aggiungendo un nuovo target in Xcode con il modello File Provider Extension. Xcode genera automaticamente una classe che eredita da NSFileProviderExtension e un insieme minimo di metodi per lavorare con gli elementi.

NSFileProviderItem e metadati

Ogni elemento nella struttura file — un file o una cartella — implementa il protocollo NSFileProviderItem. Il protocollo definisce i campi obbligatori: itemIdentifier, parentItemIdentifier, filename, typeIdentifier e capabilities. Inoltre, è possibile specificare dimensione, data di modifica e flag di download.

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

Gestione delle richieste di enumerazione

Il metodo enumerator(for:) restituisce un oggetto che implementa NSFileProviderEnumerator, che fornisce il contenuto della cartella su richiesta del sistema. iOS può richiedere l'enumerazione per la cartella radice, le sottocartelle e un set di lavoro — quest'ultimo viene utilizzato per visualizzare i file recenti o preferiti.

Apple consiglia di utilizzare metodi di enumerazione asincroni con paginazione tramite NSFileProviderPage per non caricare migliaia di elementi contemporaneamente. Pagine di 50–100 elementi sono ottimali per le prestazioni.

Domini e architettura multi-account

NSFileProviderDomain è il meccanismo per separare diversi account all'interno di una singola estensione. Se un utente ha autorizzato più account in un'app — Google Drive personale e aziendale — ogni account crea un dominio separato, che appare come fonte separata nell'app File.

Ogni dominio ha un identificatore univoco, un nome visualizzato e uno stato. Gli utenti possono disabilitare temporaneamente i domini o eliminarli senza influenzare altri account. Il sistema avvia un processo di estensione separato per ogni dominio attivo, garantendo l'isolamento dei dati tra account.

Secondo Apple, si consiglia di non creare più di 10 domini per estensione — un numero eccessivo rallenta l'avvio dell'app File e aumenta il consumo di memoria. Per i servizi con un gran numero di account, è consigliabile aggregarli in un unico dominio con cambio di profilo all'interno dell'estensione.

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