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

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

心動了嗎？

必要條件

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

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

步驟 1：將 SDK 新增至專案

  • 下載 Play 遊戲電腦版 C++ SDK。

  • 將 API 標頭資料夾 includes/ 複製到應用程式的程式碼庫。

  • 將可轉散發的檔案從 imports/ 複製到應用程式的專案。

    • 將專案連結至 play_pc_sdk.lib，允許存取 play_pc_sdk.dll 的內容。

步驟 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 說明文件。

步驟 4：初始化 SDK

在遊戲的啟動序列期間初始化 SDK。這項作業應自動完成，不需要任何使用者互動。建議您先確認初始化作業是否成功，再顯示遊戲視窗。這樣一來，系統就能盡快找出並解決錯誤，提供最佳使用者體驗。此外，如果遊戲程序需要結束，也能避免遊戲視窗短暫顯示。

呼叫 GooglePlayInitialize 初始化 API，即可開始使用 SDK。這會設定全域狀態、連線至 SDK 執行階段，並驗證應用程式是否已正確啟動。必須先呼叫這個函式，並讓後續回呼完成，且 InitializeResult::ok() 等於 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.
  // ...
}

如果初始化失敗並顯示 kActionRequiredShutdownClientProcess 代碼，請盡快結束遊戲程序。SDK 的執行階段會嘗試協助使用者，您的遊戲無須採取其他行動。舉例來說，如果使用者沒有遊戲的有效授權，Google Play 遊戲就會提示使用者購買副本。如果發生其他錯誤，我們仍建議盡快結束遊戲程序，因為遊戲無法使用 SDK 執行重要作業，例如驗證使用者是否擁有遊戲的有效授權。

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

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

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

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

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

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

如果遊戲使用多個程序，並打算從 Google Play 遊戲電腦版未直接啟動的程序使用 Play 遊戲電腦版 SDK，則需要採取額外的整合步驟：

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

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

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

    指令列參數轉送範例：

    Processes hierarchy tree:

GooglePlayGames.exe
└───YourGameLauncher.exe --foo=abc --bar=123
    └───YourGame.exe --foo=abc --bar=123

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

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

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

後續步驟

在 IDE 中開發時使用 SDK：

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