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

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

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

يمكنك تنزيل أحدث إصدار من المكوّن الإضافي Play In-App Update Unity الإضافي من حزم Google لنظام التشغيل Unity.

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

واجهة برمجة التطبيقات للتحديث داخل التطبيق في Play هي جزء من مجموعة Play Core SDK. يقدِّم مكوّن Unity الإضافي صفًا 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 Developer API. يجب تحديد أولوية التحديث داخل التطبيق في المرجع Edit.tracks الذي تم تمريره في طريقة Edit.tracks: update. يوضّح المثال التالي إصدار تطبيق برمز الإصدار 88 والإصدار 5 من inAppUpdatePriority:

{
  "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 يشير إلى أنّ نوع التعديل المحدّد مسموح به قبل بدء عملية التعديل.

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

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