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

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

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

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

AppUpdateManager appUpdateManager = new AppUpdateManager();

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

openupm add com.google.play.appupdate

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

قبل طلب تحديث، تحقَّق مما إذا كان يتوفّر تحديث لتطبيقك. استخدِم 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(), ... 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 و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 يشير إلى أنّ نوع التحديث المحدّد مسموح به قبل بدء مسار التحديث.

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

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