بدء استخدام واجهة برمجة التطبيقات Advice API

يوضّح هذا الدليل كيفية دمج إصدار Jetpack من واجهة برمجة التطبيقات Memory Advice API في تطبيقك باستخدام Android Studio.

يجب أن تستخدم الألعاب إصدار Memory Advice API الذي يُنصح به لبيئة الإصدار. بالنسبة إلى "استوديو Android"، ننصحك باستخدام إصدار Jetpack. للحصول على معلومات حول الإصدارات الخاصة ببيئات إنشاء أخرى، مثل إضافة "تطوير الألعاب على Android" (AGDE)، يُرجى الاطّلاع على عمليات التوزيع.

إضافة المكتبة

يوضّح هذا القسم كيفية إضافة المكتبة إلى مشروعك في "استوديو Android" (مكوّن Android Gradle الإضافي).

إضافة التبعيات

لإضافة المكتبة إلى مشروعك في "استوديو Android"، عليك إكمال الخطوات التالية:

فعِّل مكتبة Android Jetpack على مستوى المشروع gradle.properties)، ويقع الملف عادةً في الدليل الجذري لمشروعك:
```
  android.useAndroidX=true
```
افتح ملف build.gradle على مستوى الوحدة وأضِف ما يلي implementation إلى قسم التبعيات. يؤدي ذلك إلى تعريف عمليات الربط بواجهة برمجة التطبيقات الخاصة بنصائح استخدام الذاكرة في تطبيقك.
```
 dependencies {
     implementation 'androidx.games:games-memory-advice:1.0.0-beta01'
 }
```
حدِّد إصدار NDK داخل الحظر android:
```
 ndkVersion "23.1.7779620"
```
تأكَّد من اختيار إصدار من NDK متوافق مع Memory Advice API. تتوفّر قائمة بإصدارات NDK المتوافقة على صفحة إصدار Android Games Jetpack.

تحديد علامات إنشاء إضافية لـ CMake لإجراء ذلك، أضِف الرمز التالي إلى كتلة defaultConfig التي تقع داخل كتلة android:

 externalNativeBuild {
     cmake {
         cppFlags '-std=c++14'
         // c++_shared flavor is the only supported STL type.
         arguments "-DANDROID_STL=c++_shared"
     }
 }

فعِّل ميزة Prefab. بالنسبة إلى الإصدار 4.1 من "المكوّن الإضافي لنظام Gradle المتوافق مع Android" (AGP) أو الإصدارات الأحدث، أضِف الرمز التالي إلى الحظر android:
```
 buildFeatures {
    prefab true
 }
```
إذا كنت تستخدم الإصدار 4.0 أو إصدارًا أقدم من AGP، يُرجى الاطّلاع على صفحة Prefab للحصول على تعليمات الإعداد.
احفظ الملف. إذا ظهرت لك الرسالة التالية، انقر على الزر مزامنة الآن لتعديل مشروعك:
```
  Gradle files have changed since last project sync. A project sync may be
  necessary for the IDE to work properly.
```

ضبط CMake لإنشاء C/C++

لإضافة ملفات العناوين ومكتبة وقت التشغيل الخاصة بـ Memory Advice API إلى مشروعك، افتح ملف CMakeLists.txt الرئيسي لمشروعك. في لوحة المشروع، يظهر الملف في app > src > main > cpp. بعد فتح الملف، اتّبِع الخطوات التالية:

بالقرب من أعلى الملف، أضِف السطر التالي بعد أي أسطر cmake_minimum_required وproject:
```
 find_package(games-memory-advice REQUIRED CONFIG)
```
في الأمر target_link_libraries، أضِف games-memory-advice::memory_advice. ويجعل ذلك واجهة برمجة التطبيقات Memory Advice API عنصرًا تابعًا لمكتبة مشروعك الأصلية ويضمّنها في حزمة التطبيق النهائية. من المفترض أن يبدو التعديل على النحو التالي:
```
 target_link_libraries(
     your-native-lib

     #link memory advice to the project
     games-memory-advice::memory_advice

     #rest of the dependencies
     #...
 )
```

