Back up user data with Auto Backup

Auto Backup for Apps automatycznie tworzy kopie zapasowe danych użytkownika z aplikacji, które są przeznaczone i działają w systemie Android 6.0 (poziom API 23) lub nowszym. Android zachowuje appdata przesyłając je do użytkownika na Google Drive – gdzie jest chroniony przez użytkownika poświadczeń konta Google. Ilość danych jest ograniczona do 25MB na użytkownika Twojej aplikacji i nie ma opłaty za przechowywanie danych kopii zapasowej. Twoja aplikacja może dostosować proces tworzenia kopii zapasowej lub zrezygnować z niego przez wyłączenie tworzenia kopii zapasowych.

Aby uzyskać przegląd opcji tworzenia kopii zapasowych w systemie Android i wskazówki dotyczące danych, które należy tworzyć i przywracać, zapoznaj się z przeglądem kopii zapasowych danych.

Pliki, które są zapisywane w kopii zapasowej

Domyślnie funkcja Auto Backup obejmuje pliki w większości katalogów przypisanych do Twojej aplikacji przez system:

• Pliki preferencji współdzielonych.
• Pliki zapisane w wewnętrznej pamięci masowej aplikacji, dostępne przez getFilesDir() lub getDir(String, int).
• Pliki w katalogu zwróconym przez getDatabasePath(String), który obejmuje również pliki utworzone za pomocą klasy SQLiteOpenHelper.
• Pliki na zewnętrznej pamięci masowej w katalogu zwracanym przez getExternalFilesDir(String).

Funkcja Auto Backup wyklucza pliki znajdujące się w katalogach zwróconych przez getCacheDir()getCodeCacheDir() lub getNoBackupFilesDir(). Pliki zapisane w tych lokalizacjach są potrzebne tylko tymczasowo lub są celowo wyłączone z operacji tworzenia kopii zapasowych.

Możesz skonfigurować swoją aplikację tak, aby uwzględniała i wykluczała określone pliki. Więcej informacji na ten temat znajdziesz w sekcji Dołączanie i wykluczanie plików.

Uwaga: System Android nie traktuje konfiguracji komponentów jako danych użytkownika. Jeśli Twoja aplikacja włącza lub wyłącza określone komponenty w swoim manifeście podczas działania, nie oczekuj, że program AutoBackup zapisze i przywróci konfigurację. Aby zachować stan konfiguracji, zapisz ją w Preferencjach współdzielonych i odzyskaj Preferencje współdzielone przy przywracaniu. Jeśli chcesz, aby Twoja aplikacja zachowała swój stan, zapisz stan w Preferencjach współdzielonych i odzyskaj Preferencje współdzielone przy przywracaniu.

Lokalizacja kopii zapasowej

Dane kopii zapasowej są przechowywane w prywatnym folderze na koncie Google Drive użytkownika, z ograniczeniem do 25MB na aplikację. Zapisane dane nie wliczają się do osobistego limitu użytkownika w Google Drive. Zapisywana jest tylko najnowsza kopia zapasowa. Podczas tworzenia kopii zapasowej poprzednia kopia zapasowa (jeśli istnieje) jest usuwana. Dane z kopii zapasowej nie mogą być odczytywane przez użytkownika ani inne aplikacje na urządzeniu.

Użytkownicy mogą zobaczyć listę aplikacji, których kopie zapasowe zostały utworzone w aplikacji Google DriveAndroid. W urządzeniu z systemem Android użytkownicy mogą znaleźć tę listę w szufladzie nawigacyjnej aplikacji Drive w sekcji Ustawienia > Kopia zapasowa i zerowanie > Dane aplikacji.

Kopie zapasowe z każdego urządzenia są przechowywane w oddzielnych zbiorach danych, jak pokazano w następujących przykładach:

• Jeśli użytkownik posiada dwa urządzenia, dla każdego z nich istnieje zbiór danych kopii zapasowej.
• Jeśli użytkownik zresetuje fabrycznie urządzenie, a następnie skonfiguruje je przy użyciu tego samego konta, kopia zapasowa jest przechowywana w nowym zbiorze danych. Nieaktualne zestawy danych są automatycznie usuwane po pewnym czasie bezczynności.

Harmonogram tworzenia kopii zapasowych

Kopie zapasowe są tworzone automatycznie, gdy spełnione są wszystkie poniższe warunki:

• Użytkownik włączył tworzenie kopii zapasowych na urządzeniu. W systemie Android 9 to ustawienie znajduje się wUstawienia > System > Backup.
• Od ostatniej kopii zapasowej minęły co najmniej 24 godziny.
• Urządzenie jest bezczynne.
• Urządzenie jest połączone z siecią Wi-Fi (jeśli użytkownik urządzenia nie wybrał opcji tworzenia kopii zapasowych danych mobilnych).

W praktyce te warunki występują mniej więcej co noc, ale urządzenie może nigdy nie utworzyć kopii zapasowej (na przykład jeśli nigdy nie połączy się z siecią). Aby zachować przepustowość sieci, przesyłanie danych odbywa się tylko wtedy, gdy dane aplikacji uległy zmianie.

Podczas automatycznego tworzenia kopii zapasowej system wyłącza aplikację, aby upewnić się, że nie zapisuje ona już danych w systemie plików. Domyślnie system tworzenia kopii zapasowych ignoruje aplikacje działające na pierwszym planie, ponieważ użytkownicy zauważyliby, że ich aplikacje są wyłączane. Można zastąpić domyślne zachowanie, ustawiając atrybut backupInForeground na wartość true.

Aby uprościć testowanie, system Android zawiera narzędzia, które pozwalają ręcznie zainicjować tworzenie kopii zapasowej aplikacji. Aby uzyskać więcej informacji, zobacz Testuj kopię zapasową i przywracanie.

Harmonogram przywracania

Dane są przywracane za każdym razem, gdy aplikacja jest instalowana, albo ze sklepu Play, albo podczas konfiguracji urządzenia (kiedy system instaluje wcześniej zainstalowane aplikacje), albo po uruchomieniu adb install. Operacja przywracania danych następuje po zainstalowaniu APK, ale zanim aplikacja będzie dostępna do uruchomienia przez użytkownika.

Podczas kreatora początkowej konfiguracji urządzenia, użytkownikowi wyświetlana jest lista dostępnych zbiorów danych kopii zapasowej i jest on pytany o to, z którego zbioru przywrócić dane. Niezależnie od tego, który zapasowy zbiór danych zostanie wybrany, staje się on pierwotnym zbiorem danych dla urządzenia. Urządzenie może przywrócić dane zarówno z własnej kopii zapasowej, jak i z macierzystego zbioru danych. Jeśli dostępne są kopie zapasowe z obu źródeł, urządzenie traktuje priorytetowo swoją własną kopię zapasową. Jeśli użytkownik nie przeszedł przez kreator konfiguracji urządzenia, to urządzenie może przywrócić dane tylko z własnych kopii zapasowych.

Aby uprościć testowanie, system Android zawiera narzędzia, które pozwalają ręcznie zainicjować przywracanie aplikacji. Aby uzyskać więcej informacji, zobacz Testuj tworzenie i przywracanie kopii zapasowych.

Włączanie i wyłączanie tworzenia kopii zapasowych

Aplikacje, które działają w systemie Android 6.0 (poziom API 23) lub nowszym, automatycznie uczestniczą w funkcji Auto Backup. W pliku manifestu aplikacji ustaw wartość logicznąandroid:allowBackup, aby włączyć lub wyłączyć tworzenie kopii zapasowej. Domyślną wartością jest true, ale aby jasno określić swoje intencje, zalecamy jawne ustawienie atrybutu w swoim manifeście, jak pokazano poniżej:

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

Możesz wyłączyć kopie zapasowe, ustawiając android:allowBackup na false. Możesz chcieć to zrobić, jeśli twoja aplikacja może odtworzyć swój stan za pomocą innego mechanizmu lub jeśli twoja aplikacja zajmuje się wrażliwymi informacjami, których Android nie powinien tworzyć kopii zapasowych.

Załącz i wyklucz pliki

Domyślnie, system tworzy kopie zapasowe prawie wszystkich danych aplikacji. Aby uzyskać więcej informacji, zobacz Pliki, których kopie zapasowe są tworzone. Ta sekcja pokazuje, jak zdefiniować niestandardowe reguły XML, aby kontrolować, co jest tworzone w kopii zapasowej.

1. W AndroidManifest.xml, dodaj atrybut android:fullBackupContent do elementu <application>. Atrybut ten wskazuje na plik XML zawierający reguły tworzenia kopii zapasowych. 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. Aby uwzględnić wiele plików, należy użyć wielu elementów <include>.

  Uwaga: Pliki w katalogach zwróconych przez getCacheDir()getCodeCacheDir(), lub getNoBackupFilesDir() są zawsze wykluczone, nawet jeśli próbujesz je dołączyć.

