دعم التحديثات داخل التطبيق (Unity)

يوضّح هذا الدليل كيفية دعم داخل التطبيق التحديثات في تطبيقك باستخدام Unity. تتوفر أدلة منفصلة للحالات التي يستخدم فيها تنفيذك برمجة Kotlin أو لغة برمجة Java واللغة، والحالات التي عملية التنفيذ تستخدم رمز برمجي أصلي (C/C++).

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

يمكنك تنزيل أحدث إصدار من مكوّن Unity الإضافي في التحديث داخل التطبيق من Play من حِزم Google الانسجام:

نظرة عامة على حزمة تطوير البرامج (SDK) في Unity

واجهة برمجة التطبيقات Play In-app Update API هي جزء من Play Core مجموعة حزم تطوير البرامج (SDK). الانسجام يوفر المكون الإضافي AppUpdateManager للتعامل مع الاتصال بين تطبيقك وPlay API. يجب إنشاء مثيل لهذا الصف قبل أن تتمكّن من استخدامه لإدارة التحديثات داخل التطبيق:

AppUpdateManager appUpdateManager = new AppUpdateManager();

التحقّق من توفّر تحديثات

قبل طلب إجراء تحديث، تحقَّق مما إذا كان هناك تحديث متوفّر التطبيق. استخدِم "AppUpdateManager" للبحث عن تحديث في كوروتين:

IEnumerator CheckForUpdate()
{
  PlayAsyncOperation<AppUpdateInfo, AppUpdateErrorCode> appUpdateInfoOperation =
    appUpdateManager.GetAppUpdateInfo();

  // Wait until the asynchronous operation completes.
  yield return appUpdateInfoOperation;

  if (appUpdateInfoOperation.IsSuccessful)
  {
    var appUpdateInfoResult = appUpdateInfoOperation.GetResult();
    // Check AppUpdateInfo's UpdateAvailability, UpdatePriority,
    // IsUpdateTypeAllowed(), etc. and decide whether to ask the user
    // to start an in-app update.
  }
  else
  {
    // Log appUpdateInfoOperation.Error.
  }
}

تم إرجاع AppUpdateInfo على حالة توافر التحديث. إذا كان هناك تحديث داخل التطبيق قيد التقدم، تُبلغ المثيل أيضًا عن حالة التحديث قيد التقدم.

التحقّق من مدى قِدم التحديث

بالإضافة إلى التحقق مما إذا كان هناك تحديث متوفر أم لا، قد تحتاج أيضًا إلى التحقّق من مقدار الوقت المنقضي منذ آخر إشعار للمستخدم بالتحديث من خلال "متجر Play". يمكن أن يساعدك هذا في تحديد ما إذا كان يجب عليك بدء أو تحديث مرن أو تحديث فوري. على سبيل المثال، قد تنتظر بضعة أيام قبل إبلاغ المستخدم بتحديث مرن، وبعد بضعة أيام قبل طلب التحديث الفوري.

استخدام ClientVersionStalenessDays للتحقّق من عدد الأيام التي مرّت منذ أن أصبح التحديث متاحًا على Play المتجر:

var stalenessDays = appUpdateInfoOperation.ClientVersionStalenessDays;

التأكّد من أولوية التحديث

تتيح لك واجهة Google Play Developer API تحديد أولوية كل تحديث. ويسمح هذا الإجراء لتطبيقك بتحديد مدى اقتراح تحديث للمستخدم. على سبيل المثال، يمكنك اتّباع الاستراتيجية التالية لضبط أولوية التعديل:

• تحسينات طفيفة في واجهة المستخدم: تحديث ذو أولوية منخفضة، لا تطلب نهجًا مرنًا أو تحديث فوري.
• تحسينات الأداء: تحديث ذو أولوية متوسطة وطلب صورة تحديث.
• تحديث أمان مهم: تحديث ذو أولوية عالية وطلب إجراء فوري تحديث.

لتحديد الأولوية، يستخدم Google Play قيمة عددية بين 0 و5 مع 0. ويمثل العدد الافتراضي و5 يمثل الأولوية القصوى. لتعيين أولوية تحديث، يمكنك استخدام الحقل inAppUpdatePriority ضمن Edits.tracks.releases في واجهة Google Play Developer API: جميع الإصدارات التي تمت إضافتها مؤخرًا في الإصدار يحظى بالأولوية نفسها التي يحظى بها الإصدار. لا يمكن ضبط الأولوية إلا عندما طرح إصدار جديد ولا يمكن تغييره لاحقًا

تحديد الأولوية باستخدام Google Play Developer API كما هو موضَّح في Play واجهة برمجة تطبيقات المطور ذات الصلة. يجب تحديد أولوية التحديث داخل التطبيق في Edit.tracks المورد الذي تم تمريره في Edit.tracks: update . يوضح المثال التالي إطلاق تطبيق برمز الإصدار 88. وinAppUpdatePriority 5:

{
  "releases": [{
      "versionCodes": ["88"],
      "inAppUpdatePriority": 5,
      "status": "completed"
  }]
}

في رمز التطبيق، يمكنك التحقّق من مستوى الأولوية لتحديث معيّن باستخدام UpdatePriority:

var priority = appUpdateInfoOperation.UpdatePriority;

بدء تحديث

بعد التأكد من توفُّر تحديث، يمكنك طلب التحديث باستخدام AppUpdateManager.StartUpdate() قبل طلب إجراء تحديث، يُرجى التأكد من توفّر تحديث عنصر AppUpdateInfo. يجب عليك أيضًا إنشاء AppUpdateOptions لتهيئة تدفق التحديث.

