Back up dei dati dell’utente con Auto Backup

Auto Backup for Apps esegue automaticamente il backup dei dati di un utente dalle applicazioni che mirano ed eseguono su Android 6.0 (livello API 23) o successivo. Android conserva i dati delle app caricandoli su Google Drive dell’utente, dove sono protetti dalle credenziali dell’account Google dell’utente. La quantità di dati è limitata a 25MB per utente della tua app e non ci sono costi per la conservazione dei dati di backup. La tua app può personalizzare il processo di backup o scegliere di disattivare i backup.

Per una panoramica delle opzioni di backup di Android e una guida su quali dati dovresti eseguire il backup e il ripristino, consulta la panoramica del backup dei dati.

File di cui viene eseguito il backup

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

• File delle preferenze condivise.
• File salvati nella memoria interna della tua app, accessibile tramite getFilesDir() o getDir(String, int).
• File nella directory restituita da getDatabasePath(String), che include anche i file creati con la classe SQLiteOpenHelper.
• File su memoria esterna nella directory restituita da getExternalFilesDir(String).

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

Puoi configurare la tua applicazione per includere ed escludere particolari file. Per maggiori informazioni, vedi la sezione Includere ed escludere i file.

Nota: Android non tratta la configurazione dei componenti come dati utente. Se la tua app abilita o disabilita componenti specifici nel suo manifest mentre è in esecuzione, non aspettarti che AutoBackup salvi e ripristini la configurazione. Per preservare lo stato della configurazione, salvalo in Preferenze condivise e recupera le Preferenze condivise al ripristino. Se vuoi che la tua app salvi il suo stato, salva lo stato in Shared Preferences e recupera Shared Preferences al ripristino.

Luogo del backup

I dati del backup sono memorizzati in una cartella privata nell’account Google Drive dell’utente, limitata a 25MB per app. I dati salvati non contano per la quota personale di Google Drive dell’utente. Viene memorizzato solo il backup più recente. Quando viene fatto un backup, il backup precedente (se esiste) viene cancellato. I dati di backup non possono essere letti dall’utente o da altre applicazioni sul dispositivo.

Gli utenti possono vedere un elenco di applicazioni di cui è stato eseguito il backup nell’app Google DriveAndroid. Su un dispositivo alimentato da Android, gli utenti possono trovare questo elenco nel cassetto di navigazione dell’app Drive sotto Impostazioni > Backup e ripristino > Dati delle app.

I backup di ogni dispositivo sono memorizzati in set di dati separati come mostrato nei seguenti esempi:

• Se l’utente possiede due dispositivi, allora esiste un set di dati di backup per ogni dispositivo.
• Se l’utente reimposta di fabbrica un dispositivo e poi imposta il dispositivo con lo stesso account, il backup viene memorizzato in un nuovo set di dati. I dataset obsoleti vengono automaticamente cancellati dopo un periodo di inattività.

Pianificazione del backup

Il backup avviene automaticamente quando tutte le seguenti condizioni sono soddisfatte:

• L’utente ha attivato il backup sul dispositivo. In Android 9, questa impostazione è inImpostazioni > Sistema > Backup.
• Sono trascorse almeno 24 ore dall’ultimo backup.
• Il dispositivo è inattivo.
• Il dispositivo è connesso a una rete Wi-Fi (se l’utente del dispositivo non ha optato per il backup dei dati mobili).

In pratica, queste condizioni si verificano circa ogni notte, ma un dispositivo potrebbe non fare mai il backup (per esempio, se non si connette mai a una rete). Per conservare la larghezza di banda della rete, l’upload avviene solo se i dati dell’app sono cambiati.

Durante il backup automatico, il sistema spegne l’app per assicurarsi che non stia più scrivendo sul file system. Per impostazione predefinita, il sistema di backup ignora le app che sono in esecuzione in primo piano perché gli utenti noterebbero che le loro app vengono chiuse. Puoi sovrascrivere il comportamento predefinito impostando l’attributo backupInForeground a true.

Per semplificare i test, Android include strumenti che ti permettono di avviare manualmente un backup della tua app. Per maggiori informazioni, vedi Test di backup e ripristino.

Programma di ripristino

I dati vengono ripristinati ogni volta che l’app viene installata, sia dal Play store, durante la configurazione del dispositivo (quando il sistema installa le app precedentemente installate), o dall’esecuzione di adb install. L’operazione di ripristino avviene dopo l’installazione dell’APK, ma prima che l’app sia disponibile per essere lanciata dall’utente.

