این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

با پشتیبان‌گیری خودکار از اطلاعات کاربر نسخه پشتیبان تهیه کنید

پشتیبان‌گیری خودکار برای برنامه‌ها، به‌طور خودکار از داده‌های کاربر از برنامه‌هایی که روی اندروید ۶.۰ (سطح API ۲۳) یا بالاتر اجرا می‌شوند، پشتیبان‌گیری می‌کند. اندروید داده‌های برنامه را با آپلود کردن آن‌ها در گوگل درایو کاربر، جایی که توسط اعتبارنامه‌های حساب گوگل کاربر محافظت می‌شود، حفظ می‌کند. این پشتیبان‌گیری در دستگاه‌هایی که اندروید ۹ یا بالاتر را اجرا می‌کنند، با استفاده از پین، الگو یا رمز عبور دستگاه، به‌صورت سرتاسری رمزگذاری می‌شود. هر برنامه می‌تواند تا ۲۵ مگابایت داده پشتیبان‌گیری را به هر کاربر برنامه اختصاص دهد. هیچ هزینه‌ای برای ذخیره‌سازی داده‌های پشتیبان‌گیری وجود ندارد. برنامه شما می‌تواند فرآیند پشتیبان‌گیری را سفارشی کند یا با غیرفعال کردن پشتیبان‌گیری، از این فرآیند انصراف دهد.

برای مرور کلی گزینه‌های پشتیبان‌گیری اندروید و راهنمایی در مورد اینکه از کدام داده‌ها پشتیبان‌گیری و بازیابی شود، به مرور کلی پشتیبان‌گیری از داده‌ها مراجعه کنید.

فایل‌هایی که پشتیبان‌گیری می‌شوند

به طور پیش‌فرض، پشتیبان‌گیری خودکار شامل فایل‌هایی در اکثر دایرکتوری‌هایی است که توسط سیستم به برنامه شما اختصاص داده شده است:

فایل‌های تنظیمات اشتراکی
فایل‌هایی که در حافظه داخلی برنامه شما ذخیره می‌شوند و توسط getFilesDir() یا getDir(String, int) قابل دسترسی هستند.
فایل‌های موجود در دایرکتوری که توسط getDatabasePath(String) برگردانده می‌شود، که شامل فایل‌های ایجاد شده با کلاس SQLiteOpenHelper نیز می‌شود.
فایل‌های موجود در حافظه خارجی در دایرکتوری برگردانده شده توسط getExternalFilesDir(String)

پشتیبان‌گیری خودکار، فایل‌های موجود در دایرکتوری‌هایی که توسط getCacheDir() ، getCodeCacheDir() و getNoBackupFilesDir() برگردانده می‌شوند را حذف می‌کند. فایل‌های ذخیره شده در این مکان‌ها فقط به طور موقت مورد نیاز هستند و عمداً از عملیات پشتیبان‌گیری حذف می‌شوند.

شما می‌توانید برنامه خود را طوری پیکربندی کنید که فایل‌های خاصی را شامل شود یا نشود. برای اطلاعات بیشتر، به بخش «فایل‌های شامل شده و حذف شده» مراجعه کنید.

محل پشتیبان گیری

داده‌های پشتیبان در یک پوشه خصوصی در حساب گوگل درایو کاربر ذخیره می‌شوند که به ۲۵ مگابایت برای هر برنامه محدود شده است. داده‌های ذخیره شده جزو سهمیه شخصی گوگل درایو کاربر محسوب نمی‌شوند. فقط جدیدترین نسخه پشتیبان ذخیره می‌شود. هنگام تهیه نسخه پشتیبان، نسخه‌های پشتیبان قبلی حذف می‌شوند. داده‌های پشتیبان توسط کاربر یا سایر برنامه‌های موجود در دستگاه قابل خواندن نیستند.

کاربران می‌توانند فهرستی از برنامه‌هایی که از آنها نسخه پشتیبان تهیه شده است را در برنامه اندروید گوگل درایو مشاهده کنند. در دستگاه‌های اندروید، کاربران می‌توانند این فهرست را در کشوی ناوبری برنامه درایو در قسمت تنظیمات > پشتیبان‌گیری و تنظیم مجدد پیدا کنند.

