Mencadangkan data pengguna dengan Auto Backup

Auto Backup untuk Aplikasi otomatis mencadangkan data pengguna dari aplikasi yang menargetkan dan berjalan pada Android 6.0 (API level 23) atau yang lebih tinggi. Android menyimpan data aplikasi dengan menguploadnya ke Google Drive pengguna—yang dilindungi oleh kredensial Akun Google pengguna. Jumlah data dibatasi maksimal 25 MB per pengguna aplikasi Anda. Tidak ada biaya untuk menyimpan data cadangan. Aplikasi Anda dapat menyesuaikan proses pencadangan atau memilih tidak mencadangkan dengan menonaktifkan pencadangan.

Untuk ringkasan opsi pencadangan Android dan panduan terkait data apa saja yang harus dicadangkan dan dipulihkan, lihat ringkasan pencadangan data.

File yang dicadangkan

Secara default, Auto Backup menyertakan file di sebagian besar direktori yang ditetapkan oleh sistem ke aplikasi Anda:

• File preferensi bersama.

• File yang disimpan ke penyimpanan internal aplikasi Anda, yang diakses oleh getFilesDir() atau getDir(String, int).

• File dalam direktori yang ditampilkan oleh getDatabasePath(String), yang juga mencakup file yang dibuat dengan class SQLiteOpenHelper.

• File di penyimpanan eksternal di direktori yang ditampilkan oleh getExternalFilesDir(String).

Auto Backup mengecualikan file di direktori yang ditampilkan oleh getCacheDir(), getCodeCacheDir(), dan getNoBackupFilesDir(). File yang disimpan di lokasi ini hanya diperlukan sementara, dan sengaja dikecualikan dalam operasi pencadangan.

Anda dapat mengonfigurasi aplikasi agar menyertakan dan mengecualikan file tertentu. Untuk informasi selengkapnya tentang hal ini, lihat bagian menyertakan dan mengecualikan file.

Catatan: Android tidak menganggap konfigurasi komponen sebagai data pengguna. Jika aplikasi Anda mengaktifkan atau menonaktifkan komponen tertentu dalam manifesnya saat sedang berjalan, Auto Backup tidak akan otomatis menyimpan dan memulihkan konfigurasi. Untuk mempertahankan status konfigurasi, simpan status di Preferensi Bersama dan pulihkan Preferensi Bersama saat pemulihan.

Lokasi cadangan

Data cadangan disimpan dalam folder pribadi di akun Google Drive pengguna, yang dibatasi hingga 25 MB per aplikasi. Data yang disimpan tidak memengaruhi kuota pribadi Google Drive pengguna. Hanya cadangan terbaru yang disimpan. Saat cadangan dibuat, cadangan sebelumnya (jika ada) akan dihapus. Data cadangan tidak dapat dibaca oleh pengguna atau aplikasi lain di perangkat.

Pengguna dapat melihat daftar aplikasi yang telah dicadangkan di aplikasi Android Google Drive. Di perangkat yang menjalankan Android, pengguna dapat menemukan daftar ini di panel navigasi aplikasi Drive di bagian Setelan > Cadangkan dan reset.

Cadangan dari setiap perangkat-penyiapan-masa pakai disimpan dalam set data terpisah, seperti yang ditunjukkan dalam contoh berikut:

• Jika pengguna memiliki dua perangkat, maka set data cadangan akan dibuat untuk setiap perangkat.

• Jika pengguna mereset perangkat ke setelan pabrik, lalu menyiapkannya dengan akun yang sama, cadangan akan disimpan dalam set data baru. Set data lama otomatis dihapus setelah tidak aktif selama beberapa waktu.

Perhatian: Jika jumlah data melebihi 25 MB, sistem akan memanggil onQuotaExceeded() dan tidak mencadangkan data ke cloud. Secara berkala, sistem akan memeriksa apakah jumlah data selanjutnya akan berukuran di bawah batas 25 MB dan, jika ya, Auto Backup akan dilanjutkan.

Jadwal pencadangan

Backup otomatis terjadi saat semua kondisi berikut terpenuhi:

• Pengguna telah mengaktifkan backup di perangkatnya. Pada Android 9, setelan ini ada di Setelan > Sistem > Pencadangan.
• Minimal 24 jam telah berlalu sejak pencadangan terakhir.
• Perangkat sedang tidak digunakan.
• Perangkat tersambung ke jaringan Wi-Fi (jika pengguna perangkat belum memilih untuk menjalankan pencadangan menggunakan data seluler).

Dalam praktiknya, kondisi ini terjadi kira-kira setiap malam, tetapi mungkin juga perangkat tidak pernah menjalankan pencadangan (misalnya, jika tidak pernah terhubung ke jaringan). Untuk menghemat bandwidth jaringan, upload hanya dilakukan jika data aplikasi telah berubah.

Selama Auto Backup, sistem akan menghentikan aplikasi untuk memastikan bahwa tidak ada operasi tulis yang dilakukan ke sistem file. Secara default, pencadangan ini akan mengabaikan aplikasi yang berjalan di latar depan karena pengguna akan mengetahui jika aplikasi sedang dihentikan. Anda dapat mengganti perilaku default ini dengan menyetel atribut android;backupInForeground ke benar (true).

Untuk menyederhanakan pengujian, Android menyertakan alat yang memungkinkan Anda memulai pencadangan aplikasi secara manual. Untuk informasi lebih lanjut, lihat Menguji pencadangan dan pemulihan.

Jadwal pemulihan

Data dipulihkan setiap kali aplikasi diinstal, dari Play Store, selama penyiapan perangkat (saat sistem menginstal aplikasi yang pernah diinstal sebelumnya), atau dari menjalankan adb install. Operasi pemulihan terjadi setelah APK diinstal, tetapi sebelum aplikasi dapat diluncurkan oleh pengguna.

Selama wizard penyiapan perangkat awal, daftar set data cadangan yang tersedia akan ditampilkan kepada pengguna diikuti pertanyaan dari set data cadangan mana data akan dipulihkan. Set data cadangan yang dipilih akan menjadi set data ancestral untuk perangkat tersebut. Perangkat dapat menjalankan pemulihan dari cadangannya sendiri atau set data ancestral. Perangkat akan memprioritaskan cadangan sendiri jika cadangan dari kedua sumber tersedia. Jika pengguna tidak memanfaatkan wizard penyiapan perangkat, maka perangkat hanya dapat dipulihkan dari cadangannya sendiri.

Untuk menyederhanakan pengujian, Android menyertakan alat yang memungkinkan Anda memulai pemulihan aplikasi secara manual. Untuk informasi lebih lanjut, lihat Menguji pencadangan dan pemulihan.

Mengaktifkan dan menonaktifkan pencadangan

Aplikasi yang menargetkan Android 6.0 (API level 23) atau yang lebih baru otomatis mengimplementasikan Auto Backup. Di file manifes aplikasi, tetapkan nilai boolean android:allowBackup untuk mengaktifkan atau menonaktifkan pencadangan. Nilai defaultnya adalah true, tetapi untuk memperjelas niat Anda, sebaiknya setel atribut secara eksplisit dalam manifes seperti yang ditampilkan di bawah:

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

Anda dapat menonaktifkan pencadangan dengan menyetel android:allowBackup ke false. Anda mungkin perlu menggunakan opsi ini jika aplikasi Anda dapat membuat ulang statusnya melalui mekanisme lain, atau jika aplikasi Anda menangani informasi sensitif yang tidak boleh dicadangkan oleh Android.

Menyertakan dan mengecualikan file

Secara default, sistem mencadangkan hampir semua data aplikasi. Untuk informasi lebih lanjut, lihat File yang dicadangkan. Bagian ini menunjukkan cara menetapkan aturan XML kustom untuk mengontrol file apa saja yang akan dicadangkan.

1. Dalam AndroidManifest.xml, tambahkan atribut android:fullBackupContent ke elemen <application>. Atribut ini mengarah ke file XML yang memuat aturan pencadangan. Contoh:

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

2. Buat file XML bernama my_backup_rules.xml di direktori res/xml/. Di dalam file ini, tambahkan aturan dengan elemen <include> dan <exclude>. Contoh berikut mencadangkan semua preferensi bersama kecuali 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>
   

Sintaksis konfigurasi XML

Sintaksis XML untuk file konfigurasi ditunjukkan di bawah ini:

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

