Tworzenie kopii zapasowej danych użytkowników przy użyciu Automatycznej kopii zapasowej

Automatyczna kopia zapasowa aplikacji automatycznie tworzy kopię zapasową danych użytkownika z aplikacji, które są przeznaczone na Androida 6.0 (poziom interfejsu API 23) lub nowszego i działają na tym systemie. Android zachowuje dane aplikacji, przesyłając je na Dysk Google użytkownika, gdzie są chronione przez dane logowania na konto Google użytkownika. Kopia zapasowa jest w pełni szyfrowana na urządzeniach z Androidem 9 lub nowszym przy użyciu kodu PIN, wzoru lub hasła urządzenia. Każda aplikacja może przydzielić do 25 MB danych kopii zapasowej na użytkownika aplikacji. Przechowywanie danych kopii zapasowej jest bezpłatne. Aplikacja może dostosować proces tworzenia kopii zapasowej lub zrezygnować z niego przez wyłączenie kopii zapasowych.

Omówienie opcji tworzenia kopii zapasowych na Androidzie oraz wskazówki dotyczące tego, które dane należy uwzględnić w kopii zapasowej i przywrócić, znajdziesz w omówieniu tworzenia kopii zapasowych danych.

Pliki, których kopie zapasowe są tworzone

Domyślnie automatyczna kopia zapasowa obejmuje pliki w większości katalogów przypisanych do aplikacji przez system:

Automatyczna kopia zapasowa wyklucza pliki w katalogach zwracanych przez getCacheDir(), getCodeCacheDir() i getNoBackupFilesDir(). Pliki zapisane w tych lokalizacjach są potrzebne tylko tymczasowo i są celowo wykluczone z operacji tworzenia kopii zapasowej.

Możesz skonfigurować aplikację tak, aby uwzględniała i wykluczała określone pliki. Więcej informacji znajdziesz w sekcji Uwzględnianie i wykluczanie plików.

Lokalizacja kopii zapasowej

Dane kopii zapasowej są przechowywane w prywatnym folderze na koncie Dysku Google użytkownika, a ich ilość jest ograniczona do 25 MB na aplikację. Zapisane dane nie są wliczane do limitu miejsca na Dysku Google użytkownika. Przechowywana jest tylko najnowsza kopia zapasowa. Po utworzeniu kopii zapasowej poprzednia kopia zapasowa jest usuwana. Użytkownik ani inne aplikacje na urządzeniu nie mogą odczytać danych z kopii zapasowej.

Użytkownicy mogą wyświetlić listę aplikacji, których kopie zapasowe zostały utworzone w aplikacji Dysk Google na Androida. Na urządzeniu z Androidem użytkownicy mogą znaleźć tę listę w panelu nawigacji aplikacji Dysk w sekcji Ustawienia > Kopia zapasowa i resetowanie.

Kopie zapasowe z każdego okresu konfiguracji urządzenia są przechowywane w osobnych zbiorach danych, jak opisano w tych przykładach:

  • Jeśli użytkownik ma 2 urządzenia, dla każdego z nich istnieje zbiór danych kopii zapasowej.

  • Jeśli użytkownik przywróci urządzenie do ustawień fabrycznych, a następnie skonfiguruje je przy użyciu tego samego konta, kopia zapasowa zostanie zapisana w nowym zbiorze danych. Nieaktualne zbiory danych są automatycznie usuwane po okresie braku aktywności.

Harmonogram tworzenia kopii zapasowych

Kopie zapasowe są tworzone automatycznie, gdy spełnione są wszystkie te warunki:

  • Użytkownik włączył kopię zapasową na urządzeniu. W Androidzie 9 to ustawienie znajdziesz w sekcji Ustawienia > System > Kopia zapasowa.
  • Od ostatniej kopii zapasowej minęły co najmniej 24 godziny.
  • Urządzenie jest nieaktywne.
  • Urządzenie jest połączone z siecią Wi-Fi (jeśli użytkownik urządzenia nie wyraził zgody na tworzenie kopii zapasowych przy użyciu mobilnej transmisji danych).

W praktyce te warunki są spełniane mniej więcej co noc, ale może się zdarzyć, że kopia zapasowa urządzenia nigdy nie zostanie utworzona (np. jeśli nigdy nie połączy się ono z siecią). Aby oszczędzać przepustowość sieci, przesyłanie odbywa się tylko wtedy, gdy dane aplikacji uległy zmianie.

