لمحة عن قواعد الاحتفاظ بالبيانات

عند تفعيل تحسين التطبيق باستخدام الإعدادات التلقائية، تُجري الأداة R8 عمليات تحسين شاملة لزيادة مزايا الأداء إلى أقصى حدّ. تُجري الأداة R8 تعديلات كبيرة على الرمز البرمجي، بما في ذلك إعادة تسمية الفئات والحقول والطرق ونقلها وإزالتها. إذا لاحظت أنّ هذه التعديلات تتسبّب في حدوث أخطاء، عليك تحديد أجزاء الرمز البرمجي التي يجب ألا تعدّلها الأداة R8 من خلال تعريفها في قواعد الاحتفاظ.

السيناريوهات الشائعة التي تتطلّب قواعد الاحتفاظ

تحدّد الأداة R8 جميع الاستدعاءات المباشرة في الرمز البرمجي وتحتفظ بها. ومع ذلك، لا يمكن للأداة R8 رصد استخدامات الرمز البرمجي غير المباشرة، ما قد يؤدي إلى إزالة الرمز البرمجي الذي يحتاجه تطبيقك، ما يتسبّب في حدوث أعطال. استخدِم قواعد الاحتفاظ لإخبار الأداة R8 بالاحتفاظ بهذا الرمز البرمجي المستخدَم بشكل غير مباشر. في ما يلي بعض الحالات الشائعة التي من المحتمل أن تحتاج فيها إلى قواعد الاحتفاظ:

• الرمز البرمجي الذي يتم الوصول إليه من خلال الانعكاس: لا يمكن للأداة R8 تحديد متى يتم الوصول إلى الفئات أو الحقول أو الطرق باستخدام الانعكاس. على سبيل المثال، لا يمكن للأداة R8 تحديد طريقة يتم البحث عنها حسب اسمها باستخدام Class.getDeclaredMethod() أو تعليق توضيحي يتم استرداده باستخدام Class.getAnnotation(). في هذه الحالات، قد تعيد الأداة R8 تسمية هذه الطرق والتعليقات التوضيحية أو تزيلها بالكامل، ما يؤدي إلى ظهور ClassNotFoundException أو NoSuchMethodException في وقت التشغيل.
• الرمز البرمجي الذي يتم استدعاؤه من واجهة Java Native Interface (JNI): عندما يستدعي رمز برمجي أصلي (C أو C++) طريقة Java أو Kotlin، أو عندما يستدعي رمز برمجي Java أو Kotlin رمز C++ باستخدام JNI، يستند الاستدعاء إلى بحث ديناميكي عن اسم الطريقة باستخدام سلسلة. لا يمكن للأداة R8 رصد طلب الإجراء المستند إلى سلسلة ديناميكية، لذا قد تؤدي عمليات التحسين التي تُجريها إلى إتلاف الرمز البرمجي.

هذه القائمة ليست شاملة للسيناريوهات التي تتطلّب قواعد الاحتفاظ، ولكنها تشمل معظم الحالات التي قد تحتاج فيها إلى قواعد الاحتفاظ.

إذا كان الرمز البرمجي الخاص بك يستخدم الانعكاس أو يتم استدعاؤه من JNI، يمكنك إضافة تعليقات توضيحية إلى هذا الرمز البرمجي باستخدام تعليقات Jetpack التوضيحية للاحتفاظ بدلاً من كتابة قواعد الاحتفاظ يدويًا. ينشئ المكوّن الإضافي لنظام Gradle قواعد الاحتفاظ من التعليقات التوضيحية في وقت الإنشاء.

كيفية إضافة قواعد الاحتفاظ إلى تطبيقك

تعتمد إعدادات قواعد الاحتفاظ على إصدار المكوّن الإضافي لنظام Gradle المتوافق مع Android‏ (AGP) الذي تستخدمه.

تحتوي التطبيقات الأكبر حجمًا عادةً على رمز برمجي في وحدات مكتبة متعدّدة. في مثل هذه الحالات، من الأفضل غالبًا وضع قواعد الاحتفاظ بجانب الرمز البرمجي الذي تنطبق عليه ضمن وحدة المكتبة المحدّدة. يكمن الاختلاف الأساسي في الحفاظ على قواعد الاحتفاظ بالمكتبات في كيفية تعريف هذه القواعد ضمن ملف وحدة المكتبة build.gradle.kts (أو build.gradle) الخاص بها. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة تحسين الأداء لمؤلّفي المكتبات.

