Backup automatico per le 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 su Google Drive dell'utente, dove sono protetti dalle credenziali dell'Account Google dell'utente. Il backup è criptato end-to-end sui dispositivi con Android 9 o versioni successive utilizzando il PIN, la sequenza o la password del dispositivo. Ogni app può allocare fino a 25 MB di dati di backup per utente dell'app. Non sono previsti costi 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 su quali dati eseguire il backup e ripristinare, consulta la panoramica del backup dei dati.
File sottoposti a backup
Per impostazione predefinita, Backup automatico include i file presenti nella maggior parte delle directory assegnate alla tua app dal sistema:
File delle preferenze condivise
File salvati nella memoria interna dell'app e a cui si accede tramite
getFilesDir()
ogetDir(String, int)
I file nella directory restituita da
getDatabasePath(String)
, che include anche i file creati con la classeSQLiteOpenHelper
File sullo spazio di archiviazione esterno nella directory restituita da
getExternalFilesDir(String)
Il 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 l'app in modo da includere ed escludere file specifici. Per ulteriori informazioni, consulta la sezione Includi ed escludi file.
Posizione di backup
I dati di backup vengono archiviati in una cartella privata dell'account Google Drive dell'utente, con un limite di 25 MB per app. I dati salvati non vengono conteggiati ai fini della quota personale di Google Drive dell'utente. Viene archiviato solo il backup più recente. Quando viene eseguito un backup, qualsiasi backup precedente viene eliminato. I dati di backup non possono essere letti dall'utente o da altre app sul dispositivo.
Gli utenti possono vedere un elenco delle app di cui è stato eseguito il backup nell'app Google Drive per Android. Su un dispositivo Android, gli utenti possono trovare questo elenco nel riquadro di navigazione dell'app Drive in Impostazioni > Backup e ripristino.
I backup di ogni lifetime di configurazione del dispositivo vengono archiviati in set di dati separati, come descritto negli esempi seguenti:
Se l'utente possiede due dispositivi, esiste un set di dati di backup per ogni dispositivo.
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à.
Programmazione backup
I backup vengono eseguiti automaticamente quando vengono 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 è connesso a una rete Wi-Fi (se l'utente del dispositivo non ha attivato i backup con i dati mobili).
In pratica, queste condizioni si verificano all'incirca ogni notte, ma il backup di un dispositivo potrebbe non essere mai eseguito (ad esempio, se non si connette mai a una rete). Per risparmiare larghezza di banda della rete, il caricamento avviene solo se i dati dell'app sono stati modificati.
Durante il backup automatico, il sistema arresta l'app per assicurarsi che non stia più scrivendo sul file system. Per impostazione predefinita, il sistema di backup ignora le app in esecuzione in primo piano per evitare un'esperienza utente negativa. Puoi ignorare il comportamento predefinito impostando l'attributo android:backupInForeground
su true.
Per semplificare i test, Android include strumenti che ti consentono di avviare manualmente un backup della tua 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 app installate in precedenza) o eseguendo l'installazione di adb
. L'operazione di ripristino avviene dopo l'installazione dell'APK, ma prima che l'app sia disponibile per essere avviata dall'utente.
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 utilizzare per il ripristino. Il set di dati di backup selezionato diventa il set di dati ancestrale per il 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 eseguito la procedura guidata di configurazione 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 recupero della tua app. Per ulteriori informazioni, consulta Testare il backup e il ripristino.
Attivare e disattivare il backup
Le app che hanno come target 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 nell'esempio seguente:
<manifest ... >
...
<application android:allowBackup="true" ... >
...
</application>
</manifest>
Puoi disattivare i backup impostando android:allowBackup
su false
. Potresti voler eseguire questa operazione se la tua app può ricreare il proprio stato tramite un altro meccanismo o se gestisce informazioni sensibili.
Includere ed escludere file
Per impostazione predefinita, il sistema esegue il backup di quasi tutti i dati dell'app. Per ulteriori informazioni, consulta la sezione sui file di cui viene eseguito il backup.
Questa sezione mostra come definire regole XML personalizzate per controllare i dati sottoposti a backup. Se la tua app ha come target Android 12 (livello API 31) o versioni successive, devi specificare un ulteriore insieme di regole di backup XML, come descritto in questa sezione, per supportare le modifiche al ripristino del backup introdotte per i dispositivi con queste versioni di Android.
Controllare il backup su Android 11 e versioni precedenti
Segui i passaggi descritti in questa sezione per controllare i file di cui viene eseguito il backup sui dispositivi con Android 11 (livello API 30) o versioni precedenti.
Nel file
AndroidManifest.xml
, aggiungi l'attributoandroid:fullBackupContent
all'elemento<application>
, come mostrato nell'esempio seguente. Questo attributo rimanda a un file XML contiene le regole di backup.<application ... android:fullBackupContent="@xml/backup_rules"> </application>
Crea un file XML denominato
@xml/backup_rules
nella directoryres/xml/
. In questo file, aggiungi regole con gli elementi<include>
e<exclude>
. L'esempio seguente esegue il backup di tutte le preferenze condivise trannedevice.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 della tua 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 segreto lato client. Questa forma di crittografia è 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 suo dispositivo.deviceToDeviceTransfer
: l'utente sta trasferendo il backup su un altro dispositivo che supporta il trasferimento locale da dispositivo a dispositivo (ad esempio, Google Pixel).
Se hai eseguito l'upgrade dei tuoi dispositivi di sviluppo ad Android 9, devi disattivare e poi riattivare il backup dei dati dopo l'upgrade. Questo perché Android cripta i backup solo con un segreto lato client dopo aver informato gli utenti nelle Impostazioni o nella procedura guidata di configurazione.
Per dichiarare le condizioni di inclusione, imposta l'attributo requireFlags
su uno o più valori scelti negli elementi <include>
all'interno dell'insieme di regole di backup:
<?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 tua app implementa un sistema di backup di tipo chiave-valore o se implementi personalmenteBackupAgent
, puoi applicare questi requisiti condizionali anche 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.
Il seguente snippet di codice 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 descritti in questa sezione per controllare i file di cui viene eseguito il backup sui dispositivi con Android 12 o versioni successive.
Nel file
AndroidManifest.xml
, aggiungi l'attributoandroid:dataExtractionRules
all'elemento<application>
, come mostrato nell'esempio seguente. Questo attributo fa riferimento a un file XML contenente le regole di backup.<application ... android:dataExtractionRules="backup_rules.xml"> </application>
Crea un file XML denominato
backup_rules.xml
nella directoryres/xml/
. In questo file, aggiungi le regole con gli elementi<include>
e<exclude>
. L'esempio seguente esegue il backup di tutte le preferenze condivise trannedevice.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 della configurazione XML
La sintassi XML del file di configurazione varia a seconda della versione di Android su cui è destinata e in cui viene eseguita l'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, continuando a trasferirli durante i trasferimenti tra dispositivo (D2D). Questa opzione è utile se hai file troppo grandi per il backup sul cloud, ma che possono essere trasferiti tra dispositivi senza problemi.
Se non ci sono regole per una determinata modalità di backup, ad esempio se manca la sezione <device-transfer>
, questa modalità è completamente abilitata 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 impedisce l'invio dei backup al cloud se il dispositivo dell'utente non supporta la crittografia, ma poiché i trasferimenti D2D non vengono inviati al server, continuano a funzionare anche sui dispositivi che non supportano la crittografia.
Sintassi per gli elementi include ed exclude
All'interno dei tag <full-backup-content>
, <cloud-backup>
e <device-transfer>
(a seconda della versione di Android del dispositivo e del valore targetSDKVersion
dell'app), puoi definire gli elementi <include>
e <exclude>
:
<include>
Specifica un file o una cartella di cui eseguire il backup. Per impostazione predefinita, il backup automatico include quasi tutti i file delle app. Se specifichi un elemento
<include>
, il sistema non include più alcun file per impostazione predefinita e esegue il backup solo dei file specificati. Per includere più file, utilizza più elementi<include>
.Su Android 11 e versioni precedenti, questo elemento può contenere anche l'attributo
requireFlags
, descritto in modo più dettagliato nella sezione su come definire i requisiti condizionali per il backup.I file nelle directory restituite da
getCacheDir()
,getCodeCacheDir()
ogetNoBackupFilesDir()
sono sempre esclusi anche se provi a includerli.<exclude>
Specifica un file o una cartella da escludere durante il backup. Ecco 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 che causano il superamento della quota di backup di 25 MB da parte dell'app.
Ogni elemento <include>
e <exclude>
deve includere i seguenti due attributi:
domain
Specifica la posizione della risorsa. I valori validi per questo attributo includono quanto segue:
root
: la directory del file system in cui sono archiviati tutti i file privati appartenenti all'app.file
: directory restituite dagetFilesDir()
.database
: directory restituite dagetDatabasePath()
. I database creati conSQLiteOpenHelper
vengono archiviati qui.sharedpref
: la directory in cui sono archiviati i fileSharedPreferences
.external
: la directory restituita dagetExternalFilesDir()
.device_root
: ad esempioroot
, ma per lo spazio di archiviazione protetto dal dispositivo.device_file
: comefile
, ma per lo spazio di archiviazione protetto dal dispositivo.device_database
: comedatabase
, ma per lo spazio di archiviazione protetto dal dispositivo.device_sharedpref
: comesharedpref
, ma per lo spazio di archiviazione protetto dal dispositivo.
path
Specifica un file o una cartella da includere o escludere dal backup. Tieni presente quanto segue:
- Questo attributo non supporta la sintassi dei caratteri jolly o delle espressioni regolari.
- Puoi fare riferimento alla directory corrente utilizzando
./
, ma non puoi fare riferimento alla directory principale, ad esempio utilizzando..
, per motivi di sicurezza. - Se specifichi una directory, la regola si applica a tutti i file al suo interno e alle sottodirectory ricorsive.
Implementa BackupAgent
Le app che implementano il backup automatico non devono implementare un BackupAgent
.
Tuttavia, se vuoi, puoi implementare un elemento BackupAgent
personalizzato. In genere, ciò è possibile per due motivi:
Vuoi ricevere una notifica degli eventi di backup, ad esempio
onRestoreFinished()
eonQuotaExceeded(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 sostituisceonFullBackup(FullBackupDataOutput)
per archiviare ciò che vuoi. Per mantenere l'implementazione predefinita del sistema, chiama il metodo corrispondente sulla superclass consuper.onFullBackup()
.
Se implementi un BackupAgent
, per impostazione predefinita il sistema si aspetta che la tua app esegua il backup e il ripristino delle coppie chiave-valore. Per utilizzare il backup automatico basato su file, imposta l'attributo android:fullBackupOnly
su true
nel file manifest della tua app.
Durante le operazioni di backup e ripristino automatico, il sistema avvia l'app in una modalità limitata per impedire all'app di accedere ai file che potrebbero causare conflitti e consentire all'app di eseguire i metodi di callback nel suo BackupAgent
. In questa
modalità limitata, l'attività principale dell'app non viene avviata automaticamente, i suoi
fornitori di contenuti non vengono inizializzati e la classe di base
Application
viene creata anziché qualsiasi sottoclasse dichiarata nel
manifest dell'app.
BackupAgent
deve implementare i metodi astratti onBackup()
e
onRestore()
, che vengono 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, consulta Estendere BackupAgent.