پشتیبان‌گیری از هر طول عمر راه‌اندازی دستگاه در مجموعه داده‌های جداگانه ذخیره می‌شود، همانطور که در مثال‌های زیر توضیح داده شده است:

اگر کاربر دو دستگاه داشته باشد، برای هر دستگاه یک مجموعه داده پشتیبان وجود دارد.
اگر کاربر دستگاه را به تنظیمات کارخانه برگرداند و سپس آن را با همان حساب کاربری راه‌اندازی کند، نسخه پشتیبان در یک مجموعه داده جدید ذخیره می‌شود. مجموعه داده‌های قدیمی پس از مدتی عدم فعالیت، به‌طور خودکار حذف می‌شوند.

برنامه پشتیبان گیری

پشتیبان‌گیری به طور خودکار زمانی انجام می‌شود که همه شرایط زیر برآورده شده باشد:

کاربر پشتیبان‌گیری را در دستگاه فعال کرده است. در اندروید ۹، این تنظیم در تنظیمات > سیستم > پشتیبان‌گیری قرار دارد.
حداقل ۲۴ ساعت از آخرین پشتیبان‌گیری گذشته باشد.
دستگاه بیکار است.
دستگاه به یک شبکه Wi-Fi متصل باشد (اگر کاربر دستگاه، پشتیبان‌گیری از داده‌های تلفن همراه را انتخاب نکرده باشد).

در عمل، این شرایط تقریباً هر شب اتفاق می‌افتد، اما ممکن است یک دستگاه هرگز پشتیبان‌گیری نکند (مثلاً اگر هرگز به شبکه متصل نشود). برای صرفه‌جویی در پهنای باند شبکه، آپلود فقط در صورتی انجام می‌شود که داده‌های برنامه تغییر کرده باشند.

در طول پشتیبان‌گیری خودکار، سیستم برنامه را خاموش می‌کند تا مطمئن شود که دیگر در سیستم فایل چیزی نمی‌نویسد. به طور پیش‌فرض، سیستم پشتیبان‌گیری برنامه‌هایی را که در پیش‌زمینه اجرا می‌شوند نادیده می‌گیرد تا از تجربه کاربری ضعیف جلوگیری کند. می‌توانید با تنظیم ویژگی android:backupInForeground به true، رفتار پیش‌فرض را لغو کنید.

برای ساده‌سازی آزمایش، اندروید ابزارهایی را در اختیار شما قرار می‌دهد که به شما امکان می‌دهند به صورت دستی از برنامه خود نسخه پشتیبان تهیه کنید. برای اطلاعات بیشتر، به «آزمایش نسخه پشتیبان و بازیابی» مراجعه کنید.

بازیابی برنامه

داده‌ها هر زمان که برنامه نصب شود، چه از فروشگاه Play، چه در حین راه‌اندازی دستگاه (وقتی سیستم برنامه‌های نصب‌شده قبلی را نصب می‌کند) یا با اجرای adb install، بازیابی می‌شوند. عملیات بازیابی پس از نصب APK اما قبل از اینکه برنامه برای راه‌اندازی توسط کاربر در دسترس باشد، انجام می‌شود.

در طول جادوگر راه‌اندازی اولیه دستگاه، فهرستی از مجموعه داده‌های پشتیبان موجود به کاربر نشان داده می‌شود و از او پرسیده می‌شود که داده‌ها را از کدام یک بازیابی کند. هر کدام از مجموعه داده‌های پشتیبان که انتخاب شود، به مجموعه داده‌های اصلی دستگاه تبدیل می‌شود. دستگاه می‌تواند یا از پشتیبان‌های خود یا از مجموعه داده‌های اصلی بازیابی کند. اگر پشتیبان‌هایی از هر دو منبع در دسترس باشند، دستگاه پشتیبان خود را در اولویت قرار می‌دهد. اگر کاربر جادوگر راه‌اندازی دستگاه را طی نکرده باشد، دستگاه فقط می‌تواند از پشتیبان‌های خود بازیابی کند.

