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

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

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

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

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

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

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

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

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

الإصدار 9.3 والإصدارات الأحدث من "المكوّن الإضافي لنظام Gradle المتوافق مع Android"

أضِف القواعد إلى ملف باللاحقة .keep في الدليل src/<variant>/keepRules. على سبيل المثال، src/main/keepRules/custom-rules.keep. يُرجى العِلم أنّ استخدام DSL المعدَّل لإصدار AGP 9.3 والإصدارات الأحدث يتيح تحسين كلّ من الرموز والموارد، ولا يتطلّب منك تحديد ملف قواعد الاحتفاظ التلقائي في 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 الأساسي (إعدادات متقدّمة)

توفّر "مكوّنات Android الإضافية في Gradle" مجموعة من قواعد منصة 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 القديمة لإصدارات "المكوّن الإضافي لنظام Gradle المتوافق مع Android" الأقدم من 9.3

أضِف القواعد إلى ملف 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 على قاعدة الرموز البرمجية بأكملها. لمزيد من المعلومات، يُرجى الاطّلاع على الخيارات العامة.

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

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

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