支援應用程式內更新 (Unity)

本指南說明如何使用 Unity 支援應用程式中的應用程式內更新。針對您的實作使用 Kotlin 程式設計語言或 Java 程式設計語言的情況，以及您的實作使用原生程式碼 (C/C++)的情況，有專屬的指南。

設定開發環境

從 Unity 的 Google 套件下載最新版本的 Play 應用程式內更新 Unity 外掛程式。

Unity SDK 總覽

Play 應用程式內更新 API 屬於 Play Core SDK 系列的一部分。Unity 外掛程式提供 AppUpdateManager 類別可處理應用程式與 Play API 之間的通訊。您必須先建立此類別，才能使用此類別來管理應用程式內更新：

AppUpdateManager appUpdateManager = new AppUpdateManager();

檢查是否有可用的更新

在要求更新之前，請先檢查您的應用程式是否有可用的更新，使用 AppUpdateManager 檢查協同程式中的更新：

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

回傳的 AppUpdateInfo 執行個體含有可用更新的狀態。如果已在進行應用程式內更新，則執行個體也會報告正在進行中的更新狀態。

檢查更新是否過時

除了檢查是否有可用的更新，建議您也同時確認自從使用者上次收到 Play 商店的更新通知後已過了多久。這可以幫助您判斷是否要啟動彈性更新還是立即更新。例如，您可以等待幾天再通知使用者進行彈性更新，接著過幾天後提出需要立即更新。

您可以利用 ClientVersionStalenessDays 查看透過 Play 商店推出更新的天數。

var stalenessDays = appUpdateInfoOperation.ClientVersionStalenessDays;

檢查更新的優先順序

您可以透過 Google Play Developer API 設定每項更新的優先順序。應用程式可藉此判斷向使用者建議更新的強烈程度。舉例來說，您可以運用下列策略設定更新的優先程度：

  • 使用者介面微幅調整：低度優先等級更新；不需要提出彈性更新和立即更新。
  • 效能提升：中度優先等級更新；要求彈性更新。
  • 重大安全性更新：高度優先等級更新；要求立即更新。

為了判定優先等級，Google Play 使用一個介於 0 到 5 之間的整數值，其中 0 是預設值，5 是最高優先順序。如要設定更新的優先等級，請使用 Google Play Developer API 中 Edits.tracks.releases 下的 inAppUpdatePriority 欄位。系統會將此發行版本中所有新增版本的優先等級視同此發行版本的優先等級。只有在推出新的發行版本時才能設定優先等級，而且日後無法更改。

請按照 Play Developer API 說明文件所述，使用 Google Play Developer API 設定優先順序。請在 Edit.tracks: update 方法傳遞的 Edit.tracks 資源中指定應用程式內更新的優先等級。以下範例說明如何發布版本為 88 和 inAppUpdatePriority 5 的應用程式：

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

在應用程式的程式碼中，您可以使用 UpdatePriority 查看特定更新的優先順序等級：

var priority = appUpdateInfoOperation.UpdatePriority;

開始更新

確認有可用的更新後，您可以使用 AppUpdateManager.StartUpdate() 要求更新。提出更新要求前，請確認您已經取得最新的 AppUpdateInfo 物件。您還必須建立 AppUpdateOptions 物件來設定更新流程。

以下範例針對即時更新流程建立 AppUpdateOptions 物件：

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

以下範例針對彈性更新流程建立 AppUpdateOptions 物件：

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

AppUpdateOptions 物件也包含 AllowAssetPackDeletion 欄位，可用於定義是否允許更新在裝置儲存空間有限的情況下清除資產包。此欄位預設為 false，但您可以將 allowAssetPackDeletion 選用引數傳送至 ImmediateAppUpdateOptions() 或 FlexibleAppUpdateOptions()，將其設為 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);

後續步驟取決於您要求的是彈性更新，還是立即更新。

處理彈性更新

取得最新的 AppUpdateInfo 物件和正確設定的 AppUpdateOptions 物件後，您可以呼叫 AppUpdateManager.StartUpdate() 以非同步要求更新流程。

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

}

為提供彈性更新流程，您必須在下載完成後成功觸發應用程式安裝更新。方法是呼叫 AppUpdateManager.CompleteUpdate()，如下列範例所示：

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

處理立即更新

取得最新的 AppUpdateInfo 物件和正確設定的 AppUpdateOptions 物件後，您可以呼叫 AppUpdateManager.StartUpdate() 以非同步要求更新流程。

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

針對立即更新流程，Google Play 會顯示使用者確認對話方塊。使用者接受要求後，Google Play 會自動下載並安裝更新，並在安裝成功後重新啟動更新版的應用程式。

處理錯誤

本節將說明常見錯誤的解決方法。

  • 如果 StartUpdate() 擲出 ArgumentNullException，表示 AppUpdateInfo 為空值。開始執行更新流程之前，請確認 GetAppUpdateInfo() 回傳的 AppUpdateInfo 物件並非空值。
  • 如果 PlayAsyncOperation 回傳 ErrorUpdateUnavailable 錯誤代碼，請確認已更新的應用程式版本使用相同的應用程式 ID 和簽署金鑰。
  • 如果 PlayAsyncOperation 回傳 ErrorUpdateNotAllowed 錯誤代碼，意味著 AppUpdateOptions 物件表示可用更新不適用的更新類型。啟動更新流程之前，請檢查 AppUpdateInfo 物件是否指示所選的更新類型已獲准。

後續步驟

測試應用程式的應用程式內更新，以確認整合作業是否正常運作。