Esegui il backup dei dati utente con il backup automatico

Backup automatico per app esegue automaticamente il backup dei dati di un utente dalle app che hanno come target e vengono eseguite su Android 6.0 (livello API 23) o versioni successive. Android conserva i dati dell'app caricandoli sul Google Drive dell'utente, dove sono protetti dalle credenziali dell'Account Google dell'utente. Il backup è protetto con crittografia end-to-end sui dispositivi con Android 9 o versioni successive utilizzando il PIN, la sequenza o la password del dispositivo. La quantità di dati è limitata a 25 MB per utente. Non viene addebitato alcun costo per l'archiviazione dei dati di backup. L'app può personalizzare la procedura di backup o disattivarla disattivando i backup.

Per una panoramica delle opzioni di backup di Android e indicazioni sui dati di cui eseguire il backup e il ripristino, consulta la panoramica sul backup dei dati.

File sottoposti a backup

Per impostazione predefinita, Backup automatico include i file nella maggior parte delle directory assegnate alla tua app dal sistema:

• File delle preferenze condivisi

• File salvati nella memoria interna dell'app e accessibili da getFilesDir() o getDir(String, int)

• I file nella directory restituita da getDatabasePath(String), che include anche i file creati con la classe SQLiteOpenHelper

• I file nella memoria esterna nella directory restituita da getExternalFilesDir(String)

Backup automatico esclude i file nelle directory restituite da getCacheDir(), getCodeCacheDir() e getNoBackupFilesDir(). I file salvati in queste posizioni sono necessari solo temporaneamente e sono intenzionalmente esclusi dalle operazioni di backup.

Puoi configurare la tua app in modo da includere ed escludere determinati file. Per ulteriori informazioni, consulta la sezione Includere ed escludere file.

Nota: Android non considera la configurazione dei componenti come dati utente. Se l'app attiva o disattiva componenti specifici nel file manifest mentre è in esecuzione, Backup automatico non salva e ripristina automaticamente la configurazione. Per conservare lo stato della configurazione, archivia lo stato in Preferenze condivise e recupera le preferenze condivise al ripristino.

Posizione backup

I dati di backup sono archiviati in una cartella privata nell'account Google Drive dell'utente, con un limite di 25 MB per app. I dati salvati non sono inclusi nel calcolo della quota Google Drive personale dell'utente. Viene archiviato solo il backup più recente. Quando viene creato un backup, qualsiasi backup precedente viene eliminato. L'utente o altre app sul dispositivo non possono leggere i dati di backup.

Gli utenti possono visualizzare l'elenco delle app di cui è stato eseguito il backup nell'app Google Drive per Android. Sui dispositivi Android, gli utenti possono trovare questo elenco nel riquadro di navigazione a scomparsa dell'app Drive in Impostazioni > Backup e ripristino.

I backup di ogni durata della configurazione del dispositivo vengono archiviati in set di dati separati, come descritto nei seguenti esempi:

• Se l'utente possiede due dispositivi, esiste un set di dati di backup per ciascuno di essi.

• Se l'utente ripristina i dati di fabbrica di un dispositivo e poi lo configura con lo stesso account, il backup viene archiviato in un nuovo set di dati. I set di dati obsoleti vengono eliminati automaticamente dopo un periodo di inattività.

Attenzione: se la quantità di dati è superiore a 25 MB, il sistema chiama onQuotaExceeded() e non esegue il backup dei dati sul cloud. Il sistema controlla periodicamente se la quantità di dati in un secondo momento scende al di sotto della soglia di 25 MB e continua con il backup automatico quando lo rileva.

Programmazione backup

I backup vengono eseguiti automaticamente quando sono soddisfatte tutte le seguenti condizioni:

• L'utente ha attivato il backup sul dispositivo. In Android 9, questa impostazione si trova in Impostazioni > Sistema > Backup.
• Sono trascorse almeno 24 ore dall'ultimo backup.
• Il dispositivo è inattivo.
• Il dispositivo sia collegato a una rete Wi-Fi (se l'utente del dispositivo non ha attivato i backup con dati mobili).

In pratica, queste condizioni si verificano all'incirca ogni notte, ma un dispositivo potrebbe non eseguire mai il backup (ad esempio se non si connette mai a una rete). Per mantenere la larghezza di banda della rete, il caricamento viene eseguito solo se i dati dell'app sono stati modificati.

Durante il backup automatico, il sistema arresta l'app per assicurarsi che non scriva più al file system. Per impostazione predefinita, il sistema di backup ignora le app in esecuzione in primo piano per evitare un'esperienza utente scadente. Puoi eseguire l'override del comportamento predefinito impostando l'attributo android:backupInForeground su true.

Per semplificare i test, Android include strumenti che ti consentono di avviare manualmente un backup dell'app. Per ulteriori informazioni, consulta Testare il backup e il ripristino.

Ripristina pianificazione

I dati vengono ripristinati ogni volta che l'app viene installata, dal Play Store, durante la configurazione del dispositivo (quando il sistema installa le app installate in precedenza) o eseguendo l'installazione di adb. L'operazione di ripristino si verifica dopo l'installazione dell'APK, ma prima che l'utente sia disponibile per l'avvio dell'app.

Durante la configurazione guidata iniziale del dispositivo, all'utente viene mostrato un elenco dei set di dati di backup disponibili e viene chiesto da quale di questi ripristinare i dati. Qualsiasi set di dati di backup selezionato diventa il set di dati ancestrale del dispositivo. Il dispositivo può eseguire il ripristino dai propri backup o dal set di dati ancestrale. Se sono disponibili backup da entrambe le origini, il dispositivo dà la priorità al proprio backup. Se l'utente non ha seguito la configurazione guidata del dispositivo, il dispositivo può eseguire il ripristino solo dai propri backup.

Per semplificare i test, Android include strumenti che ti consentono di avviare manualmente un ripristino dell'app. Per ulteriori informazioni, consulta Testare il backup e il ripristino.

Abilita e disabilita il backup

Le app destinate ad Android 6.0 (livello API 23) o versioni successive partecipano automaticamente al backup automatico. Nel file manifest dell'app, imposta il valore booleano android:allowBackup per attivare o disattivare il backup. Il valore predefinito è true, ma ti consigliamo di impostare esplicitamente l'attributo nel file manifest, come mostrato di seguito:

<manifest ... >
    ...
    <application android:allowBackup="true" ... >
        ...
    </application>
</manifest>

Puoi disattivare i backup impostando android:allowBackup su false. Ti consigliamo di eseguire questa operazione se la tua app è in grado di ricreare il proprio stato con altri meccanismi o se gestisce informazioni sensibili.

Nota: per le app eseguite su Android 12 (livello API 31) o versioni successive e che hanno come target Android 12 (livello API 31) o versioni successive, se specifichi android:allowBackup="false" vengono disattivati i backup su Google Drive, ma non i trasferimenti da dispositivo a dispositivo per l'app. Per maggiori dettagli, consulta le informazioni sulle modifiche al backup e al ripristino.

Includi ed escludi file

Per impostazione predefinita, il sistema esegue il backup di quasi tutti i dati dell'app. Per ulteriori informazioni, consulta la sezione relativa ai file di cui viene eseguito il backup.

Questa sezione mostra come definire regole XML personalizzate per controllare gli elementi sottoposti a backup. Se la tua app ha come target Android 12 (livello API 31) o versioni successive, devi specificare un set aggiuntivo di regole di backup XML, come descritto in questa sezione, per supportare le modifiche al ripristino del backup introdotte per i dispositivi su cui sono installate queste versioni di Android.

Controllare il backup su Android 11 e versioni precedenti

Segui i passaggi in questa sezione per controllare di quali file viene eseguito il backup sui dispositivi con Android 11 (livello API 30) o versioni precedenti.

Importante: queste regole di backup XML vengono utilizzate anche per i dispositivi con Android 12 o versioni successive se la tua app ha come target Android 11 o versioni precedenti. Consulta la sezione seguente per un set aggiuntivo di regole di backup XML per supportare le modifiche al ripristino del backup introdotte per i dispositivi con Android 12 o versioni successive.

1. Nel file AndroidManifest.xml, aggiungi l'attributo android:fullBackupContent all'elemento <application>, come mostrato nell'esempio seguente. Questo attributo rimanda a un file XML che contiene le regole di backup.

   <application ...
    android:fullBackupContent="@xml/backup_rules">
   </application>
   

2. Crea un file XML denominato @xml/backup_rules nella directory res/xml/. In questo file, aggiungi le regole con gli elementi <include> e <exclude>. Il seguente esempio esegue il backup di tutte le preferenze condivise tranne device.xml:

   <?xml version="1.0" encoding="utf-8"?>
   <full-backup-content>
    <include domain="sharedpref" path="."/>
    <exclude domain="sharedpref" path="device.xml"/>
   </full-backup-content>
   

Definisci le condizioni del dispositivo necessarie per il backup

Se la tua app salva informazioni sensibili sul dispositivo, puoi specificare le condizioni in base alle quali i dati dell'app sono inclusi nel backup dell'utente. Puoi aggiungere le seguenti condizioni in Android 9 (livello API 28) o versioni successive:

• clientSideEncryption: il backup dell'utente è criptato con un secret lato client. Questa forma di crittografia viene attivata sui dispositivi con Android 9 o versioni successive, a condizione che l'utente abbia attivato il backup in Android 9 o versioni successive e abbia impostato un blocco schermo (PIN, sequenza o password) per il dispositivo.
• deviceToDeviceTransfer: l'utente sta trasferendo il backup su un altro dispositivo che supporta il trasferimento locale tra dispositivi (ad esempio, Google Pixel).

Se hai eseguito l'upgrade dei dispositivi di sviluppo ad Android 9, devi disattivare e riattivare il backup dei dati dopo l'upgrade. Questo perché Android cripta i backup con un secret lato client solo dopo aver informato gli utenti in Impostazioni o nella configurazione guidata.

Per dichiarare le condizioni di inclusione, imposta l'attributo requireFlags sul valore o sui valori desiderati negli elementi <include> all'interno del tuo set di regole di backup:

backup_rules.xml

<?xml version="1.0" encoding="utf-8"?>
<full-backup-content>
    <!-- App data isn't included in user's backup
         unless client-side encryption is enabled. -->
    <include domain="file" path="."
             requireFlags="clientSideEncryption" />
</full-backup-content>

Nota: poiché l'aggiunta di requisiti al file XML impedisce il funzionamento dei backup sulle versioni di Android precedenti, fornisci risorse alternative per i backup utilizzati sui dispositivi con Android 8.1 (livello API 27) o versioni precedenti.

Se la tua app implementa un sistema di backup delle coppie chiave-valore o se implementi BackupAgent autonomamente, puoi anche applicare questi requisiti condizionali alla logica di backup eseguendo un confronto a livello di bit tra l'insieme di flag di trasporto di un oggetto BackupDataOutput e i flag FLAG_CLIENT_SIDE_ENCRYPTION_ENABLED o FLAG_DEVICE_TO_DEVICE_TRANSFER dell'agente di backup personalizzato.

Lo snippet di codice riportato di seguito mostra un esempio di utilizzo di questo metodo:

Kotlin

class CustomBackupAgent : BackupAgent() {
    override fun onBackup(oldState: ParcelFileDescriptor?,
            data: BackupDataOutput?, newState: ParcelFileDescriptor?) {
        if (data != null) {
            if ((data.transportFlags and
                    FLAG_CLIENT_SIDE_ENCRYPTION_ENABLED) != 0) {
                // Client-side backup encryption is enabled.
            }

            if ((data.transportFlags and FLAG_DEVICE_TO_DEVICE_TRANSFER) != 0) {
                // Local device-to-device transfer is enabled.
            }
        }
    }

    // Implementation of onRestore() here.
}

Java

public class CustomBackupAgent extends BackupAgent {
    @Override
    public void onBackup(ParcelFileDescriptor oldState, BackupDataOutput data,
            ParcelFileDescriptor newState) throws IOException {
        if ((data.getTransportFlags() &
                FLAG_CLIENT_SIDE_ENCRYPTION_ENABLED) != 0) {
            // Client-side backup encryption is enabled.
        }

        if ((data.getTransportFlags() &
                FLAG_DEVICE_TO_DEVICE_TRANSFER) != 0) {
            // Local device-to-device transfer is enabled.
        }
    }

    // Implementation of onRestore() here.
}

Controllare il backup su Android 12 o versioni successive

Se la tua app ha come target Android 12 (livello API 31) o versioni successive, segui i passaggi in questa sezione per controllare quali file vengono sottoposti a backup sui dispositivi con Android 12 o versioni successive.

Importante: anche se la tua app ha come target Android 12 o versioni successive, devi anche specificare un altro insieme di regole di backup XML per supportare i dispositivi con Android 11 (livello API 30) o versioni precedenti.

1. Nel file AndroidManifest.xml, aggiungi l'attributo android:dataExtractionRules all'elemento <application>, come mostrato nell'esempio seguente. Questo attributo rimanda a un file XML che contiene le regole di backup.

   <application ...
    android:dataExtractionRules="backup_rules.xml">
   </application>
   

2. Crea un file XML denominato backup_rules.xml nella directory res/xml/. In questo file, aggiungi le regole con gli elementi <include> e <exclude>. Il seguente esempio esegue il backup di tutte le preferenze condivise tranne device.xml:

   <?xml version="1.0" encoding="utf-8"?>
   <data-extraction-rules>
    <cloud-backup [disableIfNoEncryptionCapabilities="true|false"]>
      <include domain="sharedpref" path="."/>
      <exclude domain="sharedpref" path="device.xml"/>
    </cloud-backup>
   </data-extraction-rules>
   

Sintassi XML per la configurazione

La sintassi XML del file di configurazione varia a seconda della versione di Android scelta come target e in esecuzione nella tua app.

Android 11 o versioni precedenti

Utilizza la seguente sintassi XML per il file di configurazione che controlla il backup per i dispositivi con Android 11 o versioni precedenti.

<full-backup-content>
    <include domain=["file" | "database" | "sharedpref" | "external" |
                     "root" | "device_file" | "device_database" |
                     "device_sharedpref" | "device_root" ] path="string"
    requireFlags=["clientSideEncryption" | "deviceToDeviceTransfer"] />
    <exclude domain=["file" | "database" | "sharedpref" | "external" |
                     "root" | "device_file" | "device_database" |
                     "device_sharedpref" | "device_root" ] path="string" />
</full-backup-content>

Android 12 o versioni successive

Se la tua app ha come target Android 12 (livello API 31) o versioni successive, utilizza la seguente sintassi XML per il file di configurazione che controlla il backup per i dispositivi con Android 12 o versioni successive.

<data-extraction-rules>
  <cloud-backup [disableIfNoEncryptionCapabilities="true|false"]>
    ...
    <include domain=["file" | "database" | "sharedpref" | "external" |
                     "root" | "device_file" | "device_database" |
                     "device_sharedpref" | "device_root" ] path="string"/>
    ...
    <exclude domain=["file" | "database" | "sharedpref" | "external" |
                     "root" | "device_file" | "device_database" |
                     "device_sharedpref" | "device_root" ] path="string"/>
    ...
  </cloud-backup>
  <device-transfer>
    ...
    <include domain=["file" | "database" | "sharedpref" | "external" |
                     "root" | "device_file" | "device_database" |
                     "device_sharedpref" | "device_root" ] path="string"/>
    ...
    <exclude domain=["file" | "database" | "sharedpref" | "external" |
                     "root" | "device_file" | "device_database" |
                     "device_sharedpref" | "device_root" ] path="string"/>
    ...
  </device-transfer>
</data-extraction-rules>

Ogni sezione della configurazione (<cloud-backup>, <device-transfer>) contiene regole che si applicano solo a quel tipo di trasferimento. Questa separazione ti consente, ad esempio, di escludere un file o una directory dai backup di Google Drive mentre li trasferisci durante i trasferimenti da dispositivo a dispositivo (D2D). Ciò è utile se hai file troppo grandi per il backup sul cloud, ma che possono essere trasferiti da un dispositivo all'altro senza problemi.

Se non sono presenti regole per una determinata modalità di backup, ad esempio se manca la sezione <device-transfer>, tale modalità viene attivata completamente per tutti i contenuti, ad eccezione delle directory no-backup e cache, come descritto nella sezione File di cui è stato eseguito il backup.

La tua app può impostare il flag disableIfNoEncryptionCapabilities nella sezione <cloud-backup> per assicurarti che il backup venga eseguito solo se può essere criptato, ad esempio quando l'utente ha una schermata di blocco. L'impostazione di questo vincolo interrompe l'invio al cloud dei backup se il dispositivo dell'utente non supporta la crittografia. Tuttavia, poiché i trasferimenti D2D non vengono inviati al server, continuano a funzionare anche su dispositivi che non supportano la crittografia.

Sintassi degli elementi di inclusione ed esclusione

All'interno dei tag <full-backup-content>, <cloud-backup> e <device-transfer> (a seconda della versione di Android del dispositivo e di quella dell'app targetSDKVersion), puoi definire gli elementi <include> e <exclude>:

<include>

Specifica un file o una cartella di cui eseguire il backup. Per impostazione predefinita, Backup automatico include quasi tutti i file delle app. Se specifichi un elemento <include>, per impostazione predefinita il sistema non includerà più alcun file ed esegue il backup solo dei file specificati. Per includere più file, utilizza più elementi <include>.

Su Android 11 e versioni precedenti, questo elemento può anche contenere l'attributo requireFlags, di cui viene discussa in maggiore dettaglio la sezione in cui viene spiegato come definire i requisiti condizionali per il backup.

I file nelle directory restituiti da getCacheDir(), getCodeCacheDir() o getNoBackupFilesDir() vengono sempre esclusi anche se tenti di includerli.

Suggerimento: per eseguire il backup delle credenziali utente e dei token di autenticazione, non archiviarli nelle preferenze condivise o in un file. Utilizza invece le API Block Store per archiviare e gestire le credenziali. Ciò contribuisce a garantire che siano archiviati in modo sicuro e possano essere sottoposti a backup e ripristino insieme ad altri dati dell'app.

<exclude>

Specifica un file o una cartella da escludere durante il backup. Di seguito sono riportati alcuni file che in genere vengono esclusi dal backup:

• File con identificatori specifici del dispositivo, emessi da un server o generati sul dispositivo. Ad esempio, Firebase Cloud Messaging (FCM) deve generare un token di registrazione ogni volta che un utente installa la tua app su un nuovo dispositivo. Se il token di registrazione precedente viene ripristinato, l'app potrebbe comportarsi in modo imprevisto.