Di dalam tag <full-backup-content>, Anda dapat menentukan elemen <include> dan <exclude>:

• <include> Menentukan file atau folder yang akan dicadangkan. Secara default, Auto Backup menyertakan hampir semua file aplikasi. Jika Anda menentukan elemen <include>, sistem tidak lagi menyertakan semua file secara default dan mencadangkan hanya file yang ditentukan. Untuk menyertakan beberapa file, gunakan beberapa elemen <include>.

  Catatan: File di direktori yang ditampilkan oleh getCacheDir(), getCodeCacheDir(), atau getNoBackupFilesDir() selalu dikecualikan meskipun Anda mencoba menyertakannya.

• <exclude> Menentukan file atau folder yang akan dikecualikan selama proses pencadangan. Berikut ini beberapa file yang biasanya dikecualikan dari pencadangan:

  • File yang menyimpan ID khusus perangkat, baik yang diterbitkan oleh server maupun yang dihasilkan pada perangkat. Misalnya, Firebase Cloud Messaging (FCM) perlu membuat token registrasi setiap kali pengguna menginstal aplikasi Anda di perangkat baru. Jika token registrasi lama dipulihkan, aplikasi mungkin menampilkan perilaku yang tidak terduga.

  • Kredensial akun atau informasi sensitif lainnya. Sebaiknya minta pengguna agar menjalankan autentikasi ulang saat pertama kali meluncurkan aplikasi yang dipulihkan, bukannya mengizinkan penyimpanan informasi tersebut dalam file cadangan.

  • File yang terkait dengan proses debug aplikasi.

  • File besar yang menyebabkan aplikasi melebihi kuota pencadangan 25 MB.

  Catatan: Jika file konfigurasi Anda menentukan kedua elemen, maka cadangan akan memuat apa saja yang diambil oleh elemen <include> dikurangi resource yang disebutkan dalam elemen <exclude>. Dengan kata lain, <exclude> lebih diprioritaskan.

  Setiap elemen harus menyertakan dua atribut berikut:

• domain Menentukan lokasi resource. Nilai yang valid untuk atribut ini meliputi:

  • root Direktori pada sistem file tempat semua file pribadi milik aplikasi ini disimpan.
  • file Direktori yang ditampilkan oleh getFilesDir().
  • database Direktori yang ditampilkan oleh getDatabasePath(). Database yang dibuat dengan SQLiteOpenHelper disimpan di sini.
  • sharedpref Direktori tempat SharedPreferences disimpan.
  • external Direktori yang ditampilkan oleh getExternalFilesDir()
  Catatan: Anda tidak dapat mencadangkan file di luar lokasi ini.

• path Menentukan file atau folder yang akan disertakan atau dikecualikan dari pencadangan. Perhatikan hal berikut:

  • Atribut ini tidak mendukung sintaksis karakter pengganti atau ekspresi reguler.
  • Anda dapat merujuk direktori saat ini menggunakan ./, tetapi Anda tidak dapat merujuk direktori induk .. karena alasan keamanan.
  • Jika Anda menentukan direktori, aturan tersebut akan berlaku pada semua file dalam direktori dan sub-direktori berulang.

Elemen <include> juga dapat berisi atribut requireFlags, yang akan dibahas lebih mendalam pada bagian cara menetapkan persyaratan kondisi untuk pencadangan di bawah ini.

Menetapkan kondisi perangkat yang diperlukan untuk pencadangan

Jika aplikasi Anda menyimpan informasi sensitif pada perangkat, Anda dapat menentukan kondisi yang mengatur penyertaan data aplikasi Anda dalam cadangan pengguna. Anda dapat menambahkan kondisi berikut pada Android 9 (API level 28) atau yang lebih baru:

• clientSideEncryption: Cadangan pengguna dienkripsi dengan rahasia sistem klien. Bentuk enkripsi ini diaktifkan pada perangkat yang menjalankan Android 9 atau yang lebih tinggi dengan syarat pengguna telah mengaktifkan pencadangan pada Android 9 atau yang lebih baru dan telah menetapkan kunci layar (PIN, pola, atau sandi) pada perangkat mereka.
• deviceToDeviceTransfer: Pengguna mentransfer cadangan mereka ke perangkat lain yang mendukung transfer perangkat ke perangkat lokal (misalnya, Google Pixel).

