دمج مواد العرض (Unity)

عند دمج ميزة عرض مواد العرض، يمكن لألعاب Unity الوصول إلى حِزم مواد العرض باستخدام Addressables أو AssetBundles. إنّ عناوين مواد العرض هي الحلّ الأكثر حداثةً وملاءمةً لإرسال مواد العرض للألعاب التي تم إنشاؤها باستخدام الإصدار Unity 2019.4 أو إصدار أحدث، في حين توفّر حِزم مواد العرض إمكانية استخدام حِزم مواد العرض في الإصدارَين Unity 2017.4 و2018.4.

العناصر القابلة للعنوان في Unity

يجب أن تستخدم الألعاب التي تم إنشاؤها باستخدام Unity 2019.4 أو إصدار أحدث Addressables لعرض مواد العرض على Android. توفّر Unity واجهة برمجة تطبيقات Play Asset Delivery (PAD) لمعالجة حِزم مواد عرض Android باستخدام Addressables. للحصول على معلومات عن استخدام عناوين الإعلانات، اطّلِع على ما يلي:

استخدام ملفات AssetBundle

يمكن للألعاب التي تم إنشاؤها باستخدام Unity 2017.4 و2018.4 استخدام ملفات AssetBundle لإرسال مواد العرض على Android. تحتوي ملفات Unity AssetBundle على مواد عرض متسلسلة يمكن أن يحمّلها محرّك Unity أثناء تشغيل التطبيق. هذه الملفات خاصة بالنظام الأساسي (على سبيل المثال، تم إنشاؤها لنظام Android) ويمكن استخدامها مع حِزم مواد العرض. في أغلب الأحيان، يتم تجميع ملف AssetBundle واحد في حزمة مواد عرض واحدة، مع استخدام الحزمة للاسم نفسه المستخدَم في AssetBundle. إذا كنت تريد المزيد من المرونة في إنشاء مجموعة مواد عرض، يمكنك ضبط مجموعة مواد العرض باستخدام واجهة برمجة التطبيقات.

أثناء التشغيل، استخدِم فئة Play Asset Delivery for Unity لاسترداد حِزمة AssetBundle مُجمَّعة في حِزمة مواد عرض.

المتطلّبات الأساسية

  1. إعداد بيئة التطوير:

OpenUPM-CLI

إذا كان لديك واجهة برمجة التطبيقات OpenUPM مثبّتة، يمكنك تثبيت قاعدة بيانات المسجّلين OpenUPM باستخدام الأمر التالي:

openupm add com.google.play.assetdelivery

OpenUPM

  1. افتح إعدادات مدير الحِزم من خلال اختيار خيار قائمة Unity تعديل > إعدادات المشروع > مدير الحِزم.

  2. أضِف 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
    
  3. افتح قائمة مدير الحِزم من خلال اختيار خيار قائمة Unity نافذة > مدير الحِزم.

  4. اضبط القائمة المنسدلة لنطاق المدير لاختيار سجلّاتي.

  5. اختَر حزمة Google Play Integrity plugin for Unity من قائمة الحِزم واضغط على تثبيت.

الاستيراد من GitHub

  1. نزِّل أحدث إصدار من .unitypackage من GitHub.

  2. استورِد ملف .unitypackage من خلال اختيار خيار قائمة Unity التالي: مواد العرض > استيراد حزمة > حزمة مخصّصة واستيراد جميع العناصر.

  1. إنشاء حِزم مواد عرض في Unity

ضبط AssetBundles باستخدام واجهة المستخدم

  1. اضبط كلّ AssetBundle في حزمة مواد عرض:

    1. اختَر Google > حِزم تطبيق Android > إعدادات عرض المواد.
    2. لاختيار المجلدات التي تحتوي مباشرةً على ملفات AssetBundle، انقر على إضافة مجلد.

  2. بالنسبة إلى كل حزمة، غيِّر وضع العرض إلى وقت التثبيت أو العرض الانسيابي السريع أو عند الطلب. أصلِح أي أخطاء أو تبعيات وأغلِق النافذة.

  3. اختَر Google > إنشاء حِزمة تطبيق Android لإنشاء حِزمة التطبيق.

  4. (اختياري) يمكنك ضبط حِزمة تطبيقك لتتوافق مع تنسيقات مختلفة لضغط الملمس.

ضبط حِزم مواد العرض باستخدام واجهة برمجة التطبيقات

يمكنك ضبط عملية إرسال مواد العرض من خلال نصوص برمجية للمحرِّر يمكن تشغيلها كجزء من نظام إنشاء مبرمَج.

استخدِم فئة 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.

الدمج مع واجهة برمجة التطبيقات Unity API في "عرض مواد في Play"

توفّر واجهة برمجة التطبيقات 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.
}

تحميل مواد العرض إلى الذاكرة

بعد اكتمال الطلب، استخدِم إحدى الدوالّ التالية لتحميل مواد العرض إلى الذاكرة:

طلب حِزم مواد العرض بشكل غير متزامن

في معظم الحالات، يجب استخدام الدوالّ المتكرّرة لطلب حزم مواد العرض بشكل غير متزامن ومراقبة مستوى التقدّم، كما هو موضّح في المثال التالي:

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();
    }
}

إزالة AssetBundles

يمكنك إزالة حِزم مواد العرض التي تتضمّن ميزة "المتابعة السريعة" وتلك التي يتم تحميلها عند الطلب والتي لم يتم تحميلها حاليًا إلى الذاكرة. أجرِ المكالمة غير المتزامنة التالية واضبط أسلوب callback عند اكتمالها:

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