使用 Play 遊戲電腦版 SDK 強化遊戲

透過 Play 遊戲電腦版 SDK，您可以存取 Google Play 服務，在電腦上建構遊戲並營利。使用 Play 結帳服務銷售數位內容、透過 Play 遊戲流暢登入，以及使用 Play Integrity 驗證使用者是否擁有應用程式的有效授權。

準備踏出第一步了嗎？

必要條件

• 在 Play 管理中心內建立應用程式項目，並聲明 Play 套件名稱。

• 下載並安裝 Google Play Games 電腦版，然後登入 Google 帳戶。

步驟 1：將 SDK 新增至專案

步驟 2：新增資訊清單檔案

如要在遊戲中使用 SDK，您必須先將遊戲可執行檔與您在 Play 管理中心聲明的 Play 套件名稱建立關聯。方法是在遊戲可執行檔的相同目錄中新增 manifest.xml 檔案。

範例 manifest.xml 內容：

<?xml version="1.0" encoding="utf-8"?>
<Manifest version="1">
    <Application>
        <PackageName>com.example.package</PackageName>
    </Application>
</Manifest>

manifest.xml 刊登位置範例：

C:\Program Files
└───Example Game
    ├───Game.exe
    └───manifest.xml

步驟 3：以數位方式簽署遊戲

遊戲必須先使用 Authenticode 數位簽章進行數位簽署，才能使用 SDK。如需簽署可執行檔的操作說明，請參閱 SignTool 說明文件。

完成遊戲的數位簽署程序後，請將憑證資訊傳送給 Google 代表進行設定。

步驟 4：初始化 SDK

在遊戲的啟動序列期間初始化 SDK。這項操作應自動完成，不需要任何使用者互動，建議您先驗證初始化是否成功，再算繪遊戲視窗。這樣做可盡快顯示並解決錯誤，提供最佳使用者體驗，並避免遊戲程序需要結束時，遊戲視窗短暫顯示。

呼叫 GooglePlayInitialize (C++)/GooglePlayInitialization.InitializeAsync (C#) 初始化 API，即可開始使用 SDK。這會設定全域狀態、連線至 SDK 執行階段，並驗證應用程式是否正確啟動。必須先呼叫這個函式，並讓後續回呼完成，且 InitializeResult::ok() (C++) / Result.IsOk (C#) 等於 true，才能使用任何其他 API。

  // Initialize the SDK as part of the startup sequence of your application.
  auto promise = std::make_shared<std::promise<InitializeResult>>();
  GooglePlayInitialize(
    [promise](InitializeResult result) {
      promise->set_value(std::move(result));
    });

  auto initialize_result = promise->get_future().get();
  if (initialize_result.ok()) {
    // The SDK succeeded with initialization. Continue with the startup sequence
    // of the game.
    // ...
  } else if (initialize_result.code() == InitializationError::kActionRequiredShutdownClientProcess) {
    // The SDK failed to initialize and has requested that your game process exit
    // as soon as possible.
    exit(1);
  } else {
    // The SDK failed to initialize for an alternative reason. It is still
    // generally recommended that you exit the game process as soon as possible,
    // because it won't be possible to access any APIs in the SDK. Critical
    // operations such as verifying the user owns a valid license to your game
    // won't be possible.
    // ...
  }

  // SDK Clients
  private BillingClient _billingClient;
  private IntegrityClient _integrityClient;

  // Stored product information
  private string _offerToken;

  private async void InitializeSDK()
  {
      // The factory provides the necessary handler for initialization.
      var initializationHandler = PlayPcSdkFactory.InitializationHandler;
      var result = await GooglePlayInitialization.InitializeAsync(initializationHandler);

      if (result.IsOk)
      {
          // Use the factory to get Unity-compatible instances of the clients
          _billingClient = PlayPcSdkFactory.CreateBillingClient();
          _integrityClient = PlayPcSdkFactory.CreateIntegrityClient();

          // SDK is ready for use
      }
      else
      {
          // Handle specific, actionable errors
          if (result.Code == InitializationError.ActionRequiredShutdownClientProcess)
          {
              Log("This game must be launched through the Google Play Games client. Please exit all game processes immediately, GPG will relaunch the game safely.");
              Application.Quit();
          }
      }
  }

如果初始化失敗，並顯示 kActionRequiredShutdownClientProcess (C++) / InitializationError.ActionRequiredShutdownClientProcess (C#) 程式碼，請盡快結束遊戲程序。SDK 的執行階段會嘗試協助使用者，您的遊戲不必採取任何額外動作。舉例來說，如果使用者沒有遊戲的有效授權，Google Play Games 會提示使用者購買副本。發生其他錯誤時，您也應該結束遊戲程序，因為您無法使用 SDK 執行重要作業，例如驗證使用者是否擁有遊戲的有效授權。

如果回應不成功，可能表示出現下列其中一種情況：

• SDK 執行階段未安裝、未在裝置上執行，或是版本較舊，與整合至遊戲的 SDK 不相容。

• SDK 執行階段無法驗證遊戲的應用程式身分。這可能是因為 manifest.xml 無效，或是在開發時使用 SDK 但未啟用開發人員模式。如果沒有這個模式，遊戲的可執行檔就必須使用向 Play 套件名稱註冊的數位憑證進行數位簽章。

• 遊戲可執行檔並非透過 Google Play 遊戲用戶端啟動。

• Google Play 遊戲中的活躍使用者沒有應用程式授權。

步驟 5：(選用) 支援多個遊戲程序

如果遊戲使用多個程序，且 Play 遊戲電腦版 SDK 由 Google Play 遊戲電腦版啟動的程序以外的程序使用，請完成下列額外的整合步驟。舉例來說，如果 Google Play 遊戲電腦版啟動遊戲的啟動器，然後啟動器啟動將與 SDK 互動的遊戲程序。

1. Google Play Games 電腦版直接啟動的程序必須驗證Play Games 電腦版 SDK 是否已成功初始化。

   這樣一來，系統就能盡快顯示錯誤，提供最佳使用者體驗。請注意，除了直接啟動的程序外，使用 SDK 的子程序也必須執行初始化作業。

2. 如要在子程序中使用 Play Games 電腦版 SDK，請將指令列參數轉送至產生的子程序。

   指令列參數轉送範例：

   Processes hierarchy tree:
   
   GooglePlayGames.exe
   └───YourGameLauncher.exe --gpg_args=abc --your_args=123
       └───YourGame.exe --gpg_args=abc --your_args=123
   

   在這個範例中，我們看到程序階層，其中 Google Play Games 電腦版 (GooglePlayGames.exe) 會啟動遊戲 (YourGameLauncher.exe)，並提供一些範例參數 (--gpg_args=abc --your_args=123)。接著，遊戲會產生使用 Play Games 電腦版 SDK 的子程序 (YourGame.exe)。為允許這項操作，Google Play Games 電腦版啟動的遊戲程序會將收到的指令列參數轉送至子程序。

3. 遊戲停止執行時，結束所有程序。

   如果使用者關閉遊戲，或遊戲因 SDK 初始化失敗 (例如 kActionRequiredShutdownClientProcess) 而結束，請關閉遊戲衍生的所有程序。這樣一來，下次透過 Google Play 遊戲電腦版用戶端啟動遊戲時，系統就會套用新變更，例如切換至其他有效帳戶。

後續步驟

在 IDE 中開發時使用 SDK：

• 啟用開發人員模式

在應用程式中新增 Google Play 電腦版功能：

• 透過 Play 帳款服務銷售數位商品
• 使用 Play 安裝參照連結網址評估行銷成效
• 使用 Play Integrity for PC 保護遊戲