برای ساده‌سازی آزمایش، اندروید ابزارهایی را در اختیار شما قرار می‌دهد که به شما امکان می‌دهند بازیابی برنامه خود را به صورت دستی آغاز کنید. برای اطلاعات بیشتر، به «آزمایش پشتیبان‌گیری و بازیابی» مراجعه کنید.

فعال و غیرفعال کردن پشتیبان‌گیری

برنامه‌هایی که اندروید ۶.۰ (سطح API ۲۳) یا بالاتر را هدف قرار می‌دهند، به‌طور خودکار در پشتیبان‌گیری خودکار شرکت می‌کنند. در فایل مانیفست برنامه خود، مقدار بولی android:allowBackup برای فعال یا غیرفعال کردن پشتیبان‌گیری تنظیم کنید. مقدار پیش‌فرض true است، اما توصیه می‌کنیم این ویژگی را به‌طور صریح در مانیفست خود تنظیم کنید، همانطور که در مثال زیر نشان داده شده است:

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

می‌توانید با تنظیم android:allowBackup روی false پشتیبان‌گیری را غیرفعال کنید. اگر برنامه شما می‌تواند وضعیت خود را از طریق مکانیسم دیگری بازسازی کند یا اگر برنامه شما با اطلاعات حساس سروکار دارد، ممکن است بخواهید این کار را انجام دهید.

شامل کردن و حذف کردن فایل‌ها

به طور پیش‌فرض، سیستم تقریباً از تمام داده‌های برنامه پشتیبان تهیه می‌کند. برای اطلاعات بیشتر، به بخش مربوط به فایل‌هایی که پشتیبان‌گیری می‌شوند مراجعه کنید.

شما می‌توانید بر اساس نوع انتقال، کنترل کنید که کدام داده‌ها در پشتیبان‌گیری گنجانده شوند. پشتیبان‌گیری خودکار از پشتیبان‌گیری ابری در گوگل درایو و انتقال مستقیم دستگاه به دستگاه (D2D) پشتیبانی می‌کند. روش‌های پیکربندی بر اساس نسخه اندروید و targetSdkVersion برنامه شما متفاوت است.

برای دستگاه‌هایی که اندروید ۱۱ یا پایین‌تر دارند، به بخش پشتیبان‌گیری کنترلی در اندروید ۱۱ و پایین‌تر مراجعه کنید.
برای دستگاه‌هایی که اندروید ۱۲ یا بالاتر را اجرا می‌کنند، برنامه‌هایی که سطح API 31+ را هدف قرار می‌دهند، از فرمت data-extraction-rules استفاده می‌کنند. برای جزئیات بیشتر به بخش پشتیبان‌گیری کنترلی در اندروید ۱۲ یا بالاتر مراجعه کنید.
فرمت data-extraction-rules همچنین از انتقال بین پلتفرمی (مثلاً به iOS) پشتیبانی می‌کند. این قابلیت از اندروید ۱۶ QPR2 در دسترس است. برای اطلاعات بیشتر به پیکربندی انتقال بین پلتفرمی مراجعه کنید.

کنترل پشتیبان‌گیری در اندروید ۱۱ و پایین‌تر

برای کنترل اینکه کدام فایل‌ها در دستگاه‌های دارای اندروید ۱۱ (سطح API 30) یا پایین‌تر پشتیبان‌گیری شوند، مراحل این بخش را دنبال کنید.