بالنسبة إلى الإصدارات 9.3 والإصدارات الأحدث من المكوّن الإضافي لنظام Gradle المتوافق مع Android‏ (AGP)

أضِف قواعدك إلى ملف باللاحقة .keep في الـ src/<variant>/keepRules دليل. على سبيل المثال، src/main/keepRules/custom-rules.keep. يُرجى العِلم أنّ استخدام لغة DSL المعدَّلة للإصدار 9.3 والإصدارات الأحدث من المكوّن الإضافي لنظام Gradle المتوافق مع Android‏ (AGP) يتيح تحسين الرمز البرمجي والموارد، ولا يتطلّب منك تحديد ملف قواعد الاحتفاظ التلقائي لنظام Android (proguard-android-optimize.txt) بشكل صريح، لأنّه مضمّن تلقائيًا، ما لم يتم استبعاده بشكل صريح.

android {
    buildTypes {
        release {
            optimization {
                enable = true // Enables code and resource optimizations.
            }
        }
    }
}

android {
    buildTypes {
        release {
            optimization {
                enable = true // Enables code and resource optimizations.
            }
        }
    }
}

استبعاد قواعد الاحتفاظ التلقائية لنظام Android (إعدادات متقدّمة)

يوفّر المكوّن الإضافي لنظام Gradle المتوافق مع Android‏ (AGP) مجموعة من القواعد التلقائية لنظام Android الأساسي. لاستبعاد هذه القواعد من إعدادات مشروعك وإدارة جميع قواعد الاحتفاظ بنفسك، اضبط optimization.keepRules.includeDefault على false.

android {
    buildTypes {
        release {
            optimization {
                enable = true // Enables code and resource optimizations.
                keepRules {
                    includeDefault = false // The file with optimization
                    // rules for the Android platform is included by
                    // default. To omit this file, set this option to false.
                }
            }
        }
    }
}

android {
    buildTypes {
        release {
            optimization {
                enable = true // Enables code and resource optimizations.
                keepRules {
                    includeDefault = false // The file with optimization
                    // rules for the Android platform is included by
                    // default. To omit this file, set this option to false.
                }
            }
        }
    }
}

لغة DSL القديمة للإصدارات الأقدم من 9.3 من المكوّن الإضافي لنظام Gradle المتوافق مع Android‏ (AGP)

أضِف قواعدك إلى ملف proguard-rules.pro موجود في دليل جذر وحدة التطبيق، وقد يكون الملف موجودًا من قبل، ولكن إذا لم يكن كذلك، أنشئه. لتطبيق القواعد في الملف، عليك تعريف الملف في ملف على مستوى الوحدة build.gradle.kts (أو build.gradle).

يتضمّن ملف الإصدار أيضًا بشكل تلقائي الملف proguard-android-optimize.txt. يتضمّن هذا الملف قواعد مطلوبة لمعظم مشاريع Android، لذا ننصحك بتركه في ملف الإصدار. يستند هذا الملف إلى الملف proguard-common.txt ويتشارك معه المحتوى.

android {
    buildTypes {
        release {
            isMinifyEnabled = true
            isShrinkResources = true

            proguardFiles(
                // Default file with default optimization rules.
                getDefaultProguardFile("proguard-android-optimize.txt"),
                ...
            )
        }
    }
}

android {
    buildTypes {
        release {
            minifyEnabled = true
            shrinkResources = true

            // Default file with default optimization rules.
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt')
            ...
        }
    }
}

إضافة قاعدة احتفاظ

عند إضافة قواعد الاحتفاظ، يمكنك تضمين الخيارات العامة بالإضافة إلى تحديد قواعد الاحتفاظ الخاصة بك.

• الخيارات العامة: الخيارات العامة هي توجيهات عامة تؤثر في طريقة عمل الأداة R8 على قاعدة الرموز البرمجية بالكامل. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة الخيارات العامة.

• قواعد الاحتفاظ: يجب تصميم قواعد الاحتفاظ بعناية للتأكّد من تحقيق التوازن المناسب بين زيادة تحسين الرمز البرمجي إلى أقصى حدّ بدون إتلاف تطبيقك عن غير قصد. لمعرفة كيفية كتابة قواعد الاحتفاظ، يُرجى الاطّلاع على مقالة إضافة قواعد الاحتفاظ.

قواعد الاحتفاظ لمؤلّفي المكتبات

بعد التعرّف على الخيارات العامة وبنية قواعد الاحتفاظ، يُرجى الاطّلاع على مقالة تحسين الأداء لمؤلّفي المكتبات لمزيد من التفاصيل.