Podczas automatycznego tworzenia kopii zapasowej system zamyka aplikację, aby upewnić się, że nie zapisuje ona już danych w systemie plików. Domyślnie system kopii zapasowych ignoruje aplikacje działające na pierwszym planie, aby nie pogarszać wrażeń użytkownika. Aby zastąpić działanie domyślne, ustaw atrybut android:backupInForeground na wartość „true”.

Aby uprościć testowanie, Android zawiera narzędzia, które umożliwiają ręczne rozpoczęcie tworzenia kopii zapasowej aplikacji. Więcej informacji znajdziesz w artykule Testowanie tworzenia i przywracania kopii zapasowej.

Harmonogram przywracania

Dane są przywracane przy każdej instalacji aplikacji, niezależnie od tego, czy jest ona instalowana ze Sklepu Play, podczas konfiguracji urządzenia (gdy system instaluje wcześniej zainstalowane aplikacje) czy przez uruchomienie polecenia adb install. Operacja przywracania następuje po zainstalowaniu pliku APK, ale zanim aplikacja będzie dostępna do uruchomienia przez użytkownika.

Podczas wstępnego kreatora konfiguracji urządzenia użytkownik widzi listę dostępnych zbiorów danych kopii zapasowej i jest pytany, z którego z nich chce przywrócić dane. Wybrany zbiór danych kopii zapasowej staje się nadrzędnym zbiorem danych urządzenia. Urządzenie może przywrócić dane z własnych kopii zapasowych lub ze zbioru danych przodka. Jeśli dostępne są kopie zapasowe z obu źródeł, urządzenie traktuje priorytetowo własną kopię zapasową. Jeśli użytkownik nie przeszedł przez kreator konfiguracji urządzenia, można je przywrócić tylko z jego własnych kopii zapasowych.

Aby uprościć testowanie, Android zawiera narzędzia, które umożliwiają ręczne rozpoczęcie przywracania aplikacji. Więcej informacji znajdziesz w artykule Testowanie tworzenia i przywracania kopii zapasowej.

Włączanie i wyłączanie kopii zapasowej

Aplikacje kierowane na Androida 6.0 (poziom interfejsu API 23) lub nowszego automatycznie korzystają z automatycznej kopii zapasowej. W pliku manifestu aplikacji ustaw wartość logiczną android:allowBackup, aby włączyć lub wyłączyć kopię zapasową. Wartość domyślna to true, ale zalecamy wyraźne ustawienie atrybutu w pliku manifestu, jak w tym przykładzie:

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

Możesz wyłączyć tworzenie kopii zapasowych, ustawiając zasadę android:allowBackup na false. Może to być przydatne, jeśli aplikacja może odtworzyć swój stan za pomocą innego mechanizmu lub jeśli przetwarza informacje poufne.

Uwzględnianie i wykluczanie plików

Domyślnie system tworzy kopie zapasowe prawie wszystkich danych aplikacji. Więcej informacji znajdziesz w sekcji o plikach, których kopie zapasowe są tworzone.

Możesz określić, które dane mają być uwzględniane w kopii zapasowej, w zależności od typu przenoszenia. Automatyczna kopia zapasowa obsługuje kopie zapasowe w chmurze na Dysku Google i bezpośrednie przenoszenie danych między urządzeniami. Metody konfiguracji różnią się w zależności od wersji Androida i targetSdkVersion aplikacji.

Zarządzanie kopią zapasową na Androidzie 11 lub starszym

Wykonaj czynności opisane w tej sekcji, aby określić, które pliki mają być zapisywane w kopii zapasowej na urządzeniach z Androidem 11 (poziom API 30) lub starszym.

  1. W pliku AndroidManifest.xml dodaj atrybut android:fullBackupContent do elementu <application>, jak pokazano w tym przykładzie. Ten atrybut wskazuje plik XML zawierający reguły tworzenia kopii zapasowych.

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

  2. Utwórz plik XML o nazwie @xml/backup_rules w katalogu res/xml/. W tym pliku dodaj reguły z elementami <include> i <exclude>. Ten przykładowy kod tworzy kopię zapasową wszystkich udostępnionych ustawień z wyjątkiem 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>

Określanie warunków urządzenia wymaganych do utworzenia kopii zapasowej

