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

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

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

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

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

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

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