در فایل AndroidManifest.xml خود، ویژگی android:fullBackupContent را به عنصر <application> اضافه کنید، همانطور که در مثال زیر نشان داده شده است. این ویژگی به یک فایل XML اشاره می‌کند که حاوی قوانین پشتیبان‌گیری است.
```
<application ...
 android:fullBackupContent="@xml/backup_rules">
</application>
```
یک فایل XML با نام @xml/ backup_rules در دایرکتوری res/xml/ ایجاد کنید. در این فایل، قوانینی با عناصر <include> و <exclude> اضافه کنید. نمونه زیر از تمام تنظیمات اشتراکی به جز 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>
```

شرایط دستگاه مورد نیاز برای پشتیبان گیری را تعریف کنید

اگر برنامه شما اطلاعات حساسی را در دستگاه ذخیره می‌کند، می‌توانید شرایطی را مشخص کنید که تحت آن داده‌های برنامه شما در نسخه پشتیبان کاربر قرار گیرد. می‌توانید شرایط زیر را در اندروید ۹ (سطح API 28) یا بالاتر اضافه کنید:

clientSideEncryption : نسخه پشتیبان کاربر با یک رمز سمت کلاینت رمزگذاری می‌شود. این نوع رمزگذاری در دستگاه‌هایی که اندروید ۹ یا بالاتر دارند فعال است، البته تا زمانی که کاربر نسخه پشتیبان را در اندروید ۹ یا بالاتر فعال کرده و قفل صفحه (پین، الگو یا رمز عبور) برای دستگاه خود تنظیم کرده باشد.
deviceToDeviceTransfer : کاربر در حال انتقال نسخه پشتیبان خود به دستگاه دیگری است که از انتقال محلی دستگاه به دستگاه پشتیبانی می‌کند (برای مثال، گوگل پیکسل).

اگر دستگاه‌های در حال توسعه خود را به اندروید ۹ ارتقا داده‌اید، باید پس از ارتقا، پشتیبان‌گیری از داده‌ها را غیرفعال و سپس دوباره فعال کنید. دلیل این امر آن است که اندروید پس از اطلاع‌رسانی به کاربران در تنظیمات یا راهنمای راه‌اندازی، پشتیبان‌گیری‌ها را فقط با یک رمز سمت کلاینت رمزگذاری می‌کند.

برای اعلام شرایط شمول، ویژگی requireFlags را روی یک یا چند مقدار انتخابی در عناصر <include> در مجموعه قوانین پشتیبان‌گیری خود تنظیم کنید:

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>

اگر برنامه شما یک سیستم پشتیبان‌گیری با مقدار کلیدی را پیاده‌سازی می‌کند یا اگر خودتان BackupAgent پیاده‌سازی کرده‌اید ، می‌توانید این الزامات شرطی را با انجام یک مقایسه بیتی بین مجموعه پرچم‌های انتقال شیء BackupDataOutput و پرچم‌های FLAG_CLIENT_SIDE_ENCRYPTION_ENABLED یا FLAG_DEVICE_TO_DEVICE_TRANSFER عامل پشتیبان‌گیری سفارشی خود، بر منطق پشتیبان‌گیری خود اعمال کنید.

قطعه کد زیر نمونه‌ای از کاربرد این روش را نشان می‌دهد:

کاتلین

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

جاوا

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

کنترل پشتیبان‌گیری در اندروید ۱۲ یا بالاتر

اگر برنامه شما اندروید ۱۲ (سطح API 31) یا بالاتر را هدف قرار می‌دهد، مراحل این بخش را دنبال کنید تا کنترل کنید که از کدام فایل‌ها در دستگاه‌هایی که اندروید ۱۲ یا بالاتر را اجرا می‌کنند، پشتیبان‌گیری شود.

در فایل AndroidManifest.xml خود، ویژگی android:dataExtractionRules را به عنصر <application> اضافه کنید، همانطور که در مثال زیر نشان داده شده است. این ویژگی به یک فایل XML اشاره می‌کند که حاوی قوانین پشتیبان‌گیری است.
```
<application ...
 android:dataExtractionRules="backup_rules.xml">
</application>
```
یک فایل XML با نام backup_rules .xml در دایرکتوری res/xml/ ایجاد کنید. در این فایل، قوانینی را با عناصر <include> و <exclude> اضافه کنید. نمونه زیر از تمام تنظیمات اشتراکی به جز 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>
```

سینتکس پیکربندی XML

سینتکس XML برای فایل پیکربندی بسته به نسخه اندرویدی که برنامه شما روی آن اجرا می‌شود، متفاوت است.

اندروید ۱۱ یا پایین‌تر

از سینتکس 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>

اندروید ۱۲ یا بالاتر

