عند دمج ميزة "عرض المواد في Play"، يمكن لألعاب Unity الوصول إلى حِزم مواد العرض باستخدام Addressables أو AssetBundles. تُعدّ Addressables أحدث حلول عرض مواد العرض وأكثرها فعالية للألعاب التي تم إنشاؤها باستخدام Unity 2019.4 أو إصدار أحدث، بينما توفّر AssetBundles إمكانية استخدام حِزم مواد العرض في Unity 2017.4 و2018.4.
Unity Addressables
يجب أن تستخدم الألعاب التي تم إنشاؤها باستخدام Unity 2019.4 أو إصدار أحدث Addressables لعرض مواد العرض على أجهزة Android. توفّر Unity واجهة برمجة تطبيقات "عرض المواد في Play" (PAD) للتعامل مع حِزم مواد عرض Android باستخدام Addressables. للحصول على معلومات حول استخدام Addressables، يُرجى الاطّلاع على ما يلي:
- حزمة Addressables لنظام التشغيل Android
- دليل PAD لـ Unity
- مستندات مرجعية لواجهة برمجة التطبيقات PAD لـ Unity reference documentation
استخدام ملفات AssetBundle
يمكن للألعاب التي تم إنشاؤها باستخدام Unity 2017.4 و2018.4 استخدام ملفات AssetBundle لعرض مواد العرض على أجهزة Android. تحتوي ملفات Unity AssetBundle على مواد عرض متسلسلة يمكن لمحرك Unity تحميلها أثناء تشغيل التطبيق. هذه الملفات خاصة بمنصّة معيّنة (على سبيل المثال، تم إنشاؤها لنظام التشغيل Android) ويمكن استخدامها مع حِزم مواد العرض. في معظم الحالات، يتم تجميع ملف AssetBundle واحد في حزمة مواد عرض واحدة، وتستخدم الحزمة الاسم نفسه الذي يحمله ملف AssetBundle. إذا أردت المزيد من المرونة في إنشاء حزمة مواد عرض، يمكنك ضبط حزمة مواد العرض باستخدام واجهة برمجة التطبيقات.
أثناء وقت التشغيل، استخدِم فئة عرض المواد في Play for Unity لاسترداد ملف AssetBundle مجمّع في حزمة مواد عرض.
المتطلبات الأساسية
- إعداد بيئة التطوير:
OpenUPM-CLI
إذا كان لديك OpenUPM CLI مثبّتًا، يمكنك تثبيت سجلّ OpenUPM باستخدام الأمر التالي:
openupm add com.google.play.assetdeliveryOpenUPM
افتح إعدادات مدير الحِزم من خلال النقر على خيار قائمة Unity تعديل (Edit) > إعدادات المشروع (Project Settings) > مدير الحِزم (Package Manager).
أضِف OpenUPM كسجلّ ذي نطاق إلى نافذة "مدير الحِزم":
Name: package.openupm.com URL: https://package.openupm.com Scopes: com.google.external-dependency-manager com.google.play.common com.google.play.core com.google.play.assetdelivery com.google.android.appbundleافتح قائمة مدير الحِزم من خلال النقر على خيار قائمة Unity نافذة (Window) > مدير الحِزم (Package Manager).
اضبط القائمة المنسدلة لنطاق المدير على سجلّاتي (My Registries).
اختَر حزمة مكوّن Google Play Integrity الإضافي لـ Unity من قائمة الحِزم وانقر على تثبيت (Install).
الاستيراد من GitHub
نزِّل أحدث
.unitypackageإصدار من GitHub.استورِد ملف
.unitypackageمن خلال النقر على خيار قائمة Unity مواد العرض (Assets) > استيراد حزمة (Import package) > حزمة مخصّصة (Custom Package) واستيراد جميع العناصر.
ضبط ملفات AssetBundle باستخدام واجهة المستخدم
اضبط كل ملف AssetBundle في حزمة مواد عرض:
- انقر على Google > مجموعة حزمات تطبيق Android > إعدادات عرض المواد.
- لاختيار المجلدات التي تحتوي مباشرةً على ملفات AssetBundle، انقر على إضافة مجلد (Add Folder).

لكل حزمة، غيِّر وضع العرض (Delivery Mode) إلى وقت التثبيت (Install Time) أو التنزيل السريع (Fast Follow) أو عند الطلب (On Demand). أصلِح أي أخطاء أو التبعيات وأغلِق النافذة.

