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. 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
Play In-App Updates API thuộc nhóm SDK Play Core. API cho Unreal Engine có một lớp UInAppUpdatesManager để xử lý giao tiếp giữa ứng dụng của bạn và Play API. Sau khi đưa ra yêu cầu, ứng dụng có thể kiểm tra trạng thái của yêu cầu bằng cách sử dụ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
Tải Trình bổ trợ Play Unreal Engine xuống từ kho lưu trữ GitHub.
Sao chép thư mục
GooglePlayvào thư mụcPluginstrong dự án Unreal Engine.Mở dự án Unreal Engine rồi nhấp vào Edit → Plugins (Chỉnh sửa → Trình bổ trợ).
Tìm Google Play rồi đánh dấu vào hộp Đã bật.
Khởi động lại dự án trò chơi và kích hoạt một bản dựng.
Mở tệp
Build.cscủa dự án rồi thêm mô-đunPlayInAppUpdatesvàoPublicDependencyModuleNames: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 bạn 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 không. Hãy sử dụng UInAppUpdatesManager::RequestInfo để kiểm tra xem có bản cập nhật hay không:
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 sẵn có của bản cập nhật.
Nếu bản cập nhật ứng dụng đang diễn ra, thực thể đó cũng 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 Cửa hàng Play có bản cập nhật:
int32 ClientVersionStalenessDays = UpdateInfo->GetClientVersionStalenessDays();
Kiểm tra mức độ ưu tiên của bản cập nhật
Google Play Developer API cho phép bạn thiết lập mức độ ưu tiên của mỗi 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 bản cập nhật cho người dùng. Ví dụ: nên 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 Google Play Developer API như mô tả trong tài liệu về Google Play Developer API. Mức độ ưu tiên của bản cập nhật trong ứng dụng phải được chỉ định 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 mức độ ưu tiên của một bản cập nhật cụ thể 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 bạn yêu cầu cập nhật, hãy đảm bảo rằng bạn có đối tượng UAppUpdateInfo đã cập nhật. Bạn cũng phải tạo một đối tượng UAppUpdateOptions để định cấu hình cho 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 hàm IsAssetPackDeletionAllowed trả về thông tin cho biết liệu bản cập nhật có được phép xoá gói tài sản hay không trong trường hợp thiết bị bị giới hạn bộ nhớ trên thiết bị. 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 cách sử dụng UAppUpdateOptions::SetAssetPackDeletionAllowed để đặt thành true:
// Sets the AssetPackDeletionAllowed field to true.
Options->SetAssetPackDeletionAllowed(true);
Các bước tiếp theo phụ thuộc vào việc bạn yêu cầu cập nhật linh hoạt hay cập nhật ngay.
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 một 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 một 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::StartUpdatetrả về lỗiAppUpdate_INVALID_REQUEST, điều đó có nghĩa làUAppUpdateInfokhông hợp lệ. Đảm bảo rằng đối tượngUAppUpdateInfođược trả về từUInAppUpdatesManager::RequestInfokhông rỗng trước khi bắt đầu quy trình cập nhật. - Nếu
UInAppUpdatesManager::StartUpdatetrả về lỗiAppUpdate_NOT_ALLOWED, thì có nghĩa là đối tượngUAppUpdateOptionscho 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ó. Trước khi bắt đầu quy trình cập nhật, hãy kiểm tra đối tượngUAppUpdateInfođể biết loại cập nhật đã chọn có được cho phép hay không.
Các bước tiếp theo
Kiểm thử bản cập nhật trong ứng dụng cho ứng dụng để xác minh rằng quá trình tích hợp hoạt động chính xác.