اگر برنامه شما اندروید ۱۲ (سطح API 31) یا بالاتر را هدف قرار می‌دهد، از سینتکس XML زیر برای فایل پیکربندی که پشتیبان‌گیری برای دستگاه‌های دارای اندروید ۱۲ یا بالاتر را کنترل می‌کند، استفاده کنید.

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

هر بخش از پیکربندی ( <cloud-backup> ، <device-transfer> ، <cross-platform-transfer> ) شامل قوانینی است که فقط برای آن نوع انتقال اعمال می‌شود. این جداسازی به شما امکان می‌دهد، به عنوان مثال، یک فایل یا دایرکتوری را از پشتیبان‌گیری‌های Google Drive مستثنی کنید، در حالی که همچنان آن را در طول انتقال دستگاه به دستگاه (D2D) یا انتقال بین پلتفرمی منتقل می‌کنید. این قابلیت در صورتی مفید است که فایل‌هایی دارید که برای پشتیبان‌گیری در فضای ابری بسیار بزرگ هستند، اما می‌توانند بدون مشکل بین دستگاه‌ها منتقل شوند.

اگر هیچ قانونی برای یک حالت پشتیبان‌گیری خاص وجود نداشته باشد، مثلاً اگر بخش <device-transfer> وجود نداشته باشد، آن حالت برای همه محتوا به جز دایرکتوری‌های no-backup و cache ، همانطور که در بخش فایل‌های پشتیبان‌گیری شده توضیح داده شده است، کاملاً فعال می‌شود.

برنامه شما می‌تواند پرچم disableIfNoEncryptionCapabilities را در بخش <cloud-backup> تنظیم کند تا مطمئن شود که پشتیبان‌گیری فقط در صورتی انجام می‌شود که بتوان آن را رمزگذاری کرد، مانند زمانی که کاربر صفحه قفل دارد. تنظیم این محدودیت، ارسال پشتیبان‌ها به فضای ابری را در صورتی که دستگاه کاربر نتواند از رمزگذاری پشتیبانی کند، متوقف می‌کند، اما از آنجا که انتقال‌های D2D به سرور ارسال نمی‌شوند، حتی در دستگاه‌هایی که از رمزگذاری پشتیبانی نمی‌کنند، به کار خود ادامه می‌دهند.

سینتکس برای شامل کردن و حذف کردن عناصر

درون تگ‌های <full-backup-content> ، <cloud-backup> و <device-transfer> (بسته به نسخه اندروید دستگاه و targetSDKVersion برنامه شما)، می‌توانید عناصر <include> و <exclude> را تعریف کنید:

<include>

یک فایل یا پوشه را برای پشتیبان‌گیری مشخص می‌کند. به‌طور پیش‌فرض، پشتیبان‌گیری خودکار تقریباً تمام فایل‌های برنامه را شامل می‌شود. اگر عنصر <include> را مشخص کنید، سیستم دیگر به‌طور پیش‌فرض هیچ فایلی را شامل نمی‌شود و فقط فایل‌های مشخص‌شده را پشتیبان‌گیری می‌کند. برای شامل کردن چندین فایل، از چندین عنصر <include> استفاده کنید.

در اندروید ۱۱ و پایین‌تر ، این عنصر می‌تواند شامل ویژگی requireFlags نیز باشد که در بخش مربوط به نحوه تعریف الزامات شرطی برای پشتیبان‌گیری ، با جزئیات بیشتری مورد بحث قرار گرفته است.

فایل‌های موجود در دایرکتوری‌هایی که توسط getCacheDir() ، getCodeCacheDir() یا getNoBackupFilesDir() برگردانده می‌شوند، حتی اگر سعی کنید آنها را اضافه کنید، همیشه مستثنی هستند.

<exclude>

یک فایل یا پوشه را برای حذف در هنگام پشتیبان گیری مشخص می‌کند. در اینجا برخی از فایل‌هایی که معمولاً از پشتیبان گیری حذف می‌شوند، آورده شده است:

فایل‌هایی که شناسه‌های مخصوص دستگاه دارند، چه توسط سرور صادر شده باشند و چه در دستگاه تولید شده باشند. برای مثال، پیام‌رسان ابری فایربیس (FCM) هر بار که کاربر برنامه شما را روی دستگاه جدیدی نصب می‌کند، باید یک توکن ثبت‌نام ایجاد کند. اگر توکن ثبت‌نام قدیمی بازیابی شود، برنامه ممکن است رفتار غیرمنتظره‌ای داشته باشد.
فایل‌های مربوط به اشکال‌زدایی برنامه.
فایل‌های بزرگی که باعث می‌شوند حجم پشتیبان‌گیری برنامه از سهمیه ۲۵ مگابایتی فراتر رود.

هر عنصر <include> و <exclude> باید شامل دو ویژگی زیر باشد:

domain

مکان منبع را مشخص می‌کند. مقادیر معتبر برای این ویژگی شامل موارد زیر است:

root : دایرکتوری در سیستم فایل که تمام فایل‌های خصوصی متعلق به این برنامه در آن ذخیره می‌شوند.
file : دایرکتوری‌هایی که توسط getFilesDir() برگردانده می‌شوند.
database : دایرکتوری‌هایی که توسط getDatabasePath() برگردانده می‌شوند. پایگاه‌های داده ایجاد شده با SQLiteOpenHelper در اینجا ذخیره می‌شوند.
sharedpref : دایرکتوری که SharedPreferences در آن ذخیره می‌شود.
external : دایرکتوری که توسط getExternalFilesDir() برگردانده می‌شود.
device_root : مانند root اما برای فضای ذخیره‌سازی محافظت‌شده توسط دستگاه.
device_file : مانند file اما برای ذخیره‌سازی محافظت‌شده توسط دستگاه.
device_database : مانند database اما برای ذخیره‌سازی محافظت‌شده توسط دستگاه.
device_sharedpref : مانند sharedpref اما برای فضای ذخیره‌سازی محافظت‌شده توسط دستگاه.

path

یک فایل یا پوشه را برای اضافه کردن یا حذف کردن در پشتیبان‌گیری مشخص می‌کند. به موارد زیر توجه کنید:

این ویژگی از سینتکس wildcard یا regular expression پشتیبانی نمی‌کند.
شما می‌توانید با استفاده از ./ به دایرکتوری فعلی ارجاع دهید، اما به دلایل امنیتی نمی‌توانید با استفاده از .. به دایرکتوری والد ارجاع دهید.
اگر یک دایرکتوری مشخص کنید، این قانون برای همه فایل‌های موجود در دایرکتوری و زیردایرکتوری‌های بازگشتی اعمال می‌شود.

پیکربندی انتقال‌های بین پلتفرمی

از اندروید ۱۶ QPR2 (سطح API 36.1) به بعد، می‌توانید پشتیبان‌گیری خودکار را برای انتقال داده‌ها به/از دستگاه‌های غیر اندروید پیکربندی کنید. برای انجام این کار، عنصر <cross-platform-transfer> را در پیکربندی <data-extraction-rules> خود اضافه کنید، همانطور که در سینتکس اندروید ۱۲ یا بالاتر نشان داده شده است. شما باید پلتفرم هدف را با استفاده از ویژگی platform مورد نیاز مشخص کنید. تنها مقدار پشتیبانی شده ios است.

در داخل این بخش، می‌توانید از عناصر استاندارد <include> و <exclude> همانطور که در بخش نحو عناصر include و exclude توضیح داده شده است، برای مشخص کردن اینکه کدام داده‌ها منتقل شوند، استفاده کنید.

علاوه بر این، شما باید عنصر <platform-specific-params> را برای کمک به سیستم در تطبیق برنامه شما با برنامه مربوطه در پلتفرم هدف، اضافه کنید. این عنصر دارای ویژگی‌های الزامی زیر است:

bundleId : شناسه بسته برنامه در پلتفرم دیگر (مثلاً شناسه بسته برنامه iOS شما).
teamId : شناسه تیم برنامه در پلتفرم دیگر (مثلاً شناسه تیم برنامه iOS شما).
contentVersion : رشته‌ی نسخه‌ای که شما تعریف می‌کنید و با فرمت داده‌ای که قرار است صادر شود مرتبط است.

