Hỗ trợ cập nhật trong ứng dụng (Unreal Engine)

Hướng dẫn này mô tả cách hỗ trợ bản cập nhật trong ứng dụng bằng Unreal Engine. Sẽ có các hướng dẫn riêng cho trường hợp triển khai sử dụng ngôn ngữ lập trình Kotlin hoặc ngôn ngữ lập trình Java và trường hợp triển khai sử dụng mã gốc (C/C++) hoặc Unity.

Tổng quan về SDK Unreal Engine

API Cập nhật trong ứng dụng của Play thuộc nhóm SDK Play Core. API cho Unreal Engine cung cấp một lớp UInAppUpdatesManager để xử lý giao tiếp giữa ứng dụng của bạn và API Play. Sau khi yêu cầu được thực hiện, ứng dụng của bạn có thể kiểm tra trạng thái của yêu cầu bằng EAppUpdateErrorCode.

Các phiên bản Unreal Engine được hỗ trợ

Trình bổ trợ này hỗ trợ Unreal Engine 5.0 và tất cả các phiên bản tiếp theo.

Thiết lập môi trường phát triển

  1. Tải Trình bổ trợ Unreal Engine của Play xuống từ kho lưu trữ GitHub.

  2. Sao chép thư mục GooglePlay vào thư mục Plugins trong dự án Unreal Engine.

  3. Mở dự án Unreal Engine rồi nhấp vào Edit → Plugins (Chỉnh sửa → Trình bổ trợ).

  4. Tìm Google Play rồi đánh dấu vào hộp đánh dấu Đã bật.

  5. Khởi động lại dự án trò chơi và kích hoạt một bản dựng.

  6. Mở tệp Build.cs của dự án và thêm mô-đun PlayInAppUpdates vào PublicDependencyModuleNames:

    using UnrealBuildTool;

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

    PublicDependencyModuleNames.Add("PlayInAppUpdates");

    // ...
  }
}

Kiểm tra xem có bản cập nhật chưa

Trước khi yêu cầu cập nhật, hãy kiểm tra xem có bản cập nhật nào cho ứng dụng của bạn hay không. Sử dụng UInAppUpdatesManager::RequestInfo để kiểm tra bản cập nhật:

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);
}

Thực thể UAppUpdateInfo được trả về chứa trạng thái có bản cập nhật hay không. Nếu một bản cập nhật trong ứng dụng đang diễn ra, thì thực thể này cũng sẽ báo cáo trạng thái của bản cập nhật đang diễn ra.

Kiểm tra tình trạng lỗi thời của bản cập nhật

Ngoài việc kiểm tra xem có bản cập nhật hay không, bạn cũng nên kiểm tra xem đã bao lâu kể từ lần gần nhất người dùng được Cửa hàng Play thông báo về bản cập nhật. Điều này có thể giúp bạn quyết định xem nên tiến hành cập nhật linh hoạt hay cập nhật tức thì. Ví dụ: bạn có thể chờ một vài ngày trước khi thông báo cho người dùng về bản cập nhật linh hoạt và vài ngày sau đó mới yêu cầu cập nhật ngay.

Sử dụng UAppUpdateInfo:GetClientVersionStalenessDays để kiểm tra số ngày kể từ khi bản cập nhật đó có trên Cửa hàng Play:

int32 ClientVersionStalenessDays = UpdateInfo->GetClientVersionStalenessDays();

Kiểm tra mức độ ưu tiên của bản cập nhật

API Nhà phát triển Google Play cho phép bạn đặt mức độ ưu tiên của từng bản cập nhật. Điều này cho phép ứng dụng của bạn quyết định mức độ đề xuất cập nhật cho người dùng. Ví dụ: hãy cân nhắc chiến lược sau đây về việc đặt mức độ ưu tiên cho bản cập nhật:

  • Cải tiến nhỏ về giao diện người dùng: Cập nhật có mức độ ưu tiên thấp; không yêu cầu cập nhật linh hoạt cũng như cập nhật ngay.
  • Cải thiện hiệu suất: Cập nhật có mức độ ưu tiên trung bình; yêu cầu cập nhật linh hoạt.
  • Cập nhật bảo mật quan trọng: Cập nhật có mức độ ưu tiên cao; yêu cầu cập nhật ngay.

Để xác định mức độ ưu tiên, Google Play sử dụng giá trị số nguyên từ 0 đến 5, trong đó 0 là giá trị mặc định và 5 là mức độ ưu tiên cao nhất. Để thiết lập mức độ ưu tiên cho một bản cập nhật, hãy sử dụng trường inAppUpdatePriority trong Edits.tracks.releases của API Nhà phát triển Google Play. Tất cả các phiên bản mới thêm vào trong bản phát hành đều có mức độ ưu tiên tương tự với bản phát hành đó. Chỉ có thể thiết lập mức độ ưu tiên vào thời điểm ra mắt bản phát hành mới và sau đó bạn không thay đổi được mức độ ưu tiên này.

