دمج عرض المواد (الأصلي)

1. عدِّل إصدار المكوّن الإضافي لنظام Gradle المتوافق مع Android في ملف build.gradle الخاص بمشروعك إلى 4.0.0 أو إصدار أحدث.

2. في الدليل ذي المستوى الأعلى لمشروعك، أنشِئ دليلاً لحزمة مواد العرض. يُستخدَم اسم هذا الدليل كاسم لحزمة مواد العرض. يجب أن تبدأ أسماء حِزم مواد العرض بحرف، ويمكن أن تحتوي على أحرف وأرقام وشرطات سفلية فقط.

3. في دليل حزمة مواد العرض، أنشِئ ملف build.gradle وأضِف الرمز البرمجي التالي. احرص على تحديد اسم حزمة مواد العرض ونوع تسليم واحد فقط:

   // In the asset pack’s build.gradle file:
   plugins {
       id 'com.android.asset-pack'
   }
   
   assetPack {
       packName = "asset-pack-name" // Directory name for the asset pack
       dynamicDelivery {
           deliveryType = "[ install-time | fast-follow | on-demand ]"
       }
   }

4. في ملف build.gradle الخاص بتطبيق المشروع، أضِف اسم كل حزمة مواد عرض في مشروعك كما هو موضّح أدناه:

   // In the app build.gradle file:
   android {
       ...
       assetPacks = [":asset-pack-name", ":asset-pack2-name"]
   }

5. في ملف settings.gradle الخاص بالمشروع، أدرِج جميع حِزم مواد العرض في مشروعك كما هو موضّح أدناه:

   // In the settings.gradle file:
   include ':app'
   include ':asset-pack-name'
   include ':asset-pack2-name'

6. في دليل حزمة مواد العرض، أنشِئ الدليل الفرعي التالي: src/main/assets.

7. ضَع مواد العرض في الدليل src/main/assets. يمكنك أيضًا إنشاء أدلة فرعية هنا. من المفترض أن تبدو بنية الدليل لتطبيقك الآن على النحو التالي:

   • build.gradle
   • settings.gradle
   • app/
   • asset-pack-name/build.gradle
   • asset-pack-name/src/main/assets/your-asset-directories

8. أنشِئ مجموعة حزمات تطبيق Android باستخدام Gradle. في حزمة التطبيق التي تم إنشاؤها، يتضمّن الدليل ذو المستوى الأعلى الآن ما يلي:

   • asset-pack-name/manifest/AndroidManifest.xml: يضبط معرّف حزمة مواد العرض وطريقة الإرسال
   • asset-pack-name/assets/your-asset-directories:دليل يحتوي على جميع مواد العرض التي يتم تسليمها كجزء من حزمة مواد العرض

   ينشئ Gradle ملف البيان لكل حزمة مواد عرض ويُخرج دليل assets/ لك.

9. (اختياري) اضبط حزمة تطبيقك لتتوافق مع تنسيقات ضغط مختلفة للصور texture compression formats.

التكامل مع مكتبة "عرض المواد في Play"

يمكنك تنفيذ واجهة برمجة التطبيقات هذه وفقًا لنوع تسليم حزمة مواد العرض التي تريد الوصول إليها. تظهر هذه الخطوات في مخطط التدفق التالي.

الشكل 1: مخطط تدفق للوصول إلى حِزم مواد العرض

توفر حزمة تطوير البرامج (SDK) الأصلية في "مكتبة Play الأساسية" ملف رأس C ‏ ‏play/asset_pack.h لطلب حِزم مواد العرض وإدارة عمليات التنزيل و الوصول إلى مواد العرض.

إعداد بيئة التطوير لحزمة تطوير البرامج (SDK) الأصلية في "مكتبة Play الأساسية"

1. عليك القيام بأي مما يلي:

   • ثبِّت الإصدار 4.0 أو إصدارًا أحدث من استوديو Android. استخدِم واجهة مستخدم SDK Manager لتثبيت الإصدار 10.0 من منصة حزمة تطوير البرامج (SDK) لنظام التشغيل Android (المستوى 29 من واجهة برمجة التطبيقات).
   • ثبِّت أدوات سطر الأوامر لحزمة تطوير البرامج (SDK) لنظام التشغيل Android واستخدِم sdkmanager لتثبيت الإصدار 10.0 من منصة حزمة تطوير البرامج (SDK) لنظام التشغيل Android (مستوى واجهة برمجة التطبيقات 29).

2. جهِّز "استوديو Android" للتطوير الأصلي باستخدام SDK Manager لتثبيت أحدث إصدار من CMake وحزمة Android Native Development Kit (NDK). لمزيد من المعلومات حول إنشاء المشاريع الأصلية أو استيرادها، يُرجى الاطّلاع على البدء في استخدام NDK.

