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

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

نمای کلی Unreal Engine SDK

Play In-App Updates API بخشی از خانواده Play Core SDK است. API برای Unreal Engine یک کلاس UInAppUpdatesManager برای مدیریت ارتباط بین برنامه شما و Play API ارائه می دهد. پس از درخواست، برنامه شما می‌تواند وضعیت درخواست را با استفاده از EAppUpdateErrorCode بررسی کند.

پشتیبانی از نسخه های Unreal Engine

این افزونه از Unreal Engine 5.0 و تمامی نسخه های بعدی پشتیبانی می کند.

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

راه اندازی

  1. افزونه Play Unreal Engine را از مخزن GitHub دانلود کنید.

  2. پوشه GooglePlay را در داخل پوشه Plugins خود در پروژه Unreal Engine خود کپی کنید.

  3. پروژه Unreal Engine خود را باز کنید و روی Edit → Plugins کلیک کنید.

  4. Google Play را جستجو کنید و چک باکس Enabled را علامت بزنید.

  5. پروژه بازی را دوباره راه اندازی کنید و یک ساخت را راه اندازی کنید.

  6. فایل Build.cs پروژه خود را باز کنید و ماژول PlayInAppUpdates را به PublicDependencyModuleNames اضافه کنید:

    using UnrealBuildTool;

public class MyGame : ModuleRules
{
  public MyGame(ReadOnlyTargetRules Target) : base(Target)
  {
    // ...

    PublicDependencyModuleNames.Add("PlayInAppUpdates");

    // ...
  }
}

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

قبل از درخواست به‌روزرسانی، بررسی کنید که آیا به‌روزرسانی برای برنامه شما موجود است یا خیر. از UInAppUpdatesManager::RequestInfo برای بررسی به‌روزرسانی استفاده کنید:

MyClass.h

void MyClass::OnRequestInfoOperationCompleted(
  EAppUpdateErrorCode ErrorCode,
  UAppUpdateInfo* UpdateInfo)
{
  // Check the resulting error code.
  if (ErrorCode == EAppUpdateErrorCode::AppUpdate_NO_ERROR)
  {
    // Check AppUpdateInfo's UpdateAvailability, UpdatePriority,
    // IsUpdateTypeAllowed(), ... and decide whether to ask the user
    // to start an in-app update.
  }
}

MyClass.cpp

void MyClass::CheckForUpdateAvailability()
{
  // Create a delegate to bind the callback function.
  FRequestInfoOperationCompletedDelegate Delegate;

  // Bind the completion handler (OnRequestInfoOperationCompleted) to the delegate.
  Delegate.BindDynamic(this, &MyClass::OnRequestInfoOperationCompleted);

  // Initiate the request info operation, passing the delegate to handle the result.
  GetGameInstance()
    ->GetSubsystem<UInAppUpdatesManager>()
    ->RequestInfo(Delegate);
}

نمونه UAppUpdateInfo برگشتی حاوی وضعیت در دسترس بودن به‌روزرسانی است. اگر یک به‌روزرسانی درون‌برنامه از قبل در حال انجام است، نمونه وضعیت به‌روزرسانی در حال انجام را نیز گزارش می‌کند.

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

علاوه بر بررسی اینکه آیا یک به‌روزرسانی در دسترس است، ممکن است بخواهید بررسی کنید که از آخرین باری که کاربر از یک به‌روزرسانی از طریق فروشگاه Play اطلاع داده شده است، چقدر زمان گذشته است. این می تواند به شما کمک کند تصمیم بگیرید که آیا باید یک به روز رسانی انعطاف پذیر را شروع کنید یا یک به روز رسانی فوری. برای مثال، ممکن است چند روز قبل از اطلاع دادن به کاربر با یک به‌روزرسانی انعطاف‌پذیر، و چند روز پس از آن قبل از نیاز به به‌روزرسانی فوری صبر کنید.

از UAppUpdateInfo:GetClientVersionStalenessDays برای بررسی تعداد روزهایی که به‌روزرسانی از طریق فروشگاه Play در دسترس قرار گرفته است، استفاده کنید:

int32 ClientVersionStalenessDays = UpdateInfo->GetClientVersionStalenessDays();

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

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"
  }]
}

در کد برنامه‌تان، می‌توانید با استفاده از UAppUpdateInfo::UpdatePriority سطح اولویت یک به‌روزرسانی را بررسی کنید:

int32 Priority = UpdateInfo->GetPriority();

یک به روز رسانی را شروع کنید

پس از تأیید وجود به‌روزرسانی، می‌توانید با استفاده از UInAppUpdatesManager::StartUpdate درخواست به‌روزرسانی کنید. قبل از درخواست به‌روزرسانی، مطمئن شوید که یک شی UAppUpdateInfo به‌روز دارید. همچنین باید یک شی UAppUpdateOptions برای پیکربندی جریان به روز رسانی ایجاد کنید.

مثال زیر یک شی UAppUpdateOptions را برای یک جریان به روز رسانی فوری ایجاد می کند:

// Creates an UAppUpdateOptions defining an immediate in-app
// update flow and its parameters.
UAppUpdateOptions* Options = NewObject<UAppUpdateOptions>();
Options->CreateOptions(EAppUpdateType::AppUpdate_TYPE_IMMEDIATE);

مثال زیر یک شی UAppUpdateOptions را برای یک جریان به روز رسانی انعطاف پذیر ایجاد می کند:

// Creates an UAppUpdateOptions defining a flexible in-app
// update flow and its parameters.
UAppUpdateOptions* Options = NewObject<UAppUpdateOptions>();
Options->CreateOptions(EAppUpdateType::AppUpdate_TYPE_FLEXIBLE);

شی UAppUpdateOptions همچنین حاوی یک تابع IsAssetPackDeletionAllowed است که نشان می دهد آیا به روز رسانی مجاز به پاک کردن بسته های دارایی در صورت محدودیت فضای ذخیره سازی دستگاه است یا خیر. این فیلد به طور پیش‌فرض روی false تنظیم شده است، اما می‌توانید با استفاده از UAppUpdateOptions::SetAssetPackDeletionAllowed فیلد را روی true تنظیم کنید:

// Sets the AssetPackDeletionAllowed field to true.
Options->SetAssetPackDeletionAllowed(true);

مراحل بعدی بستگی به این دارد که آیا درخواست به‌روزرسانی انعطاف‌پذیر دارید یا به‌روزرسانی فوری .

به روز رسانی انعطاف پذیر را مدیریت کنید

بعد از اینکه یک شی UAppUpdateInfo به روز و یک شی UAppUpdateOptions با پیکربندی مناسب داشتید، می توانید با UInAppUpdatesManager::StartUpdate تماس بگیرید تا جریان به روز رسانی را درخواست کنید.

MyClass.h 

void MyClass::OnStartUpdateOperationCompleted(EAppUpdateErrorCode ErrorCode)
{
  // ...
}

MyClass.cpp 

// .cpp
void MyClass::StartUpdate()
{
  // Create a delegate to bind the callback function.
  FUpdateOperationCompletedDelegate Delegate;

  // Bind the completion handler (OnStartUpdateOperationCompleted) to the delegate.
  Delegate.BindDynamic(this, &MyClass::OnStartUpdateOperationCompleted);

  // Initiate the start update operation, passing the delegate to handle the result.
  GetGameInstance()
    ->GetSubsystem<UInAppUpdatesManager>()
    ->StartUpdate(UpdateInfo, UpdateOptions, Delegate);
}

برای یک جریان به‌روزرسانی انعطاف‌پذیر، باید پس از اتمام موفقیت‌آمیز دانلود، نصب به‌روزرسانی برنامه را آغاز کنید. برای انجام این کار، همانطور که در مثال زیر نشان داده شده است، InAppUpdatesManager::CompleteUpdate را فراخوانی کنید:

MyClass.h 

void MyClass::OnCompleteUpdateOperationCompleted(EAppUpdateErrorCode ErrorCode)
{
  // ...
}

MyClass.cpp 

void MyClass::CompleteFlexibleUpdate()
{
  // Create a delegate to bind the callback function.
  FUpdateOperationCompletedDelegate Delegate;

  // Bind the completion handler (OnCompleteUpdateOperationCompleted) to the delegate.
  Delegate.BindDynamic(this, &MyClass::OnCompleteUpdateOperationCompleted);

  // Initiate the complete update operation, passing the delegate to handle the result.
  GetGameInstance()
    ->GetSubsystem<UInAppUpdatesManager>()
    ->CompleteUpdate(UpdateInfo, UpdateOptions, Delegate);
}

به روز رسانی فوری را مدیریت کنید

بعد از اینکه یک شی UAppUpdateInfo به‌روز و یک شی UAppUpdateOptions با پیکربندی مناسب داشتید، می‌توانید با InAppUpdatesManager::StartUpdate تماس بگیرید تا جریان به‌روزرسانی را درخواست کنید.

MyClass.h 

void MyClass::OnStartUpdateOperationCompleted(EAppUpdateErrorCode ErrorCode)
{
  // ...
}

MyClass.cpp 

void MyClass::StartUpdate()
{
  // Create a delegate to bind the callback function.
  FUpdateOperationCompletedDelegate Delegate;

  // Bind the completion handler (OnStartUpdateOperationCompleted) to the delegate.
  Delegate.BindDynamic(this, &MyClass::OnStartUpdateOperationCompleted);

  // Initiate the start update operation, passing the delegate to handle the result.
  GetGameInstance()
    ->GetSubsystem<UInAppUpdatesManager>()
    ->StartUpdate(UpdateInfo, UpdateOptions, Delegate);
}

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

رسیدگی به خطا

این بخش راه حل هایی را برای خطاهای رایج توضیح می دهد.

  • اگر UInAppUpdatesManager::StartUpdate یک خطای AppUpdate_INVALID_REQUEST برگرداند، به این معنی است که UAppUpdateInfo نامعتبر است. مطمئن شوید که شی UAppUpdateInfo که از UInAppUpdatesManager::RequestInfo برگردانده شده است، قبل از شروع جریان به روز رسانی تهی نباشد.
  • اگر UInAppUpdatesManager::StartUpdate خطای AppUpdate_NOT_ALLOWED را برمی گرداند، به این معنی است که شی UAppUpdateOptions نوع به روز رسانی را نشان می دهد که برای به روز رسانی موجود مجاز نیست. بررسی کنید که آیا شی UAppUpdateInfo نشان می دهد که نوع به روز رسانی انتخاب شده قبل از شروع جریان به روز رسانی مجاز است یا خیر.

مراحل بعدی

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