ویژگی‌های bundleId و teamId برای کمک به تأیید یکپارچگی داده‌ها و تطبیق مناسب برنامه با برنامه استفاده می‌شوند. آن‌ها تضمین می‌کنند که داده‌ها فقط در طول یک export به برنامه مشخص شده در پلتفرم دیگر منتقل می‌شوند و این برنامه اندروید فقط داده‌ها را از آن برنامه خاص در طول import وارد می‌کند.

برای کنترل دقیق‌تر بر فرآیند تبدیل و انتقال داده‌ها، فراتر از آنچه قوانین XML ارائه می‌دهند، می‌توانید یک BackupAgent سفارشی پیاده‌سازی کنید و از APIهای انتقال چند پلتفرمی (Cross-Platform Transfer APIs) استفاده کنید.

نگاشت فایل برای انتقال‌های iOS

هنگام انتقال فایل‌ها به iOS، domain و path اندروید که در قوانین <include> مشخص می‌کنید، به یک ساختار دایرکتوری خاص نگاشت می‌شود. جدول زیر مسیرهای مقصد در iOS را نسبت به ریشه مقصد انتقال، بر اساس domain اندروید نشان می‌دهد:

`domain` اندروید	مسیر در iOS (نسبت به انتقال روت)
`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/`

برای مثال، فایلی که با <include domain="file" path="my_settings.txt"/> همراه شده باشد، در سمت iOS و در مسیر app/files/my_settings.txt نسبت به ریشه مقصد انتقال، در دسترس خواهد بود.

پیاده‌سازی BackupAgent

برنامه‌هایی که پشتیبان‌گیری خودکار را پیاده‌سازی می‌کنند، نیازی به پیاده‌سازی BackupAgent ندارند. با این حال، می‌توانید به صورت اختیاری یک BackupAgent سفارشی پیاده‌سازی کنید. معمولاً دو دلیل برای انجام این کار وجود دارد:

شما می‌خواهید از رویدادهای پشتیبان‌گیری، مانند onRestoreFinished() و onQuotaExceeded() مطلع شوید. این متدهای فراخوانی حتی اگر برنامه در حال اجرا نباشد، اجرا می‌شوند.
شما نمی‌توانید به راحتی مجموعه فایل‌هایی را که می‌خواهید از آنها نسخه پشتیبان تهیه کنید با قوانین XML بیان کنید. در این موارد نادر، می‌توانید یک BackupAgent پیاده‌سازی کنید که onFullBackup(FullBackupDataOutput) را برای ذخیره آنچه می‌خواهید، لغو کند. برای حفظ پیاده‌سازی پیش‌فرض سیستم، متد مربوطه را در کلاس بالا با super.onFullBackup() فراخوانی کنید.

اگر از BackupAgent استفاده کنید، سیستم به طور پیش‌فرض انتظار دارد که برنامه شما پشتیبان‌گیری و بازیابی کلید-مقدار را انجام دهد. برای استفاده از پشتیبان‌گیری خودکار مبتنی بر فایل، ویژگی android:fullBackupOnly را در مانیفست برنامه خود روی true تنظیم کنید.

در طول عملیات پشتیبان‌گیری و بازیابی خودکار، سیستم برنامه را در حالت محدود اجرا می‌کند تا هم از دسترسی برنامه به فایل‌هایی که ممکن است باعث تداخل شوند جلوگیری کند و هم به برنامه اجازه دهد متدهای فراخوانی را در BackupAgent خود اجرا کند. در این حالت محدود، فعالیت اصلی برنامه به طور خودکار اجرا نمی‌شود، ارائه‌دهندگان محتوای آن مقداردهی اولیه نمی‌شوند و به جای هر زیرکلاسی که در مانیفست برنامه اعلام شده است، از کلاس پایه Application نمونه‌سازی می‌شود.