انقر على Google > إنشاء مجموعة حزمات تطبيق Android لإنشاء حزمة التطبيق.
(اختياري) اضبط حزمة التطبيق لتتوافق مع تنسيقات ضغط مواد العرض المختلفة.
ضبط حِزم مواد العرض باستخدام واجهة برمجة التطبيقات
يمكنك ضبط عرض مواد العرض من خلال نصوص المحرّر البرمجية التي يمكن تشغيلها كجزء من نظام إنشاء آلي.
استخدِم فئة
AssetPackConfig
لتحديد مواد العرض التي سيتم تضمينها في إنشاء مجموعة حزمات تطبيق Android، بالإضافة
إلى وضع عرض مواد العرض. لا تحتاج حِزم مواد العرض هذه إلى احتواء ملف AssetBundle.
public void ConfigureAssetPacks { // Creates an AssetPackConfig with a single asset pack, named // examplePackName, containing all the files in path/to/exampleFolder. var assetPackConfig = new AssetPackConfig(); assetPackConfig.AddAssetsFolder("examplePackName", "path/to/exampleFolder", AssetPackDeliveryMode.OnDemand); // Configures the build system to use the newly created assetPackConfig when // calling Google > Build and Run or Google > Build Android App Bundle. AssetPackConfigSerializer.SaveConfig(assetPackConfig); // Alternatively, use BundleTool.BuildBundle to build an App Bundle from script. BuildBundle(new buildPlayerOptions(), assetPackConfig); }
يمكنك أيضًا استخدام طريقة
BuildBundle
الثابتة في فئة Bundletool لإنشاء مجموعة حزمات تطبيق Android باستخدام حِزم مواد
العرض، مع توفير
BuildPlayerOptions
و
AssetPackConfig.
للحصول على برنامج تعليمي إرشادي، يُرجى الاطّلاع على الـ درس تطبيقي حول استخدام ميزة "عرض المواد في Play" في ألعاب Unity.
التكامل مع واجهة برمجة التطبيقات Play Asset Delivery Unity API
توفر واجهة برمجة التطبيقات Play Asset Delivery Unity API وظيفة طلب حِزم مواد العرض وإدارة عمليات التنزيل و الوصول إلى مواد العرض. احرِص على إضافة مكوّن Unity الإضافي إلى مشروعك أولاً.
تعتمد الدوال التي تستخدمها في واجهة برمجة التطبيقات على طريقة إنشاء حِزم مواد العرض.
تكون واجهة برمجة التطبيقات مشابهة بغض النظر عن نوع عرض حزمة مواد العرض التي تريد الوصول إليها. يتم عرض هذه الخطوات في مخطط التدفق التالي.
الشكل 1: مخطط تدفق للوصول إلى حِزم مواد العرض
استرداد حزمة مواد عرض
استورِد مكتبة
عرض المواد في Play
واستخدِم طريقة
RetrieveAssetPackAsync()
لتنزيل حزمة مواد عرض إذا لم يكن أحدث إصدار من الحزمة متاحًا على القرص.
using Google.Play.AssetDelivery; // After download, the assets and/or AssetBundles contained in the asset pack // are not loaded into memory. PlayAssetPackRequest request = PlayAssetDelivery.RetrieveAssetPackAsync(assetPackName);
العرض في وقت التثبيت
تتوفّر حزمة مواد العرض التي تم ضبطها على install-time على الفور عند تشغيل التطبيق، ولكن عليك تحميل مواد العرض الخاصة بها في الذاكرة. اطّلِع على
تحميل مواد العرض في الذاكرة.
التنزيل فور اكتمال التثبيت والعرض عند الطلب
تنطبق هذه الأقسام على حِزم مواد العرض fast-follow وon-demand.
التحقّق من الحالة
يتم تخزين كل حزمة مواد عرض في مجلد منفصل في وحدة التخزين الداخلية للتطبيق.
استخدِم الـ
isDone()
لتحديد ما إذا تم تنزيل حزمة مواد عرض من قبل وأصبحت
متاحة، أو إذا حدث خطأ.
مراقبة عملية التنزيل
استخدِم عنصر
PlayAssetPackRequest
للاطّلاع على
حالة
الطلب:
// Download progress of request, between 0.0f and 1.0f. The value will always be // 1.0 for assets delivered as install-time. // NOTE: A value of 1.0 does not mean that the request has completed, only that // the DOWNLOADING stage is finished. float progress = request.DownloadProgress; // Returns the status of the retrieval request. // If the request completed successfully, this value should be AssetDeliveryStatus.Available. // If an error occurred, this value should be AssetDeliveryStatus.Failed. AssetDelivery status = request.Status; switch(status) { case AssetDeliveryStatus.Pending: // Asset pack download is pending - N/A for install-time assets. case AssetDeliveryStatus.Retrieving: // Asset pack is being downloaded and transferred to app storage. // N/A for install-time assets. case AssetDeliveryStatus.Available: // Asset pack is downloaded on disk but NOT loaded into memory. // For PlayAssetPackRequest(), this indicates that the request is complete. case AssetDeliveryStatus.Failed: // Asset pack retrieval failed. case AssetDeliveryStatus.WaitingForWifi: // Asset pack retrieval paused until either the device connects via Wi-Fi, // or the user accepts the PlayAssetDelivery.ShowConfirmationDialog dialog. case AssetDeliveryStatus.RequiresUserConfirmation: // Asset pack retrieval paused until the user accepts the // PlayAssetDelivery.ShowConfirmationDialog dialog. default: break; } // Returns true if status is AssetDeliveryStatus.Available or AssetDeliveryStatus.Failed. bool done = request.IsDone; // If AssetDeliveryStatus.Failed, find more info about the error. AssetDeliveryErrorCode error = request.Error;
عمليات التنزيل الكبيرة
يمكن تنزيل حِزم مواد العرض التي يزيد حجمها عن 200 ميغابايت تلقائيًا، ولكن فقط إذا كان الجهاز متصلاً بشبكة Wi-Fi. إذا لم يكن المستخدم متصلاً بشبكة Wi-Fi، يتم ضبط PlayAssetPackRequest
الحالة على
AssetDeliveryStatus.WaitingForWifi
ويتم إيقاف عملية التنزيل مؤقتًا. في هذه الحالة، يمكنك إما الانتظار إلى أن يتصل الجهاز بشبكة Wi-Fi، ما يؤدي إلى استئناف عملية التنزيل، أو مطالبة المستخدم بالموافقة على تنزيل الحزمة عبر اتصال شبكة الجوّال.
موافقة المستخدم مطلوبة
إذا كانت حالة الحزمة هي AssetDeliveryStatus.RequiresUserConfirmation، لن تكتمل عملية التنزيل إلى أن يقبل المستخدم مربّع الحوار الذي يظهر باستخدام PlayAssetDelivery.ShowConfirmationDialog(). يمكن أن تحدث هذه الحالة إذا لم يتعرّف Play على التطبيق. يُرجى العِلم أنّ استدعاء PlayAssetDelivery.ShowConfirmationDialog() في هذه الحالة يؤدي إلى تعديل التطبيق. بعد التعديل، اطلب مواد العرض مرة أخرى.
if(request.Status == AssetDeliveryStatus.RequiresUserConfirmation || request.Status == AssetDeliveryStatus.WaitingForWifi) { var userConfirmationOperation = PlayAssetDelivery.ShowConfirmationDialog(); yield return userConfirmationOperation; switch(userConfirmationOperation.GetResult()) { case ConfirmationDialogResult.Unknown: // userConfirmationOperation finished with an error. Something went // wrong when displaying the prompt to the user, and they weren't // able to interact with the dialog. case ConfirmationDialogResult.Accepted: // User accepted the confirmation dialog--an update will start. case ConfirmationDialogResult.Declined: // User canceled or declined the dialog. It can be shown again. default: break; } }
إلغاء طلب (عند الطلب فقط)
إذا كنت بحاجة إلى إلغاء الطلب قبل تنزيل حِزم مواد العرض، استخدِم
طريقة
AttemptCancel()
في عنصر PlayAssetPackRequest:
// Will only attempt if the status is Pending, Retrieving, or Available; otherwise // it will be a no-op. request.AttemptCancel(); // Check to see if the request was successful by checking if the error code is Canceled. if(request.Error == AssetDeliveryErrorCode.Canceled) { // Request was successfully canceled. }
تحميل مواد العرض في الذاكرة
بعد اكتمال الطلب، استخدِم إحدى هاتَين الدالتَين لتحميل مواد العرض في الذاكرة:
- استخدِم
PlayAssetPackRequest.GetAssetLocation()للحصول على عنصرAssetLocation. يوفر هذا العنصر مسار مادة العرض والإزاحة والحجم حتى يمكن تحميلها من القرص. - إذا كانت مادة العرض ملف AssetBundle، يمكنك استخدام طريقة الاختصار
PlayAssetPackRequest.LoadAssetBundleAsync(assetPath). يجب أن يتطابق مسار مادة العرض الذي تقدّمه مع مسار ملف AssetBundle من داخل حزمة مواد العرض. سيؤدي ذلك إلى إرجاع AssetBundleCreateRequest.
طلب حِزم مواد العرض بشكل غير متزامن
في معظم الحالات، عليك استخدام Coroutines لـ طلب حِزم مواد العرض بشكل غير متزامن ومراقبة التقدّم، كما هو موضّح في ما يلي:
private IEnumerator LoadAssetPackCoroutine(string assetPackName) { PlayAssetPackRequest request = PlayAssetDelivery.RetrieveAssetPackAsync(assetPackName); while (!request.IsDone) { if(request.Status == AssetDeliveryStatus.WaitingForWifi) { var userConfirmationOperation = PlayAssetDelivery.ShowConfirmationDialog(); // Wait for confirmation dialog action. yield return userConfirmationOperation; if((userConfirmationOperation.Error != AssetDeliveryErrorCode.NoError) || (userConfirmationOperation.GetResult() != ConfirmationDialogResult.Accepted)) { // The user did not accept the confirmation. Handle as needed. } // Wait for Wi-Fi connection OR confirmation dialog acceptance before moving on. yield return new WaitUntil(() => request.Status != AssetDeliveryStatus.WaitingForWifi); } // Use request.DownloadProgress to track download progress. // Use request.Status to track the status of request. yield return null; } if (request.Error != AssetDeliveryErrorCode.NoError) { // There was an error retrieving the pack. For error codes NetworkError // and InsufficientStorage, you may prompt the user to check their // connection settings or check their storage space, respectively, then // try again. yield return null; } // Request was successful. Load the asset pack into memory. AssetBundleCreateRequest assetBundleCreateRequest = request.LoadAssetBundleAsync(path/to/exampleBundle); yield return assetBundleCreateRequest; AssetBundle assetBundle = assetBundleCreateRequest.assetBundle;
لمزيد من المعلومات حول معالجة الأخطاء، اطّلِع على قائمة رموز الأخطاء.
طُرق واجهة برمجة التطبيقات Play Core API الأخرى
في ما يلي بعض طُرق واجهة برمجة التطبيقات الإضافية التي قد ترغب في استخدامها في تطبيقك.
استرداد حِزم مواد عرض متعددة
لاسترداد حِزم مواد عرض متعددة في آنٍ واحد، استخدِم الدالة التالية:
// assetPackNames is an array of strings corresponding to asset packs. PlayAssetPackBatchRequest batchRequest = PlayAssetDelivery.RetrieveAssetPackBatchAsync(<IListstring> assetPackNames);
يمكنك مراقبة حالات كل طلب من خلال الاطّلاع على Dictionary للحالات:
// Dictionary of AssetPackStates, with the asset pack name as the key. Dictionary<string, PlayAssetPackRequest> requests = batchRequest.Requests; // Returns true if all requests are complete. bool requestComplete = batchRequest.IsDone;
الاطّلاع على حجم التنزيل
يمكنك الاطّلاع على حجم حزمة مواد عرض من خلال إجراء طلب غير متزامن إلى Google Play وضبط طريقة رد الاتصال عند اكتمال العملية:
public IEnumerator GetDownloadSize() { PlayAsyncOperation<long> getSizeOperation = PlayAssetDelivery.GetDownloadSize(assetPackName); yield return getSizeOperation; if(operation.Error != AssetDeliveryErrorCode.NoError) { // Error while retrieving download size. } else { // Download size is given in bytes. long downloadSize = operation.GetResult(); } }
إزالة ملفات AssetBundle
يمكنك إزالة حِزم مواد العرض التي يتم تنزيلها فور اكتمال التثبيت وحِزم مواد العرض التي يتم تنزيلها عند الطلب والتي لم يتم تحميلها حاليًا في الذاكرة. أجرِ الطلب غير المتزامن التالي واضبط طريقة معاودة الاتصال عند اكتماله:
PlayAsyncOperation<string> removeOperation = PlayAssetDelivery.RemoveAssetPack(assetBundleName); removeOperation.Completed += (operation) => { if(operation.Error != AssetDeliveryErrorCode.NoError) { // Error while attempting to remove AssetBundles. } else { // Files were deleted OR files did not exist to begin with. } };
الخطوات التالية
اختبِر عرض مواد العرض محليًا ومن Google Play.