3. نزِّل ملف ZIP واستخرج ملفاته بجانب مشروعك.

   رابط التنزيل	الحجم	مجموع SHA-256 الاختباري
   play-core-native-sdk-1.16.0.zip	54.8 ميغابايت	008b8fedc6179a6dc6ccc21af75591afc7036f78f3d5559d844f1b923934fef0

4. عدِّل ملف build.gradle الخاص بتطبيقك كما هو موضّح أدناه:

   أنيق

       // App build.gradle
   
       plugins {
         id 'com.android.application'
       }
   
       // Define a path to the extracted Play Core SDK files.
       // If using a relative path, wrap it with file() since CMake requires absolute paths.
       def playcoreDir = file('../path/to/playcore-native-sdk')
   
       android {
           defaultConfig {
               ...
               externalNativeBuild {
                   cmake {
                       // Define the PLAYCORE_LOCATION directive.
                       arguments "-DANDROID_STL=c++_static",
                                 "-DPLAYCORE_LOCATION=$playcoreDir"
                   }
               }
               ndk {
                   // Skip deprecated ABIs. Only required when using NDK 16 or earlier.
                   abiFilters 'armeabi-v7a', 'arm64-v8a', 'x86', 'x86_64'
               }
           }
           buildTypes {
               release {
                   // Include Play Core Library proguard config files to strip unused code while retaining the Java symbols needed for JNI.
                   proguardFile '$playcoreDir/proguard/common.pgcfg'
                   proguardFile '$playcoreDir/proguard/gms_task.pgcfg'
                   proguardFile '$playcoreDir/proguard/per-feature-proguard-files'
                   ...
               }
               debug {
                   ...
               }
           }
           externalNativeBuild {
               cmake {
                   path 'src/main/CMakeLists.txt'
               }
           }
       }
   
       dependencies {
           // Import these feature-specific AARs for each Google Play Core library.
           implementation 'com.google.android.play:app-update:2.1.0'
           implementation 'com.google.android.play:asset-delivery:2.3.0'
           implementation 'com.google.android.play:integrity:1.6.0'
           implementation 'com.google.android.play:review:2.0.2'
   
           // Import these common dependencies.
           implementation 'com.google.android.gms:play-services-tasks:18.0.2'
           implementation files("$playcoreDir/playcore-native-metadata.jar")
           ...
       }
       

   Kotlin

   // App build.gradle
   
   plugins {
       id("com.android.application")
   }
   
   // Define a path to the extracted Play Core SDK files.
   // If using a relative path, wrap it with file() since CMake requires absolute paths.
   val playcoreDir = file("../path/to/playcore-native-sdk")
   
   android {
       defaultConfig {
           ...
           externalNativeBuild {
               cmake {
                   // Define the PLAYCORE_LOCATION directive.
                   arguments += listOf("-DANDROID_STL=c++_static", "-DPLAYCORE_LOCATION=$playcoreDir")
               }
           }
           ndk {
               // Skip deprecated ABIs. Only required when using NDK 16 or earlier.
               abiFilters.clear()
               abiFilters += listOf("armeabi-v7a", "arm64-v8a", "x86", "x86_64")
           }
       }
       buildTypes {
           release {
               // Include Play Core Library proguard config files to strip unused code while retaining the Java symbols needed for JNI.
               proguardFile("$playcoreDir/proguard/common.pgcfg")
               proguardFile("$playcoreDir/proguard/gms_task.pgcfg")
               proguardFile("$playcoreDir/proguard/per-feature-proguard-files")
               ...
           }
           debug {
               ...
           }
       }
       externalNativeBuild {
           cmake {
               path = "src/main/CMakeLists.txt"
           }
       }
   }
   
   dependencies {
       // Import these feature-specific AARs for each Google Play Core library.
       implementation("com.google.android.play:app-update:2.1.0")
       implementation("com.google.android.play:asset-delivery:2.3.0")
       implementation("com.google.android.play:integrity:1.6.0")
       implementation("com.google.android.play:review:2.0.2")
   
       // Import these common dependencies.
       implementation("com.google.android.gms:play-services-tasks:18.0.2")
       implementation(files("$playcoreDir/playcore-native-metadata.jar"))
       ...
   }