BackupAgent شما باید متدهای انتزاعی onBackup() و onRestore() را که برای پشتیبان‌گیری کلید-مقدار استفاده می‌شوند، پیاده‌سازی کند. اگر نمی‌خواهید پشتیبان‌گیری کلید-مقدار انجام دهید، می‌توانید پیاده‌سازی این متدها را خالی بگذارید.

برای اطلاعات بیشتر، به Extend BackupAgent مراجعه کنید.

مدیریت انتقال‌های بین پلتفرمی در BackupAgent

با شروع از اندروید ۱۶ QPR2 (سطح API 36.1)، چندین API جدید در BackupAgent برای پشتیبانی بهتر از انتقال داده‌های بین پلتفرمی در دسترس قرار گرفته‌اند.

پرچم حمل و نقل جدید:

FLAG_CROSS_PLATFORM_TRANSFER_IOS : این پرچم به transportFlags ارائه شده به BackupAgent شما اضافه می‌شود.
- در onFullBackup ، این پرچم در صورتی تنظیم می‌شود که عملیات پشتیبان‌گیری فعلی بخشی از صادرات داده به دستگاه iOS باشد.
- در overload جدید onRestoreFile ، اگر داده‌ها از یک دستگاه iOS وارد شوند، این پرچم تنظیم می‌شود.

متد جدید onRestoreFile :

یک سربارگذاری جدید از onRestoreFile معرفی شده است که یک پارامتر FullRestoreDataInput واحد می‌گیرد. این شیء زمینه بیشتری در مورد عملیات بازیابی ارائه می‌دهد:

FullRestoreDataInput.getTransportFlags() : پرچم‌های انتقال را برای عملیات بازیابی فعلی برمی‌گرداند، که می‌تواند شامل FLAG_CROSS_PLATFORM_TRANSFER_IOS باشد.
FullRestoreDataInput.getContentVersion() : رشته نسخه محتوای ارائه شده توسط برنامه منبع در پلتفرم دیگر را در طول انتقال بین پلتفرمی برمی‌گرداند. اگر این مقدار توسط منبع ارائه نشده باشد، یک رشته خالی است.

روش جدید تخمین اندازه:

onEstimateFullBackupBytes() : این متد به شما امکان می‌دهد تا اندازه تخمینی از داده‌هایی که برنامه شما قصد پشتیبان‌گیری از آنها را دارد، ارائه دهید. اگر برنامه شما در طول پشتیبان‌گیری، تبدیل‌های داده‌ای قابل توجهی انجام می‌دهد یا حجم زیادی از داده‌ها را مدیریت می‌کند، پیاده‌سازی آن اکیداً توصیه می‌شود، زیرا می‌تواند با جلوگیری از اجرای خشک پیش‌فرض سیستم، کارایی را بهبود بخشد. برای برنامه‌هایی با پشتیبان‌گیری‌های کوچک و ساده، این متد معمولاً ضروری نیست.

مثال استفاده:

کاتلین

// 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()
}

جاوا

// 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();
}

با پشتیبان‌گیری خودکار از اطلاعات کاربر نسخه پشتیبان تهیه کنید با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

فایل‌هایی که پشتیبان‌گیری می‌شوند

محل پشتیبان گیری

برنامه پشتیبان گیری

بازیابی برنامه

فعال و غیرفعال کردن پشتیبان‌گیری

شامل کردن و حذف کردن فایل‌ها

کنترل پشتیبان‌گیری در اندروید ۱۱ و پایین‌تر

شرایط دستگاه مورد نیاز برای پشتیبان گیری را تعریف کنید

کاتلین

جاوا

کنترل پشتیبان‌گیری در اندروید ۱۲ یا بالاتر

سینتکس پیکربندی XML

اندروید ۱۱ یا پایین‌تر

اندروید ۱۲ یا بالاتر

سینتکس برای شامل کردن و حذف کردن عناصر

پیکربندی انتقال‌های بین پلتفرمی

نگاشت فایل برای انتقال‌های iOS

پیاده‌سازی BackupAgent

مدیریت انتقال‌های بین پلتفرمی در BackupAgent

کاتلین

جاوا

با پشتیبان‌گیری خودکار از اطلاعات کاربر نسخه پشتیبان تهیه کنید