Jeśli aplikacja zapisuje na urządzeniu informacje poufne, możesz określić warunki, na jakich dane aplikacji są uwzględniane w kopii zapasowej użytkownika. W Androidzie 9 (poziom API 28) lub nowszym możesz dodać te warunki:

Jeśli urządzenia deweloperskie zostały uaktualnione do Androida 9, po uaktualnieniu musisz wyłączyć, a następnie ponownie włączyć tworzenie kopii zapasowej danych. Dzieje się tak, ponieważ Android szyfruje kopie zapasowe za pomocą klucza tajnego po stronie klienta dopiero po poinformowaniu użytkowników w Ustawieniach lub kreatorze konfiguracji.

Aby zadeklarować warunki uwzględniania, ustaw atrybut requireFlags na wybraną wartość lub wartości w elementach <include> w zestawie reguł kopii zapasowej:

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 kopii zapasowej klucz-wartość lub jeśli implementujesz BackupAgent samodzielnie, możesz też zastosować te wymagania warunkowe do logiki kopii zapasowej, wykonując porównanie bitowe między zestawem flag transportu obiektu BackupDataOutput a flagami FLAG_CLIENT_SIDE_ENCRYPTION_ENABLED lub FLAG_DEVICE_TO_DEVICE_TRANSFER niestandardowego agenta kopii zapasowej.

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

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.
}

Zarządzanie kopią zapasową na Androidzie 12 lub nowszym

Jeśli Twoja aplikacja jest kierowana na Androida 12 (API na poziomie 31) lub nowszego, wykonaj czynności opisane w tej sekcji, aby kontrolować, które pliki mają być zapisywane w kopii zapasowej na urządzeniach z Androidem 12 lub nowszym.

  1. W pliku AndroidManifest.xml dodaj atrybut android:dataExtractionRules do elementu <application>, jak pokazano w tym przykładzie. Ten atrybut wskazuje plik XML zawierający reguły tworzenia kopii zapasowych.

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

  2. Utwórz plik XML o nazwie backup_rules.xml w katalogu res/xml/. W tym pliku dodaj reguły z elementami <include> i <exclude>. Ten przykładowy kod tworzy kopię zapasową wszystkich udostępnionych ustawień z wyjątkiem 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>

Składnia konfiguracji XML

Składnia XML pliku konfiguracji różni się w zależności od wersji Androida, na której aplikacja jest uruchamiana i na którą jest przeznaczona.

Android 11 lub starszy

W pliku konfiguracji, który kontroluje tworzenie kopii zapasowych na urządzeniach z Androidem 11 lub starszym, użyj tej składni XML.

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

Androida 12 lub nowszego,

Jeśli Twoja aplikacja jest kierowana na Androida 12 (poziom interfejsu API 31) lub nowszego, użyj tej składni XML w pliku konfiguracji, który kontroluje tworzenie kopii zapasowych na urządzeniach z Androidem 12 lub nowszym.

<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>
  <cross-platform-transfer platform="ios">
    ...
    <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"/>
    ...
    <platform-specific-params bundleId="string" teamId="string" contentVersion="string"/>
    ...
  </cross-platform-transfer>
</data-extraction-rules>

Każda sekcja konfiguracji (<cloud-backup>, <device-transfer>, <cross-platform-transfer>) zawiera reguły, które mają zastosowanie tylko do tego typu transferu. Dzięki temu możesz na przykład wykluczyć plik lub katalog z kopii zapasowych na Dysku Google, ale nadal przenosić go podczas przenoszenia danych między urządzeniami lub między platformami. Jest to przydatne, jeśli masz pliki, które są zbyt duże, aby utworzyć ich kopię zapasową w chmurze, ale można je bez problemu przesyłać między urządzeniami.

Jeśli nie ma reguł dla określonego trybu tworzenia kopii zapasowej, np. brakuje sekcji <device-transfer>, ten tryb jest w pełni włączony dla wszystkich treści z wyjątkiem katalogów no-backup i cache, zgodnie z opisem w sekcji Pliki, których kopie zapasowe są tworzone.

Aplikacja może ustawić flagę disableIfNoEncryptionCapabilities w sekcji <cloud-backup>, aby kopia zapasowa była tworzona tylko wtedy, gdy można ją zaszyfrować, np. gdy użytkownik ma ekran blokady. Ustawienie tego ograniczenia uniemożliwia wysyłanie kopii zapasowych do chmury, jeśli urządzenie użytkownika nie obsługuje szyfrowania. Ponieważ jednak transfery D2D nie są wysyłane na serwer, nadal działają nawet na urządzeniach, które nie obsługują szyfrowania.