Durante la procedura guidata di configurazione iniziale del dispositivo, all’utente viene mostrato un elenco di set di dati di backup disponibili e gli viene chiesto da quale ripristinare i dati. Il set di dati di backup selezionato diventa il set di dati ancestrale per il dispositivo. Il dispositivo può ripristinare dai propri backup o dal dataset ancestrale. Il dispositivo dà la priorità al proprio backup se i backup da entrambe le fonti sono disponibili. Se l’utente non è passato attraverso la procedura guidata di configurazione del dispositivo, allora il dispositivo può ripristinare solo dai propri backup.

Per semplificare i test, Android include strumenti che ti permettono di avviare manualmente un ripristino della tua applicazione. Per maggiori informazioni, vedi Test di backup e ripristino.

Abilitare e disabilitare il backup

Le app che puntano ad Android 6.0 (livello API 23) o superiore partecipano automaticamente al backup automatico. Nel file manifest della tua app, imposta il valore booleanoandroid:allowBackupper abilitare o disabilitare il backup. Il valore predefinito è true ma per rendere chiare le tue intenzioni, ti consigliamo di impostare esplicitamente l’attributo nel tuo manifest come mostrato di seguito:

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

Puoi disabilitare i backup impostando android:allowBackup a false. Potresti volerlo fare se la tua app può ricreare il suo stato attraverso qualche altro meccanismo o se la tua app ha a che fare con informazioni sensibili di cui Android non dovrebbe fare il backup.

Includere ed escludere i file

Per impostazione predefinita, il sistema esegue il backup di quasi tutti i dati delle app. Per maggiori informazioni, vedi File di cui viene eseguito il backup. Questa sezione mostra come definire regole XML personalizzate per controllare cosa viene sottoposto a backup.

1. In AndroidManifest.xml, aggiungere l’attributo android:fullBackupContent all’elemento <application>. Questo attributo punta a un file XML che contiene le regole di backup. For example:

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

2. Create an XML file called my_backup_rules.xml in theres/xml/ directory. Inside the file, add rules with the<include> and <exclude> elements.The following sample backs up all shared preferences exceptdevice.xml

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

XML config syntax

The XML syntax for the configuration file is shown below:

<full-backup-content> <include domain= path="string" requireFlags= /> <exclude domain= path="string" /></full-backup-content>

Inside the <full-backup-content> tag, you can define <include> and <exclude> elements:

• <include> – Specifies a file or folder to backup. By default, Auto Backup includes almost all app files. If you specify an <include> element, the system no longer includes any files by default and backs up only the files specified. Per includere più file, usa più elementi <include>.

  Nota: i file nelle directory restituite da getCacheDir()getCodeCacheDir(), o getNoBackupFilesDir() sono sempre esclusi anche se si cerca di includerli.

• <exclude> – Specifica un file o una cartella da escludere durante il backup. Ecco alcuni file che sono tipicamente esclusi dal backup:
  • File che hanno identificatori specifici del dispositivo, emessi da un server o generati sul dispositivo. Per esempio, Google Cloud Messaging (GCM) deve generare un token di registrazione ogni volta che un utente installa la tua app su un nuovo dispositivo. Se il vecchio token di registrazione viene ripristinato, l’app potrebbe comportarsi in modo inaspettato.
  • Credenziali dell’account o altre informazioni sensibili. Considerate di chiedere all’utente di autenticarsi nuovamente la prima volta che lancia un’app ripristinata piuttosto che permettere la memorizzazione di tali informazioni nel backup.
  • File relativi al debug delle app.
  • Large files that cause the app to exceed the 25MB backup quota.

Note: If your configuration file specifies both elements, then the backup contains everything captured by the <include> elements minus the resources named in the <exclude> elements. In other words, <exclude> takes precedence.

Each element must include the following two attributes:

• domain – specifies the location of resource. Valid values for this attribute include the following:
  • root – the directory on the filesystem where all private files belonging to this app are stored.
  • file – directories returned by getFilesDir().
  • database – directories returned by getDatabasePath(). Databases created with SQLiteOpenHelper are stored here.
  • sharedpref – the directory where SharedPreferences are stored.
  • external the directory returned by getExternalFilesDir()

Note: You cannot back up files outside of these locations.

