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

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

نمای کلی Unity SDK

میانای برنامه‌سازی کاربردی به‌روزرسانی درون‌برنامه Play بخشی از خانواده کیت توسعه نرم‌افزار Play Core است. افزونه Unity کلاس AppUpdateManager را برای مدیریت ارتباط بین برنامه شما و Google Play API ارائه می‌دهد. باید این کلاس را نمونه‌سازی کنید تا بتوانید از آن برای مدیریت به‌روزرسانی‌های درون‌برنامه استفاده کنید:

AppUpdateManager appUpdateManager = new AppUpdateManager();

راه‌اندازی محیط توسعه نرم‌افزار

OpenUPM-CLI

اگر OpenUPM CLI را نصب کرده‌اید، می‌توانید با فرمان زیر، دفتر ثبت OpenUPM را نصب کنید:

openupm add com.google.play.appupdate

OpenUPM

  1. با انتخاب گزینه منو Unity Edit > Project Settings > Package Manager، تنظیمات مدیر بسته را باز کنید.

  2. OpenUPM را به‌عنوان یک دفتر ثبت محدودشده به پنجره Package Manager اضافه کنید:

    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.appupdate
    
  3. منو مدیر بسته را با انتخاب گزینه منو Unity پنجره > مدیر بسته باز کنید.

  4. منوِ کرکره‌ای دامنه مدیر را روی دفترهای ثبت من تنظیم کنید.

  5. بسته افزونه Google Play Integrity برای Unity را از فهرست بسته‌ها انتخاب کنید و نصب را فشار دهید.

وارد کردن از GitHub

  1. جدیدترین نسخه .unitypackage را از GitHub بارگیری کنید.

  2. فایل .unitypackage را با انتخاب گزینه منو Unity دارایی‌ها > وارد کردن بسته > بسته سفارشی و وارد کردن همه موارد وارد کنید.

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

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

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

مراحل بعدی

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