Đặt mức độ ưu tiên bằng cách sử dụng API Nhà phát triển Google Play như mô tả trong tài liệu về API Nhà phát triển Play. Bạn nên chỉ định mức độ ưu tiên của bản cập nhật trong ứng dụng trong tài nguyên Edit.tracks được truyền trong phương thức Edit.tracks: update. Ví dụ sau minh hoạ việc phát hành một ứng dụng có mã phiên bản 88 và inAppUpdatePriority 5:

{
  "releases": [{
      "versionCodes": ["88"],
      "inAppUpdatePriority": 5,
      "status": "completed"
  }]
}

Trong mã của ứng dụng, bạn có thể kiểm tra cấp độ ưu tiên của một bản cập nhật nhất định bằng cách sử dụng UAppUpdateInfo::UpdatePriority:

int32 Priority = UpdateInfo->GetPriority();

Bắt đầu cập nhật

Sau khi xác nhận đã có bản cập nhật, bạn có thể yêu cầu cập nhật bằng UInAppUpdatesManager::StartUpdate. Trước khi yêu cầu cập nhật, hãy đảm bảo bạn có đối tượng UAppUpdateInfo mới nhất. Bạn cũng phải tạo một đối tượng UAppUpdateOptions để định cấu hình quy trình cập nhật.

Ví dụ sau đây sẽ tạo một đối tượng UAppUpdateOptions cho quy trình cập nhật ngay:

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

Ví dụ sau đây sẽ tạo một đối tượng UAppUpdateOptions cho quy trình cập nhật linh hoạt:

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

Đối tượng UAppUpdateOptions cũng chứa một hàm IsAssetPackDeletionAllowed trả về liệu bản cập nhật có được phép xoá các gói tài sản trong trường hợp bộ nhớ thiết bị bị hạn chế hay không. Theo mặc định, trường này được đặt thành false, nhưng bạn có thể đặt trường này bằng UAppUpdateOptions::SetAssetPackDeletionAllowed để đặt thành true:

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

Các bước tiếp theo sẽ tuỳ thuộc vào việc bạn yêu cầu cập nhật linh hoạt hay cập nhật tức thì.

Xử lý bản cập nhật linh hoạt

Sau khi có đối tượng UAppUpdateInfo cập nhật và đối tượng UAppUpdateOptions được định cấu hình đúng cách, bạn có thể gọi UInAppUpdatesManager::StartUpdate để yêu cầu quy trình cập nhật.

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);
}

Đối với quy trình cập nhật linh hoạt, bạn phải kích hoạt cài đặt bản cập nhật ứng dụng sau khi tải xuống thành công. Để thực hiện việc này, hãy gọi InAppUpdatesManager::CompleteUpdate như trong ví dụ sau:

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);
}

Xử lý bản cập nhật tức thì

Sau khi có đối tượng UAppUpdateInfo cập nhật và đối tượng UAppUpdateOptions được định cấu hình đúng cách, bạn có thể gọi InAppUpdatesManager::StartUpdate để yêu cầu quy trình cập nhật.

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);
}

Đối với quy trình cập nhật ngay, Google Play sẽ hiện hộp thoại yêu cầu người dùng xác nhận. Khi người dùng chấp nhận yêu cầu, Google Play sẽ tự động tải xuống và cài đặt bản cập nhật, sau đó khởi động lại ứng dụng ở phiên bản cập nhật nếu cài đặt thành công.

Xử lý lỗi

Phần này mô tả giải pháp cho các lỗi thường gặp.

  • Nếu UInAppUpdatesManager::StartUpdate trả về lỗi AppUpdate_INVALID_REQUEST, thì có nghĩa là UAppUpdateInfo không hợp lệ. Đảm bảo rằng đối tượng UAppUpdateInfo được trả về từ UInAppUpdatesManager::RequestInfo không rỗng trước khi bắt đầu quy trình cập nhật.
  • Nếu UInAppUpdatesManager::StartUpdate trả về lỗi AppUpdate_NOT_ALLOWED, thì có nghĩa là đối tượng UAppUpdateOptions cho biết loại cập nhật không được phép đối với bản cập nhật hiện có. Kiểm tra xem đối tượng UAppUpdateInfo có cho biết loại cập nhật đã chọn có được phép hay không trước khi bắt đầu quy trình cập nhật.

Các bước tiếp theo

Kiểm thử bản cập nhật trong ứng dụng của bạn để xác minh rằng tính năng tích hợp của bạn đang hoạt động đúng cách.