Jika sudah mengupgrade perangkat pengembangan ke Android 9, Anda perlu menonaktifkan lalu mengaktifkan kembali pencadangan data setelah proses upgrade. Hal ini karena Android hanya mengenkripsi cadangan dengan rahasia sistem klien setelah memberi tahu pengguna melalui Setelan atau Wizard Penyiapan.

Untuk mendeklarasikan kondisi penyertaan, tetapkan atribut requireFlags ke nilai yang diinginkan atau nilai pada elemen <include> dalam kumpulan aturan pencadangan:

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>

Catatan: Karena menambahkan persyaratan ke XML mencegah berfungsinya pencadangan pada Android versi sebelumnya, Anda harus menyediakan resource alternatif untuk pencadangan yang digunakan pada perangkat yang menjalankan Android 8.1 (API level 27) atau yang lebih rendah.

Jika aplikasi Anda mengimplementasikan sistem pencadangan nilai kunci, atau jika Anda mengimplementasikan BackupAgent sendiri, Anda juga dapat menerapkan persyaratan kondisional ini ke logika pencadangan dengan menjalankan perbandingan tingkat bit antara kumpulan flag transport BackupDataOutput pada objek dengan flag FLAG_CLIENT_SIDE_ENCRYPTION_ENABLED atau flag FLAG_DEVICE_TO_DEVICE_TRANSFER pada agen cadangan kustom.

Cuplikan kode berikut menunjukkan contoh penggunaan metode ini:

Kotlin

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

Java

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

Mengimplementasikan BackupAgent

Aplikasi yang mengimplementasikan Auto Backup tidak perlu mengimplementasikan BackupAgent. Namun, Anda dapat memilih untuk mengimplementasikan BackupAgent kustom. Biasanya, ada dua alasan untuk menggunakan opsi ini:

• Anda ingin menerima notifikasi peristiwa pencadangan, seperti onRestoreFinished() dan onQuotaExceeded(long, long). Metode callback ini akan tetap dieksekusi meskipun aplikasi tidak sedang berjalan.

• Anda tidak dapat mengekspresikan dengan mudah kumpulan file yang ingin Anda cadangkan dengan aturan XML. Dalam kasus yang jarang terjadi ini, Anda dapat mengimplementasikan BackupAgent sebagai pengganti onFullBackup(FullBackupDataOutput) untuk menyimpan file yang Anda inginkan. Untuk mempertahankan implementasi default sistem, panggil metode terkait pada superclass dengan super.onFullBackup().

Jika Anda mengimplementasikan BackupAgent, secara default sistem mengharapkan aplikasi Anda menjalankan pencadangan dan pemulihan kunci/nilai. Untuk menggunakan Auto Backup berbasis file, tetapkan atribut android:fullBackupOnly ke true dalam manifes aplikasi Anda.

Selama operasi pencadangan dan pemulihan otomatis, sistem meluncurkan aplikasi dalam mode terbatas agar aplikasi tidak mengakses file yang dapat menyebabkan konflik dan untuk mengizinkan aplikasi mengeksekusi metode callback dalam BackupAgent-nya. Dalam mode terbatas ini, aktivitas utama aplikasi tidak otomatis diluncurkan, Penyedia Kontennya tidak diinisialisasi, dan Application class dasar tidak dibuatkan instance sebagai ganti subclass yang dinyatakan dalam manifes aplikasi.

Perhatian: Untuk menghindari error, pastikan bagian aplikasi yang berjalan dalam mode terbatas (kemungkinan besar BackupAgent) tidak mengakses penyedia konten dalam aplikasi yang sama atau mencoba mentransmisikan objek Application. Jika Anda tidak dapat menghindari pola tersebut, sebaiknya implementasikan pencadangan Kunci/Nilai atau menonaktifkan pencadangan sepenuhnya.

BackupAgent Anda harus mengimplementasikan metode abstrak di onBackup() dan onRestore(), yang digunakan untuk pencadangan nilai kunci. Namun, jika tidak ingin menjalankan pencadangan nilai kunci, Anda dapat membiarkan implementasi metode tersebut kosong.

Untuk informasi lebih lanjut, lihat Memperluas BackupAgent.