• <exclude> – Określa plik lub folder, który ma zostać wykluczony podczas tworzenia kopii zapasowej. Oto kilka plików, które są zwykle wykluczane z kopii zapasowej:
  • Pliki, które mają identyfikatory specyficzne dla urządzenia, wydawane przez serwer lub generowane na urządzeniu. Na przykład Google Cloud Messaging (GCM) musi wygenerować token rejestracyjny za każdym razem, gdy użytkownik instaluje Twoją aplikację na nowym urządzeniu. Jeśli stary token rejestracyjny zostanie przywrócony, aplikacja może zachowywać się nieoczekiwanie.
  • Poświadczenia konta lub inne wrażliwe informacje. Warto rozważyć poproszenie użytkownika o ponowne uwierzytelnienie przy pierwszym uruchomieniu przywróconej aplikacji, zamiast zezwalać na przechowywanie takich informacji w kopii zapasowej.
  • Pliki związane z debugowaniem aplikacji.
  • 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.

Zdefiniuj warunki urządzenia wymagane do wykonania kopii zapasowej

Jeśli Twoja aplikacja zapisuje wrażliwe informacje na urządzeniu, możesz określić warunki, po spełnieniu których dane aplikacji zostaną uwzględnione w kopii zapasowej użytkownika. Możesz dodać następujące warunki w systemie Android 9 (poziom API 28) lub wyższym:

• clientSideEncryption: Kopia zapasowa użytkownika jest szyfrowana za pomocą client-secret. Ta forma szyfrowania jest dostępna na urządzeniach z systemem Android 9 lub nowszym, o ile użytkownik włączył funkcję tworzenia kopii zapasowych w systemie Android 9 lub nowszym i ustawił dla swojego urządzenia blokadę ekranową (PIN, wzór lub hasło).
• deviceToDeviceTransfer: Użytkownik przenosi swoją kopię zapasową na inne urządzenie, które obsługuje lokalny transfer między urządzeniami (na przykład Google Pixel).

Jeśli uaktualniłeś swoje urządzenia deweloperskie do systemu Android 9, musisz wyłączyć i ponownie włączyć tworzenie kopii zapasowej danych po uaktualnieniu. Dzieje się tak, ponieważ system Android szyfruje kopie zapasowe za pomocą sekretu po stronie klienta po poinformowaniu użytkowników w Ustawieniach lub Kreatorze konfiguracji.

Aby zadeklarować warunki włączenia, ustaw atrybut requireFlags na żądaną wartość lub wartości w elementach <include> w swoim zestawie reguł tworzenia kopii zapasowych:

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>

Jeśli Twoja aplikacja implementuje system backupu klucz-wartość, lub jeśli sam implementujeszBackupAgent,możesz również zastosować te wymagania warunkowe do swojej logiki tworzenia kopii zapasowych, wykonując porównanie bitowe między zestawem flag transportowych obiektuBackupDataOutput a niestandardowym agentem kopii zapasowejFLAG_CLIENT_SIDE_ENCRYPTION_ENABLED lub FLAG_DEVICE_TO_DEVICE_TRANSFERflag.

Poniższy wycinek kodu pokazuje przykładowe użycie tej metody:

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. Aby zamiast tego użyć Auto Backup opartego na plikach, ustaw atrybut android:fullBackupOnly na true w manifeście swojej aplikacji.

Podczas operacji automatycznego tworzenia kopii zapasowych i przywracania system uruchamia aplikację w trybie ograniczonym, aby zarówno uniemożliwić aplikacji dostęp do plików, które mogłyby powodować konflikty, jak i pozwolić aplikacji wykonywać metody wywołania zwrotnego w jej BackupAgent. W trybie ograniczonym główna aktywność aplikacji nie jest automatycznie uruchamiana, jej Content Providers nie są inicjalizowane, a klasa bazowa Application jest instancjonowana zamiast dowolnej podklasy zadeklarowanej w manifeście aplikacji.

Uwaga: Aby uniknąć błędów, upewnij się, że części twojej aplikacji, które wykonują się w trybie ograniczonym (głównie twój BackupAgent) nie uzyskują dostępu do dostawców treści w tej samej aplikacji lub próbują rzucić obiekt Application. Jeśli nie możesz uniknąć tych wzorców, to rozważ wdrożenie backupu Key/Value lub wyłączenie backupu całkowicie.

Twój BackupAgent musi implementować abstrakcyjne metody onBackup() i onRestore(), które są używane do backupu key-value. Jeśli jednak nie chcesz wykonywać kopii zapasowych wartości kluczowych, możesz po prostu pozostawić implementację tych metod pustą.

Więcej informacji znajdziesz w rozdziale Rozszerzanie BackupAgent.