Składnia elementów uwzględniania i wykluczania

W tagach <full-backup-content>, <cloud-backup> i <device-transfer> (w zależności od wersji Androida na urządzeniu i targetSDKVersion aplikacji) możesz zdefiniować elementy <include> i <exclude>:

<include>

Określa plik lub folder, którego kopię zapasową chcesz utworzyć. Domyślnie automatyczna kopia zapasowa obejmuje prawie wszystkie pliki aplikacji. Jeśli określisz element <include>, system nie będzie już domyślnie uwzględniać żadnych plików i będzie tworzyć kopie zapasowe tylko określonych plików. Aby uwzględnić wiele plików, użyj wielu elementów <include>.

W przypadku Androida 11 i starszych wersji ten element może też zawierać atrybut requireFlags, który został szczegółowo omówiony w sekcji opisującej sposób definiowania wymagań warunkowych dotyczących kopii zapasowej.

Pliki w katalogach zwracane przez getCacheDir(), getCodeCacheDir() lub getNoBackupFilesDir() są zawsze wykluczane, nawet jeśli spróbujesz je uwzględnić.

<exclude>

Określa plik lub folder, który ma zostać wykluczony podczas tworzenia kopii zapasowej. Oto kilka plików, które zwykle są wykluczane z kopii zapasowej:

  • Pliki, które mają identyfikatory urządzeń, wydane przez serwer lub wygenerowane na urządzeniu. Na przykład Komunikacja w chmurze Firebase (FCM) musi wygenerować token rejestracji za każdym razem, gdy użytkownik zainstaluje aplikację na nowym urządzeniu. Jeśli stary token rejestracji zostanie przywrócony, aplikacja może działać nieprawidłowo.

  • Pliki związane z debugowaniem aplikacji.

  • duże pliki, które powodują, że aplikacja przekracza limit 25 MB miejsca na kopię zapasową;

Każdy element <include> i <exclude> musi zawierać te 2 atrybuty:

domain

Określa lokalizację zasobu. Prawidłowe wartości tego atrybutu to:

  • root: katalog w systemie plików, w którym przechowywane są wszystkie prywatne pliki należące do tej aplikacji.
  • file: katalogi zwrócone przez getFilesDir().
  • database: katalogi zwrócone przez getDatabasePath(). Tutaj są przechowywane bazy danych utworzone za pomocą SQLiteOpenHelper.
  • sharedpref: katalog, w którym przechowywane są SharedPreferences.
  • external: katalog zwrócony przez getExternalFilesDir().
  • device_root: podobnie jak root, ale w przypadku pamięci chronionej przez urządzenie.
  • device_file: podobnie jak file, ale w przypadku pamięci chronionej przez urządzenie.
  • device_database: podobnie jak database, ale w przypadku pamięci chronionej przez urządzenie.
  • device_sharedpref: podobnie jak sharedpref, ale w przypadku pamięci chronionej przez urządzenie.
path

Określa plik lub folder, który ma zostać uwzględniony w kopii zapasowej lub z niej wykluczony. Uwaga:

  • Ten atrybut nie obsługuje składni symboli wieloznacznych ani wyrażeń regularnych.
  • Możesz odwołać się do bieżącego katalogu za pomocą ./, ale ze względów bezpieczeństwa nie możesz odwołać się do katalogu nadrzędnego, np. za pomocą ...
  • Jeśli określisz katalog, reguła będzie stosowana do wszystkich plików w katalogu i podkatalogach cyklicznych.

Konfigurowanie przenoszenia między platformami

Od Androida 16 QPR2 (poziom API 36.1) możesz skonfigurować automatyczną kopię zapasową na potrzeby przesyłania danych na urządzenia inne niż z Androidem i z nich. Aby to zrobić, dodaj element <cross-platform-transfer> w konfiguracji <data-extraction-rules>, jak pokazano w składni Androida 12 lub nowszego. Musisz określić platformę docelową za pomocą wymaganego atrybutu platform. Jedyną obsługiwaną wartością jest ios.