ينشئ المثال التالي كائن AppUpdateOptions لعملية شراء فورية تدفق التحديث:

// Creates an AppUpdateOptions defining an immediate in-app
// update flow and its parameters.
var appUpdateOptions = AppUpdateOptions.ImmediateAppUpdateOptions();

ينشئ المثال التالي كائن AppUpdateOptions للنموذج المرن تدفق التحديث:

// Creates an AppUpdateOptions defining a flexible in-app
// update flow and its parameters.
var appUpdateOptions = AppUpdateOptions.FlexibleAppUpdateOptions();

يحتوي الكائن AppUpdateOptions أيضًا على حقل AllowAssetPackDeletion. تحدِّد ما إذا كان التعديل مسموحًا له بمحو مادة العرض الحزم في حال انخفاض مساحة التخزين على الجهاز. هذا النمط على false بشكل تلقائي، ولكن يمكنك ضبط allowAssetPackDeletion وسيطة اختيارية إلى ImmediateAppUpdateOptions() أو FlexibleAppUpdateOptions() لضبطها على true بدلاً من ذلك:

// Creates an AppUpdateOptions for an immediate flow that allows
// asset pack deletion.
var appUpdateOptions =
  AppUpdateOptions.ImmediateAppUpdateOptions(allowAssetPackDeletion: true);

// Creates an AppUpdateOptions for a flexible flow that allows asset
// pack deletion.
var appUpdateOptions =
  AppUpdateOptions.FlexibleAppUpdateOptions(allowAssetPackDeletion: true);

تعتمد الخطوات التالية على ما إذا كنت تطلب جدولاً مرنًا إجراء تحديث أو إجراء تحديث فوري

التعامل مع التحديث المرن

بعد توفُّر عنصر AppUpdateInfo حديث وضبطه بشكل صحيح كائن AppUpdateOptions، يمكنك طلب AppUpdateManager.StartUpdate() من أجل طلب تدفق تحديث بشكل غير متزامن.

IEnumerator StartFlexibleUpdate()
{
  // Creates an AppUpdateRequest that can be used to monitor the
  // requested in-app update flow.
  var startUpdateRequest = appUpdateManager.StartUpdate(
    // The result returned by PlayAsyncOperation.GetResult().
    appUpdateInfoResult,
    // The AppUpdateOptions created defining the requested in-app update
    // and its parameters.
    appUpdateOptions);

  while (!startUpdateRequest.IsDone)
  {
  // For flexible flow,the user can continue to use the app while
  // the update downloads in the background. You can implement a
  // progress bar showing the download status during this time.
  yield return null;
  }

}

لإجراء تحديث مرن، يجب بدء تثبيت تحديث التطبيق. بعد انتهاء التنزيل بنجاح. للقيام بذلك، اتصل AppUpdateManager.CompleteUpdate(), كما هو موضح في المثال التالي:

IEnumerator CompleteFlexibleUpdate()
{
  var result = appUpdateManager.CompleteUpdate();
  yield return result;

  // If the update completes successfully, then the app restarts and this line
  // is never reached. If this line is reached, then handle the failure (e.g. by
  // logging result.Error or by displaying a message to the user).
}

معالجة طلب التحديث الفوري

بعد توفُّر عنصر AppUpdateInfo حديث وضبطه بشكل صحيح كائن AppUpdateOptions، يمكنك طلب AppUpdateManager.StartUpdate() من أجل طلب تدفق تحديث بشكل غير متزامن.

IEnumerator StartImmediateUpdate()
{
  // Creates an AppUpdateRequest that can be used to monitor the
  // requested in-app update flow.
  var startUpdateRequest = appUpdateManager.StartUpdate(
    // The result returned by PlayAsyncOperation.GetResult().
    appUpdateInfoResult,
    // The AppUpdateOptions created defining the requested in-app update
    // and its parameters.
    appUpdateOptions);
  yield return startUpdateRequest;

  // If the update completes successfully, then the app restarts and this line
  // is never reached. If this line is reached, then handle the failure (for
  // example, by logging result.Error or by displaying a message to the user).
}

ولإجراء عملية تحديث فورية، يعرض Google Play مربّع حوار لتأكيد حساب المستخدم. عندما يقبل المستخدم الطلب، يتم تنزيل Google Play تلقائيًا بتثبيت التحديث، ثم إعادة تشغيل التطبيق إلى الإصدار المحدَّث إذا تم التثبيت بنجاح.

خطأ أثناء المعالجة

يصف هذا القسم حلول الأخطاء الشائعة.

• إذا طرحت StartUpdate() العلامة ArgumentNullException، هذا يعني أن AppUpdateInfo فارغ. تأكَّد من عرض الكائن AppUpdateInfo من القيمة GetAppUpdateInfo() ليست فارغة قبل بدء عملية التحديث.
• إذا عرضت PlayAsyncOperation رمز الخطأ ErrorUpdateUnavailable، عليك إجراء من توفُّر إصدار مُحدَّث للتطبيق يتضمّن التطبيق نفسه رقم التعريف ومفتاح التوقيع
• إذا عرضت PlayAsyncOperation رمز الخطأ ErrorUpdateNotAllowed، سيتم يعني أن الكائن AppUpdateOptions يشير إلى نوع تحديث ليس سيتم السماح للتحديث المتاح. التحقّق مما إذا كان الكائن AppUpdateInfo يشير إلى أنّ نوع التحديث المحدَّد مسموح به قبل بدء عملية التحديث التدفق.

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

اختبار تحديثات تطبيقك داخل التطبيق للتحقق أن الدمج يعمل بشكل صحيح.