پشتیبانی از به روز رسانی های درون برنامه ای (یونیتی)

این راهنما نحوه پشتیبانی از به‌روزرسانی‌های درون‌برنامه‌ای در برنامه شما با استفاده از Unity را شرح می‌دهد. راهنماهای جداگانه‌ای برای مواردی که پیاده‌سازی شما از زبان برنامه‌نویسی Kotlin یا زبان برنامه‌نویسی Java استفاده می‌کند و مواردی که پیاده‌سازی شما از کد بومی (C/C++) استفاده می‌کند، وجود دارد.

مرور کلی SDK یونیتی

API به‌روزرسانی درون‌برنامه‌ای Play بخشی از خانواده‌ی Play Core SDK است. افزونه‌ی 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;

بررسی اولویت به‌روزرسانی

رابط برنامه‌نویسی کاربردی توسعه‌دهندگان گوگل پلی به شما امکان می‌دهد اولویت هر به‌روزرسانی را تعیین کنید. این به برنامه شما اجازه می‌دهد تا تصمیم بگیرد که با چه شدتی یک به‌روزرسانی را به کاربر توصیه کند. برای مثال، استراتژی زیر را برای تنظیم اولویت به‌روزرسانی در نظر بگیرید:

• بهبودهای جزئی رابط کاربری: به‌روزرسانی با اولویت پایین ؛ نه به‌روزرسانی انعطاف‌پذیر و نه به‌روزرسانی فوری درخواست نکنید.
• بهبود عملکرد: به‌روزرسانی با اولویت متوسط ؛ درخواست به‌روزرسانی انعطاف‌پذیر.
• به‌روزرسانی امنیتی حیاتی: به‌روزرسانی با اولویت بالا ؛ درخواست به‌روزرسانی فوری.

برای تعیین اولویت، گوگل پلی از یک مقدار صحیح بین ۰ تا ۵ استفاده می‌کند که ۰ مقدار پیش‌فرض و ۵ بالاترین اولویت را دارد. برای تنظیم اولویت یک به‌روزرسانی، از فیلد inAppUpdatePriority در زیر Edits.tracks.releases در Google Play Developer API استفاده کنید. همه نسخه‌های تازه اضافه شده در نسخه، اولویت یکسانی با نسخه دارند. اولویت فقط هنگام انتشار نسخه جدید قابل تنظیم است و بعداً قابل تغییر نیست.

اولویت را با استفاده از Google Play Developer API همانطور که در مستندات Play Developer API توضیح داده شده است، تنظیم کنید. اولویت به‌روزرسانی درون‌برنامه‌ای باید در منبع Edit.tracks که در متد Edit.tracks: update ارسال شده است، مشخص شود. مثال زیر انتشار یک برنامه با کد نسخه ۸۸ و 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).
}

برای به‌روزرسانی فوری، گوگل پلی یک پنجره‌ی تأیید به کاربر نمایش می‌دهد. وقتی کاربر درخواست را می‌پذیرد، گوگل پلی به‌طور خودکار به‌روزرسانی را دانلود و نصب می‌کند، سپس در صورت موفقیت‌آمیز بودن نصب، برنامه را مجدداً به نسخه به‌روزرسانی‌شده راه‌اندازی می‌کند.

مدیریت خطا

این بخش راه‌حل‌هایی برای خطاهای رایج ارائه می‌دهد.

• اگر StartUpdate() یک ArgumentNullException صادر کند، به این معنی است که AppUpdateInfo با null است. قبل از شروع جریان به‌روزرسانی، مطمئن شوید که شیء AppUpdateInfo که از GetAppUpdateInfo() برگردانده می‌شود، null نباشد.
• اگر PlayAsyncOperation کد خطای ErrorUpdateUnavailable را برمی‌گرداند، مطمئن شوید که نسخه به‌روزرسانی‌شده‌ای از برنامه با همان شناسه برنامه و کلید امضای آن در دسترس است.
• اگر PlayAsyncOperation کد خطای ErrorUpdateNotAllowed را برگرداند، به این معنی است که شیء AppUpdateOptions نوع به‌روزرسانی را نشان می‌دهد که برای به‌روزرسانی موجود مجاز نیست. قبل از شروع جریان به‌روزرسانی، بررسی کنید که آیا شیء AppUpdateInfo نشان می‌دهد که نوع به‌روزرسانی انتخاب شده مجاز است یا خیر.

مراحل بعدی

به‌روزرسانی‌های درون‌برنامه‌ای برنامه‌تان را آزمایش کنید تا مطمئن شوید که یکپارچه‌سازی به درستی کار می‌کند.