5. عدِّل ملفات CMakeLists.txt الخاصة بتطبيقك كما هو موضّح أدناه:

   cmake_minimum_required(VERSION 3.6)
   
   ...
   
   # Add a static library called “playcore” built with the c++_static STL.
   include(${PLAYCORE_LOCATION}/playcore.cmake)
   add_playcore_static_library()
   
   // In this example “main” is your native code library, i.e. libmain.so.
   add_library(main SHARED
           ...)
   
   target_include_directories(main PRIVATE
           ${PLAYCORE_LOCATION}/include
           ...)
   
   target_link_libraries(main
           android
           playcore
           ...)
   

جمع البيانات

قد تجمع حزمة تطوير البرامج (SDK) الأصلية في "مكتبة Play الأساسية" بيانات متعلقة بالإصدار لتمكين Google من تحسين المنتج، بما في ذلك:

• اسم حزمة التطبيق
• إصدار حزمة التطبيق
• إصدار حزمة تطوير البرامج (SDK) الأصلية في "مكتبة Play الأساسية"

سيتم جمع هذه البيانات عند تحميل حزمة تطبيقك إلى Play Console. لإيقاف عملية جمع البيانات هذه، أزِل عملية استيراد $playcoreDir/playcore-native-metadata.jar في ملف build.gradle.

يُرجى العِلم أنّ عملية جمع البيانات هذه المتعلقة باستخدامك لحزمة تطوير البرامج (SDK) الأصلية في "مكتبة Play الأساسية" واستخدام Google للبيانات التي يتم جمعها منفصلة ومستقلة عن عملية جمع Google لموارد الاعتمادية للمكتبة التي تم الإفصاح عنها في Gradle عند تحميل حزمة تطبيقك إلى Play Console.

التسليم في وقت التثبيت

تتوفّر حِزم مواد العرض التي تم ضبطها على install-time على الفور عند إطلاق التطبيق. استخدِم واجهة برمجة التطبيقات NDK AAssetManager للوصول إلى مواد العرض التي يتم عرضها في هذا الوضع:

#include <android/asset_manager.h>
#include <android_native_app_glue.h>
...
AAssetManager* assetManager = app->activity->assetManager;
AAsset* asset = AAssetManager_open(assetManager, "asset-name", AASSET_MODE_BUFFER);
size_t assetLength = AAsset_getLength(asset);
char* buffer = (char*) malloc(assetLength + 1);
AAsset_read(asset, buffer, assetLength);

التنزيل فور اكتمال التثبيت والتسليم عند الطلب

توضّح الأقسام التالية كيفية إعداد واجهة برمجة التطبيقات، وكيفية الحصول على معلومات حول حِزم مواد العرض قبل تنزيلها، وكيفية استدعاء واجهة برمجة التطبيقات لبدء التنزيل، وكيفية الوصول إلى الحِزم التي تم تنزيلها. تنطبق هذه الأقسام على حِزم مواد العرض fast-follow وon-demand.

إطلاق التطبيق

عليك دائمًا استدعاء AssetPackManager_init() لإعداد واجهة برمجة التطبيقات لحزمة مواد العرض قبل استدعاء أي دالة أخرى. تحقَّق من أي رموز خطأ لحزمة مواد العرض.

#include "play/asset_pack.h"
...
AssetPackErrorCode AssetPackManager_init(JavaVM* jvm, jobject android_context);

احرص أيضًا على استدعاء الدوال التالية في onPause() و onResume() من ANativeActivityCallbacks:

• AssetPackErrorCode AssetPackManager_onPause()
• AssetPackErrorCode AssetPackManager_onResume()

الحصول على معلومات التنزيل حول حِزم مواد العرض

يُطلب من التطبيقات الإفصاح عن حجم التنزيل قبل جلب حزمة مواد العرض. استخدِم الدالة AssetPackManager_requestInfo() لبدء طلب غير متزامن لحجم التنزيل وما إذا كانت الحزمة قيد التنزيل حاليًا. بعد ذلك، استخدِم AssetPackManager_getDownloadState() للاطّلاع على حالة التنزيل (على سبيل المثال، استدعِ هذه الدالة مرة واحدة لكل إطار في حلقة اللعبة). إذا فشل طلب ، تحقَّق من رموز خطأ حزمة مواد العرض.

AssetPackErrorCode AssetPackManager_requestInfo();      // Call once
AssetPackErrorCode AssetPackManager_getDownloadState(); // Call once per frame in your game loop

تعرض الدالة AssetPackManager_getDownloadState() النوع غير الشفاف AssetPackDownloadState كمؤشر ناتج. استخدِم هذا المؤشر لاستدعاء الدوال التالية:

AssetPackDownloadState* state;
AssetPackErrorCode error_code = AssetPackManager_getDownloadState(asset-pack-name, &state);
AssetPackDownloadStatus status = AssetPackDownloadState_getStatus(state);
uint64_t downloadedBytes = AssetPackDownloadState_getBytesDownloaded(state);
uint64_t totalBytes = AssetPackDownloadState_getTotalBytesToDownload(state));
AssetPackDownloadState_destroy(state);