W tej sekcji możesz użyć standardowych elementów <include> i <exclude>, jak opisano w artykule Składnia elementów uwzględniania i wykluczania, aby określić, które dane mają zostać przeniesione.

Musisz też uwzględnić element <platform-specific-params>, aby pomóc systemowi dopasować Twoją aplikację do odpowiedniej aplikacji na platformie docelowej. Ten element ma te wymagane atrybuty:

  • bundleId: identyfikator pakietu aplikacji na innej platformie (np. identyfikator pakietu aplikacji na iOS).
  • teamId: identyfikator zespołu aplikacji na innej platformie (np. identyfikator zespołu aplikacji na iOS).
  • contentVersion: zdefiniowany przez Ciebie ciąg znaków wersji powiązany z eksportowanym formatem danych.

Atrybuty bundleId i teamId służą do weryfikacji integralności danych i prawidłowego dopasowania aplikacji. Gwarantują, że podczas eksportu dane są przesyłane do określonej aplikacji na innej platformie, a podczas importu ta aplikacja na Androida importuje dane z tej konkretnej aplikacji.

Aby uzyskać bardziej szczegółową kontrolę nad procesem przekształcania i przesyłania danych, która wykracza poza możliwości reguł XML, możesz wdrożyć niestandardowy interfejs BackupAgent i używać interfejsów API do przenoszenia danych na wielu platformach.

Mapowanie plików na potrzeby przenoszenia danych na iOS

Podczas przenoszenia plików na iOS wartości domain i path Androida określone w regułach <include> są mapowane na określoną strukturę katalogów. W tabeli poniżej znajdziesz ścieżki docelowe na iOS względem katalogu głównego miejsca docelowego przenoszenia na podstawie domain na Androidzie:

Android (domain) Ścieżka na iOS (względem katalogu głównego transferu)
root app/
file app/files/
database app/databases/
sharedpref app/shared_prefs/
external external/files/
device_root device/app/
device_file device/app/files/
device_database device/app/databases/
device_sharedpref device/app/shared_prefs/

Na przykład plik dołączony do <include domain="file" path="my_settings.txt"/> będzie dostępny na urządzeniu z iOS w lokalizacji app/files/my_settings.txt względem katalogu głównego miejsca docelowego przenoszenia.

Implementowanie klasy BackupAgent

Aplikacje, które implementują automatyczną kopię zapasową, nie muszą implementować interfejsu BackupAgent. Możesz jednak opcjonalnie wdrożyć niestandardowy element BackupAgent. Zwykle robi się to z 2 powodów:

  • Chcesz otrzymywać powiadomienia o zdarzeniach związanych z kopiami zapasowymi, takich jak onRestoreFinished() i onQuotaExceeded(). Te metody wywołania zwrotnego są wykonywane, nawet jeśli aplikacja nie jest uruchomiona.

  • Nie możesz łatwo określić zestawu plików, których kopię zapasową chcesz utworzyć, za pomocą reguł XML. W takich rzadkich przypadkach możesz zaimplementować funkcję BackupAgent, która zastępuje funkcję onFullBackup(FullBackupDataOutput), aby przechowywać to, co chcesz. Aby zachować domyślną implementację systemu, wywołaj odpowiednią metodę w klasie nadrzędnej za pomocą super.onFullBackup().

Jeśli wdrożysz BackupAgent, system domyślnie oczekuje, że aplikacja będzie wykonywać tworzenie i przywracanie kopii zapasowej klucz-wartość. Aby zamiast tego używać automatycznej kopii zapasowej opartej na plikach, ustaw atrybut android:fullBackupOnly na true w pliku manifestu aplikacji.

Podczas operacji automatycznego tworzenia i przywracania kopii zapasowej system uruchamia aplikację w trybie ograniczonym, aby uniemożliwić jej dostęp do plików, które mogą powodować konflikty, i umożliwić jej wykonywanie metod wywołania zwrotnego w BackupAgent. W tym trybie ograniczonym główna aktywność aplikacji nie jest uruchamiana automatycznie, jej mechanizmy dostarczania treści nie są inicjowane, a zamiast podklasy zadeklarowanej w pliku manifestu aplikacji tworzona jest instancja klasy podstawowej Application.

Klasa BackupAgent musi implementować metody abstrakcyjne onBackup() i onRestore(), które są używane do tworzenia kopii zapasowych par klucz-wartość. Jeśli nie chcesz tworzyć kopii zapasowej par klucz-wartość, możesz pozostawić implementację tych metod pustą.

