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

عند تفعيل تحسين التطبيق باستخدام الإعدادات التلقائية، ينفّذ 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 التعرّف على استدعاء الطريقة الديناميكية المستندة إلى السلسلة، وبالتالي قد تؤدي عمليات التحسين التي يجريها إلى إيقاف عمل الرمز.

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

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

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

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

            proguardFiles(
                // File with default rules provided by the Android Gradle Plugin
                getDefaultProguardFile("proguard-android-optimize.txt"),

                // File with your custom rules
                "proguard-rules.pro"
            )
           // ...
        }
    }
    // ...
}

android {
    buildTypes {
        release {
            minifyEnabled true
            shrinkResources true

            proguardFiles(
                // File with default rules provided by the Android Gradle Plugin
                getDefaultProguardFile('proguard-android-optimize.txt'),

                // File with your custom rules.
                'proguard-rules.pro'
            )
           // ...
        }
    }
    // ...
}

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

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

إضافة قاعدة الاحتفاظ بالبيانات

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

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

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

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

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