بدء استخدام واجهة برمجة التطبيقات 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 إلى كتلة التبعيات. تتضمّن هذه البيانات بيان واجهة برمجة التطبيقات Memory Previews والتبعية في تطبيقك.
```
 dependencies {
     implementation 'androidx.games:games-memory-advice:1.0.0-beta01'
 }
```
حدِّد إصدار NDK داخل المجموعة android:
```
 ndkVersion "23.1.7779620"
```
تأكَّد من اختيار إصدار من NDK متوافق مع Memory Advice API. تتوفّر قائمة بإصدارات NDK المتوافقة على صفحة إصدار Jetpack لألعاب Android.
تعريف علامات إنشاء إضافية لـ CMake. للقيام بذلك، أضف التعليمة البرمجية التالية إلى defaultConfig جزء من مجموعة "android":
```
 externalNativeBuild {
     cmake {
         cppFlags '-std=c++14'
         // c++_shared flavor is the only supported STL type.
         arguments "-DANDROID_STL=c++_shared"
     }
 }
```
فعِّل ميزة الإعداد المسبق. بالنسبة إلى الإصدار 4.1 من Android Gradle Plugin(AGP) 4.1 أو الإصدارات الأحدث، أضِف الرمز التالي إلى حظر واحد (android):
```
 buildFeatures {
    prefab true
 }
```
إذا كنت تستخدم AGP 4.0 أو إصدارًا أقدم، راجع الصفحة المسبقة للحصول على تعليمات الضبط.
احفظ الملف. إذا ظهرت لك الرسالة التالية، انقر على المزامنة الآن. الزر لتحديث مشروعك:
```
  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 > الصفحة الرئيسية > التكلفة لكل نقطة بعد فتح نفِّذ الخطوات التالية:

بالقرب من أعلى الملف، أضِف السطر التالي بعد أي سطر 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().

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

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

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

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