Więcej informacji znajdziesz w sekcji Rozszerzanie klasy BackupAgent.

Obsługa przenoszenia danych między platformami w BackupAgent

Od Androida 16 QPR2 (poziom API 36.1) w pakiecie BackupAgent dostępnych jest kilka nowych interfejsów API, które lepiej obsługują przesyłanie danych na wielu platformach.

Nowa flaga transportu:

  • FLAG_CROSS_PLATFORM_TRANSFER_IOS: ta flaga jest dodawana do obiektu transportFlags przekazywanego do BackupAgent.
    • W onFullBackup ta flaga jest ustawiana, jeśli bieżąca operacja tworzenia kopii zapasowej jest częścią eksportu danych na urządzenie z iOS.
    • W nowym przeciążeniu onRestoreFile ta flaga jest ustawiana, jeśli dane są importowane z urządzenia z iOS.

Nowa metoda onRestoreFile:

Wprowadzono nowe przeciążenie metody onRestoreFile, które przyjmuje pojedynczy parametr FullRestoreDataInput. Ten obiekt zawiera więcej informacji o operacji przywracania:

  • FullRestoreDataInput.getTransportFlags(): zwraca flagi transportu dla bieżącej operacji przywracania, które mogą obejmować FLAG_CROSS_PLATFORM_TRANSFER_IOS.
  • FullRestoreDataInput.getContentVersion(): zwraca ciąg znaków wersji treści podany przez aplikację źródłową na innej platformie podczas przenoszenia między platformami. Jeśli źródło nie podaje tej wartości, jest ona pustym ciągiem znaków.

Nowa metoda szacowania rozmiaru:

  • onEstimateFullBackupBytes(): ta metoda pozwala podać szacowany rozmiar danych, których kopię zapasową aplikacja zamierza utworzyć. Zdecydowanie zalecamy wdrożenie tej metody, jeśli aplikacja wykonuje znaczące przekształcenia danych podczas tworzenia kopii zapasowej lub obsługuje dużą ilość danych, ponieważ może to zwiększyć wydajność dzięki uniknięciu domyślnego uruchomienia próbnego systemu. W przypadku aplikacji z małymi, prostymi kopiami zapasowymi ta metoda zwykle nie jest konieczna.

Przykładowe zastosowanie:

Kotlin

// In your custom BackupAgent class

override fun onFullBackup(out: FullBackupDataOutput) {
    // Check if this is a cross-platform export to iOS
    if ((out.transportFlags and FLAG_CROSS_PLATFORM_TRANSFER_IOS) != 0) {
        Log.d(TAG, "onFullBackup for iOS transfer")
        // Your custom export logic here
        // Call fullBackupFile() for files to include
    }
}

override fun onRestoreFile(input: FullRestoreDataInput) {
    if ((input.transportFlags and FLAG_CROSS_PLATFORM_TRANSFER_IOS) != 0) {
        val sourceContentVersion = input.contentVersion
        Log.d(TAG, "onRestoreFile from iOS, content version: $sourceContentVersion")
        // Your custom import logic here, using input.data, input.destination, etc.
    }
}

// Optional: Provide an estimate of the backup size
override fun onEstimateFullBackupBytes(): Long {
    return calculateEstimatedBackupSize()
}

Java

// In your custom BackupAgent class

@Override
public void onFullBackup(FullBackupDataOutput out) throws IOException {
    // Check if this is a cross-platform export to iOS
    if ((out.getTransportFlags() & FLAG_CROSS_PLATFORM_TRANSFER_IOS) != 0) {
        Log.d(TAG, "onFullBackup for iOS transfer");
        // Your custom export logic here
        // Call fullBackupFile() for files to include
    }
}

@Override
public void onRestoreFile(FullRestoreDataInput input) {
    if ((input.getTransportFlags() & FLAG_CROSS_PLATFORM_TRANSFER_IOS) != 0) {
        String sourceContentVersion = input.getContentVersion();
        Log.d(TAG, "onRestoreFile from iOS, content version: " + sourceContentVersion);
        // Your custom import logic here, using input.getData(), input.getDestination(), etc.
    }
}

// Optional: Provide an estimate of the backup size
@Override
public long onEstimateFullBackupBytes() {
    return calculateEstimatedBackupSize();
}