ضبط ملفات Java

المكتبة الأصلية المضمّنة في Memory Advice API هي libmemory_advice.so. وهي عبارة عن تبعية تجميع لمكتبة C/C++ المشترَكة الخاصة بتطبيقك، ويتم تحميلها تلقائيًا عندما يحمّل تطبيقك مكتبته المشترَكة الخاصة باستخدام الدالة System.loadlibrary().

هذه الخطوة اختيارية.

ابحث عن رمز Java في مشروعك الذي يحمّل المكتبات المجمَّعة من رموز برمجية أصلية. إذا لم يكن متوفّرًا، يمكنك إضافته. يجب أن يبدو الرمز مشابهًا للرمز System.loadLibrary("your-native-lib")، ويكون مضمّنًا في كتلة static.

أضِف System.loadLibrary("memory_advice") ضمن System.loadLibrary("your-native-lib"). من المفترض أن يبدو التعديل مشابهًا لما يلي:

 static {
     System.loadLibrary("your-native-lib");
     // Note: loading libmemory_advice.so is optional.
     System.loadLibrary("memory_advice");
 }

استخدام المكتبة

يوضّح هذا القسم كيفية استخدام المكتبة.

إضافة ملفات العناوين

أدرِج ملف عنوان المكتبة التالي في مشروعك:

    #include <memory_advice/memory_advice.h>

تهيئة المكتبة

عليك إعداد المكتبة مرة واحدة عند بدء تشغيل التطبيق. لإجراء ذلك، أضِف الرمز التالي إلى مشروعك:

    MemoryAdvice_init(env, activity);

المَعلمتان env وactivity هما المتغيّران JNIEnv* وjobject التي يجب أن تكونا متاحتَين في مكتبتك الأصلية. يجب أن يحتوي كل استدعاء JNI لمكتبتك الأصلية على هذه المتغيرات. إذا كنت تستخدم مكتبة GameActivity، احرص على ربط سلسلة التعليمات التي يتم استدعاؤها بـ JavaVM قبل استدعاء الدالة MemoryAdvice_init.

استطلاع حول حالة الذاكرة

يمكنك استرداد حالة الذاكرة لتطبيقك من خلال طلب البيانات من المكتبة بالفاصل الزمني الذي تختاره. استخدِم الدالة MemoryAdvice_getMemoryState عندما تحتاج إلى طلب بيانات من المكتبة:

    MemoryAdvice_MemoryState state = MemoryAdvice_getMemoryState();
    switch (state) {
      case MEMORYADVICE_STATE_OK:
        // The application can safely allocate significant memory.
        break;
      case MEMORYADVICE_STATE_APPROACHING_LIMIT:
        //The application should minimize memory allocation.
        break;
      case MEMORYADVICE_STATE_CRITICAL:
        // The application should free memory as soon as possible,
        // until the memory state changes.
        break;
    }

إعداد مراقب

يمكنك أيضًا إعداد مراقب وتسجيل Memory Advice API، وسيتم استدعاء دالة المراقب عندما تقترب الحالة من الحد أو حالة الذاكرة الحرجة (ولكن ليس للحالة العادية). على سبيل المثال، ينشئ الرمز التالي أداة مراقبة ويطلب إشعارًا من واجهة برمجة التطبيقات Memory Advice API كل ثانيتَين:

    static int USER_DATA;
    constexpr int callback_waittime_ms = 2000;

    void callback(MemoryAdvice_MemoryState state, void* context) {
        switch (state) {
          case MEMORYADVICE_STATE_APPROACHING_LIMIT:
            //The application should minimize memory allocation.
            break;
          case MEMORYADVICE_STATE_CRITICAL:
            // The application should free memory as soon as possible,
            // until the memory state changes.
            break;
        }
    }

    MemoryAdvice_registerWatcher(callback_waittime_ms, callback, &USER_DATA);

الخطوات التالية

يمكنك الاطّلاع على النظرة العامة للحصول على مراجع إضافية والإبلاغ عن المشاكل.

بدء استخدام واجهة برمجة التطبيقات Advice API تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.