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

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

محیط توسعه خود را تنظیم کنید

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 Window > Package Manager باز کنید.

  4. منوی کشویی مدیریت دامنه را برای انتخاب My Registries تنظیم کنید.

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

واردات از GitHub

  1. آخرین نسخه .unitypackage را از GitHub دانلود کنید.

  2. فایل .unitypackage را با انتخاب گزینه منوی Unity Assets > Import package > Custom Package و وارد کردن همه موارد وارد کنید.

نمای کلی Unity SDK

API به‌روزرسانی درون‌برنامه 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 به شما امکان می دهد اولویت هر به روز رسانی را تعیین کنید. این به برنامه شما اجازه می‌دهد تصمیم بگیرد که چقدر به‌روزرسانی به‌طور جدی به کاربر توصیه کند. برای مثال، استراتژی زیر را برای تنظیم اولویت به‌روزرسانی در نظر بگیرید:

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

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

همانطور که در مستندات Play Developer API توضیح داده شده است، اولویت را با استفاده از Google 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 نشان می دهد که نوع به روز رسانی انتخاب شده قبل از شروع جریان به روز رسانی مجاز است یا خیر.

مراحل بعدی

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