• File relativi al debug delle app.

• File di grandi dimensioni, per cui l'app supera la quota di backup di 25 MB.

Nota: se il file di configurazione specifica entrambi gli elementi, il backup contiene tutto ciò che è stato acquisito dagli elementi <include> meno le risorse denominate negli elementi <exclude>. In altre parole, <exclude> ha la precedenza.

Ogni elemento <include> e <exclude> deve includere i seguenti due attributi:

domain

Specifica la località della risorsa. I valori validi per questo attributo includono i seguenti:

• root: la directory nel file system in cui sono archiviati tutti i file privati appartenenti all'app.
• file: directory restituite da getFilesDir().
• database: directory restituite da getDatabasePath(). I database creati con SQLiteOpenHelper vengono archiviati qui.
• sharedpref: la directory in cui sono archiviati SharedPreferences.
• external: la directory restituita da getExternalFilesDir().
• device_root: ad esempio root per l'archiviazione protetta dal dispositivo.
• device_file: ad esempio file per l'archiviazione protetta dal dispositivo.
• device_database: ad esempio database per l'archiviazione protetta dal dispositivo.
• device_sharedpref: ad esempio sharedpref per l'archiviazione protetta dal dispositivo.

Nota: non puoi eseguire il backup dei file all'esterno di queste posizioni.

