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

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

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

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

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

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

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

تهيئة CMake for C/C++ اللازم

لإضافة ملفات العنوان ومكتبة وقت التشغيل الخاصة بواجهة Memory Advice API في مشروعك، افتح ملف CMakeLists.txt الرئيسي الخاص بمشروعك. في جزء المشروع، يكون الملف في التطبيق > src > رئيسي > 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().

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

ابحث عن رمز جافا في مشروعك الذي يحمِّل المكتبات الأصلية. إذا لم تكن موجودة، فقم بإضافتها. من المفترَض أن يبدو الرمز البرمجي مشابهًا لـ 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);

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

يمكنك الاطّلاع على النظرة العامة للاطّلاع على موارد إضافية ومشاكل إعداد التقارير.