تثبيت

استخدِم AssetPackManager_requestDownload() لبدء تنزيل حزمة مواد عرض للمرة الأولى أو لطلب تحديث حزمة مواد عرض لإكمالها:

AssetPackErrorCode AssetPackManager_requestDownload();  // Call once
AssetPackErrorCode AssetPackManager_getDownloadState(); // Call once per frame in your game loop

تعرض الدالة AssetPackManager_getDownloadState() النوع غير الشفاف AssetPackDownloadState. للحصول على معلومات حول كيفية استخدام هذا النوع، يُرجى الاطّلاع على الحصول على معلومات التنزيل.

حجم أكبر من التنزيلات

إذا كان حجم التنزيل أكبر من 200 ميغابايت ولم يكن المستخدم متصلاً بشبكة Wi-Fi، لن يبدأ التنزيل إلى أن يمنح المستخدم موافقته الصريحة على المتابعة باستخدام اتصال بيانات الجوّال. وبالمثل، إذا كان حجم التنزيل كبيرًا وفقد المستخدم اتصال Wi-Fi، سيتوقف التنزيل مؤقتًا ويجب الحصول على موافقة صريحة للمتابعة باستخدام اتصال بيانات الجوّال. تكون حالة الحزمة المتوقفة مؤقتًا WAITING_FOR_WIFI. لتشغيل مسار واجهة المستخدم لمطالبة المستخدم بالموافقة، استخدِم ما يلي:

• AssetPackManager_showConfirmationDialog()
• AssetPackManager_getShowConfirmationDialogStatus()

تأكيد المستخدم مطلوب

إذا كانت حالة الحزمة REQUIRES_USER_CONFIRMATION، لن يستمر التنزيل إلى أن يقبل المستخدم مربع الحوار الذي يظهر باستخدام AssetPackManager_showConfirmationDialog(). يمكن أن تحدث هذه الحالة إذا لم يتعرّف Play على التطبيق. يُرجى العِلم أنّ استدعاء AssetPackManager_showConfirmationDialog() في هذه الحالة يؤدي إلى تحديث التطبيق. بعد التحديث، اطلب مواد العرض مرة أخرى.

الوصول إلى حِزم مواد العرض

يمكنك الوصول إلى حزمة مواد عرض باستخدام استدعاءات نظام الملفات بعد أن تصل حالة طلب التنزيل إلى COMPLETED. يتم تخزين كل حزمة مواد عرض في دليل منفصل في مساحة التخزين الداخلية للتطبيق. استخدِم AssetPackManager_getAssetPackLocation() للحصول على AssetPackLocation لحزمة مواد العرض المحدّدة. استخدِم AssetPackLocation_getStorageMethod() في هذا الموقع لتحديد طريقة التخزين:

• ASSET_PACK_STORAGE_APK: يتم تثبيت حزمة مواد العرض كملف APK. يُرجى الاطّلاع على التسليم في وقت التثبيت للوصول إلى مواد العرض هذه.
• ASSET_PACK_STORAGE_FILES: Use AssetPackLocation_getAssetsPath() للحصول على مسار ملف إلى الدليل الذي يحتوي على مواد العرض، أو null إذا لم يتم تنزيل مواد العرض. لا تعدِّل الملفات التي تم تنزيلها في مسار الملف هذا.

AssetPackLocation* location;

AssetPackErrorCode error_code = AssetPackManager_getAssetPackLocation(asset-pack-name, &location);

if (error_code == ASSET_PACK_NO_ERROR) {
    AssetPackStorageMethod storage_method = AssetPackLocation_getStorageMethod(location);
    const char* assets_path = AssetPackLocation_getAssetsPath(location);
    AssetPackLocation_destroy(location);
}

بعد تحديد موقع مواد العرض، استخدِم دوال مثل fopen أو ifstream للوصول إلى الملفات.

طُرق أخرى في مكتبة Play الأساسية

في ما يلي بعض طُرق واجهة برمجة التطبيقات الإضافية التي قد ترغب في استخدامها في تطبيقك.

إلغاء الطلب

استخدِم AssetPackManager_cancelDownload() لإلغاء طلب نشط لحزمة مواد عرض. يُرجى العِلم أنّ هذا الطلب هو عملية يتم تنفيذها بأفضل جهد ممكن.

طلب إزالة

استخدِم AssetPackManager_requestRemoval() لجدولة إزالة حزمة مواد عرض.

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

اختبِر ميزة "عرض المواد في Play" محليًا ومن Google Play.