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

Hướng dẫn này mô tả cách hỗ trợ bản cập nhật trong ứng dụng bằng Unity. Sẽ có hướng dẫn riêng cho các trường hợp mà quá trình 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à các trường hợp mà quá trình triển khai sử dụng mã gốc (C/C++).

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

Tải bản phát hành mới nhất của Trình bổ trợ Unity của Play để cập nhật trong ứng dụng từ các gói Google dành cho Unity.

Lưu ý: Việc tải xuống và sử dụng Trình bổ trợ Unity của Google Play phải tuân thủ Điều khoản dịch vụ của Bộ phát triển phần mềm Play Core. Bằng việc tải xuống và sử dụng Trình bổ trợ Unity của Google Play, bạn đồng ý với Điều khoản dịch vụ của Bộ phát triển phần mềm Play Core.

Tổng quan về SDK Unity

Play In-App Update API thuộc nhóm SDK Play Core. Trình bổ trợ Unity có một lớp AppUpdateManager để xử lý giao tiếp giữa ứng dụng của bạn và Play API. Bạn phải tạo thực thể lớp này thì mới có thể sử dụng để quản lý các bản cập nhật trong ứng dụng:

AppUpdateManager appUpdateManager = new AppUpdateManager();

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 AppUpdateManager để kiểm tra xem có bản cập nhật trong coroutine hay không:

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.
  }
}

Thực thể AppUpdateInfo được trả về chứa trạng thái sẵn có của bản cập nhật. Nếu quá trình cập nhật trong ứng dụng đang diễn ra, thực thể đó cũng báo cáo trạng thái của quá trình 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 ClientVersionStalenessDays để kiểm tra đã bao nhiêu ngày đã trôi qua kể từ khi bản cập nhật đó có trên Cửa hàng Play:

var stalenessDays = appUpdateInfoOperation.ClientVersionStalenessDays;

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 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 API Nhà phát triển Google Play như mô tả trong tài liệu về API Nhà phát triển Play. 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 UpdatePriority:

var priority = appUpdateInfoOperation.UpdatePriority;

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

Sau khi đảm bảo rằng đã có bản cập nhật, bạn có thể yêu cầu cập nhật bằng cách sử dụng AppUpdateManager.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 AppUpdateInfo đã cập nhật. Bạn cũng phải tạo một đối tượng AppUpdateOptions để đị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 AppUpdateOptions cho quy trình cập nhật ngay:

// Creates an AppUpdateOptions defining an immediate in-app
// update flow and its parameters.
var appUpdateOptions = AppUpdateOptions.ImmediateAppUpdateOptions();

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

// Creates an AppUpdateOptions defining a flexible in-app
// update flow and its parameters.
var appUpdateOptions = AppUpdateOptions.FlexibleAppUpdateOptions();

Đối tượng AppUpdateOptions cũng chứa trường AllowAssetPackDeletion xác định liệu quá trình 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ị hạn chế hay không. Trường này được đặt thành false theo mặc định. Tuy nhiên, bạn có thể truyền đối số (không bắt buộc) allowAssetPackDeletion đến ImmediateAppUpdateOptions() hoặc FlexibleAppUpdateOptions() để đặt trường này thành 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);

Lưu ý: Hãy cẩn thận khi sử dụng lựa chọn API AllowAssetPackDeletion để tránh việc vô tình xoá tài sản. Trước khi đặt lựa chọn này thành true, bạn nên kiểm tra AppUpdateManager.IsUpdateTypeAllowed() để đảm bảo đã đặt lựa chọn AllowAssetPackDeletion thành false.

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ý quá trình cập nhật linh hoạt

Sau khi có đối tượng AppUpdateInfo đã cập nhật và đối tượng AppUpdateOptions được định cấu hình đúng cách, bạn có thể gọi AppUpdateManager.StartUpdate() để yêu cầu không đồng bộ (asynchronously request) một quy trình cập nhật.

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

}

Đố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 AppUpdateManager.CompleteUpdate(), như trong ví dụ sau:

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

Xử lý quá trình cập nhật ngay

Sau khi có đối tượng AppUpdateInfo đã cập nhật và đối tượng AppUpdateOptions được định cấu hình đúng cách, bạn có thể gọi AppUpdateManager.StartUpdate() để yêu cầu không đồng bộ (asynchronously request) một quy trình cập nhật.

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

Đố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 StartUpdate() gửi ArgumentNullException, điều đó có nghĩa là AppUpdateInfo rỗng. Đảm bảo rằng đối tượng AppUpdateInfo được trả về từ GetAppUpdateInfo() không rỗng trước khi bắt đầu quy trình cập nhật.
• Nếu PlayAsyncOperation trả về mã lỗi ErrorUpdateUnavailable, hãy đảm bảo rằng có một phiên bản ứng dụng cập nhật có cùng khoá ký và ID ứng dụng.
• Nếu PlayAsyncOperation trả về mã lỗi ErrorUpdateNotAllowed, thì có nghĩa là đối tượng AppUpdateOptions 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ó. Trước khi bắt đầu quy trình cập nhật, hãy kiểm tra đối tượng AppUpdateInfo để 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.