รองรับการอัปเดตในแอป (Unreal Engine)

คู่มือนี้จะอธิบายวิธีรองรับการอัปเดตในแอปในแอปของคุณโดยใช้ Unreal Engine เรามีคำแนะนำแยกต่างหากสำหรับกรณีที่การติดตั้งใช้งานใช้ภาษาโปรแกรม Kotlin หรือภาษาโปรแกรม Java และกรณีที่การติดตั้งใช้งานใช้โค้ดเนทีฟ (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 Plugin จากที่เก็บ GitHub

  2. คัดลอกโฟลเดอร์ GooglePlay ภายในโฟลเดอร์ Plugins ในโปรเจ็กต์ Unreal Engine

  3. เปิดโปรเจ็กต์ Unreal Engine แล้วคลิกแก้ไข → ปลั๊กอิน

  4. ค้นหา Google Play แล้วเลือกช่องทำเครื่องหมายเปิดใช้

  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 Store ซึ่งจะช่วยให้คุณตัดสินใจได้ว่าจะเริ่มต้นการอัปเดตแบบยืดหยุ่นหรือการอัปเดตทันที ตัวอย่างเช่น คุณอาจรอ 2-3 วันก่อนแจ้งให้ผู้ใช้ทราบถึงการอัปเดตแบบยืดหยุ่น และรออีก 2-3 วันหลังจากนั้นก่อนที่จะกำหนดให้อัปเดตทันที

ใช้ UAppUpdateInfo:GetClientVersionStalenessDays เพื่อตรวจสอบจำนวนวันนับตั้งแต่การอัปเดตพร้อมให้บริการผ่าน Play Store

int32 ClientVersionStalenessDays = UpdateInfo->GetClientVersionStalenessDays();

ตรวจสอบลําดับความสําคัญของการอัปเดต

Google Play Developer API ช่วยให้คุณกำหนดลำดับความสำคัญของการอัปเดตแต่ละรายการได้ ซึ่งจะช่วยให้แอปตัดสินใจได้ว่าควรแนะนำให้ผู้ใช้อัปเดตมากน้อยเพียงใด ตัวอย่างเช่น ลองใช้กลยุทธ์ต่อไปนี้ในการกำหนดลำดับความสำคัญของการอัปเดต

  • การปรับปรุง UI เล็กน้อย: การอัปเดตสำคัญน้อย ไม่ขอการอัปเดตแบบยืดหยุ่นหรือการอัปเดตทันที
  • การปรับปรุงประสิทธิภาพ: การอัปเดตสำคัญปานกลาง ขอการอัปเดตแบบยืดหยุ่น
  • การอัปเดตความปลอดภัยที่สำคัญ: การอัปเดตสำคัญสูง ให้ขอการอัปเดตทันที

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

ในโค้ดของแอป คุณสามารถตรวจสอบระดับความสำคัญของการอัปเดตหนึ่งๆ ได้โดยใช้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 ไม่ใช่ค่า Null ก่อนเริ่มขั้นตอนการอัปเดต
  • หาก UInAppUpdatesManager::StartUpdate แสดงข้อผิดพลาด AppUpdate_NOT_ALLOWED แสดงว่าออบเจ็กต์ UAppUpdateOptions ระบุประเภทการอัปเดตที่ไม่อนุญาตให้ใช้กับการอัปเดตที่มีอยู่ ตรวจสอบว่าออบเจ็กต์ UAppUpdateInfo ระบุว่าอนุญาตให้อัปเดตประเภทที่เลือกหรือไม่ก่อนที่จะเริ่มขั้นตอนการอัปเดต

ขั้นตอนถัดไป

ทดสอบการอัปเดตในแอปของแอปเพื่อยืนยันว่าการผสานรวมทํางานอย่างถูกต้อง