path

Specifica un file o una cartella da includere nel backup o da escludere. Tieni presente quanto segue:

• Questo attributo non supporta la sintassi con caratteri jolly o regex.
• Puoi fare riferimento alla directory corrente utilizzando ./, ma non puoi fare riferimento alla directory padre, ad esempio utilizzando .., per motivi di sicurezza.
• Se specifichi una directory, la regola si applica a tutti i file nella directory e nelle sottodirectory ricorsive.

Implementare BackupAgent

Per le app che implementano il backup automatico non è necessario implementare BackupAgent. Tuttavia, puoi facoltativamente implementare un elemento BackupAgent personalizzato. In genere, ciò ha due motivi:

• Vuoi ricevere una notifica in caso di eventi di backup, ad esempio onRestoreFinished() e onQuotaExceeded(long, long). Questi metodi di callback vengono eseguiti anche se l'app non è in esecuzione.

• Non puoi esprimere facilmente l'insieme di file di cui vuoi eseguire il backup con le regole XML. In questi rari casi, puoi implementare un BackupAgent che sostituisca onFullBackup(FullBackupDataOutput) per memorizzare ciò che vuoi. Per mantenere l'implementazione predefinita del sistema, chiama il metodo corrispondente nella superclasse con super.onFullBackup().

Se implementi BackupAgent, per impostazione predefinita il sistema prevede che l'app esegua backup e ripristino delle coppie chiave-valore. Per utilizzare invece il backup automatico basato su file, imposta l'attributo android:fullBackupOnly su true nel file manifest dell'app.

Durante le operazioni di backup e ripristino automatico, il sistema avvia l'app in modalità con restrizioni per impedire all'app di accedere a file che potrebbero causare conflitti e per consentire all'app di eseguire metodi di callback in BackupAgent. In questa modalità con restrizioni, l'attività principale dell'app non viene avviata automaticamente, i relativi fornitori di contenuti non vengono inizializzati e viene creata un'istanza della classe base Application al posto di una sottoclasse dichiarata nel manifest dell'app.

Attenzione: per evitare errori, assicurati che le parti della tua app eseguite in modalità con restrizioni (principalmente la tua BackupAgent) non accedano ai provider di contenuti nella stessa app o non provino a trasmettere l'oggetto Application. Se è impossibile evitare questi pattern, valuta l'implementazione del backup delle coppie chiave-valore o della disabilitazione del backup del tutto.

BackupAgent deve implementare i metodi astratti onBackup() e onRestore(), utilizzati per il backup delle coppie chiave-valore. Se non vuoi eseguire il backup delle coppie chiave-valore, puoi lasciare vuota l'implementazione di questi metodi.

Per ulteriori informazioni, vedi Extend BackupAgent.