• path: Specifies a file or folder to include in or exclude from backup. Note that:
  • This attribute does not support wildcard or regex syntax.
  • You can use . to reference the current directory, however, you cannot reference the parent directory .. for security reasons.
  • If you specify a directory, then the rule applies to all files in the directory and recursive sub-directories.

The include element can also contain the requireFlags attribute, which thesection describing how to define conditional requirements forbackup section discusses in more detail.

Definire le condizioni del dispositivo richieste per il backup

Se la vostra app salva informazioni sensibili sul dispositivo, potete specificare le condizioni in base alle quali i dati della vostra app sono inclusi nel backup dell’utente. È possibile aggiungere le seguenti condizioni in Android 9 (livello API 28) o superiore:

• clientSideEncryption: Il backup dell’utente è criptato con un client-sidesecret. Questa forma di crittografia è abilitata sui dispositivi con Android 9 o superiore, a condizione che l’utente abbia abilitato il backup in Android 9 o superiore e abbia impostato un blocco dello schermo (PIN, modello o password) per il proprio dispositivo.
• deviceToDeviceTransfer: L’utente sta trasferendo il suo backup a un altro dispositivo che supporta il trasferimento locale da dispositivo a dispositivo (per esempio, Google Pixel).

Se hai aggiornato i tuoi dispositivi di sviluppo ad Android 9, è necessario disabilitare e poi riabilitare il backup dei dati dopo l’aggiornamento. Questo perché Android cripta i backup con un segreto lato client solo dopo aver informato gli utenti in Impostazioni o nel Setup Wizard.

Per dichiarare le condizioni di inclusione, impostate l’attributo requireFlags al valore o ai valori desiderati nei vostri elementi <include> nel vostro set di regole dibackup:

my_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>

Se la vostra app implementa un sistema di backup chiave-valore, o se voi stessi implementateBackupAgent,potete anche applicare questi requisiti condizionali alla vostra logica di backup eseguendo un confronto bitwise tra unBackupDataOutput set di flag di trasporto di un oggetto e il vostro agente di backup personalizzatoFLAG_CLIENT_SIDE_ENCRYPTION_ENABLEDo FLAG_DEVICE_TO_DEVICE_TRANSFERflags.

Il seguente frammento di codice mostra un esempio di utilizzo di questo metodo:

class MyCustomBackupAgent : 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.}

public class MyCustomBackupAgent 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.}

Implement BackupAgent

Apps that implement Auto Backup do not need to implement a BackupAgent. However, you can optionally implement a custom BackupAgent. Typically, there are two reasons for doing this:

• You want to receive notification of backup events such as, onRestoreFinished() or onQuotaExceeded(long, long). These callback methods are executed even if the app is not running.
• You can’t easily express the set of files you want to backup with XML rules. In these rare cases, you can implement a BackupAgent that overrides onFullBackup(FullBackupDataOutput) to store what you want. To retain the system’s default implementation, call the corresponding method on the superclass with super.onFullBackup().

If you implement a BackupAgent, by default the system expects your app to perform key/value backup and restore. Per utilizzare invece il backup automatico basato su file, impostare l’attributo android:fullBackupOnly a true nel manifest della tua app.

Durante le operazioni di backup e ripristino automatico, il sistema lancia l’app in una modalità ristretta sia per impedire all’app di accedere a file che potrebbero causare conflitti, sia per permettere all’app di eseguire metodi di callback nel suo BackupAgent. In questa modalità ristretta, l’attività principale dell’app non viene lanciata automaticamente, i suoi Content Provider non vengono inizializzati e la classe base Application viene istanziata al posto di qualsiasi sottoclasse dichiarata nel manifest dell’app.

Attenzione: Per evitare errori, assicurati che le parti della tua app che vengono eseguite in modalità ristretta (per lo più il tuo BackupAgent) non accedano a fornitori di contenuti nella stessa app o tentino di eseguire il cast dell’oggetto Application. Se non potete evitare questi schemi, allora prendete in considerazione l’implementazione del backup chiave/valore o disabilitate completamente il backup.

Il vostro BackupAgent deve implementare i metodi astratti onBackup() e onRestore(), che sono usati per il backup chiave-valore. Ma se non si vuole eseguire il backup chiave-valore, si può semplicemente lasciare vuota l’implementazione di questi metodi.

Per maggiori informazioni, vedere Estensione di BackupAgent.