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

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

如要概略瞭解即將推出的功能、穩定版,以及整合架構,請參閱「Play Games 電腦版發展藍圖」。

準備踏出第一步了嗎?

必要條件

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

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

步驟 1:將 SDK 新增至專案

C++

  • 下載 Play Games 電腦版 C++ SDK。

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

  • 根據目標架構,將可轉散發的檔案從 imports/ 目錄複製到應用程式專案:

  • 64 位元 (x64):從 imports/x64/ 複製檔案。

  • 32 位元 (x86):從 imports/x86/ 複製檔案。

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

C#

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

您必須先將遊戲可執行檔與在 Play 管理中心聲明的 Play 套件名稱建立關聯,才能在遊戲中使用 SDK。方法是在遊戲可執行檔所在的目錄中新增 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。建議您在初始化期間,於 GooglePlayInitializeParams 中傳遞遊戲的 Android 套件名稱。這會設定全域狀態、連結至 SDK 執行階段,並驗證應用程式是否正確啟動。您必須呼叫此函式,並讓接續回呼完成,且 InitializeResult::ok() (C++) 或 Result.IsOk (C#) 等於 true,才能使用任何其他 API。

C++

// Initialize the SDK as part of the startup sequence of your
// application.
auto promise = std::make_shared<std::promise<InitializeResult>>();
GooglePlayInitializeParams params;
// Replace with your game's package name.
params.package_name = "com.example.game";
GooglePlayInitialize(
  [promise] (InitializeResult result) {
    promise->set_value(std::move(result));
  }, params);

auto initialize_result = promise->get_future().get();
if (initialize_result.ok()) {
  // The SDK succeeded with initialization. Continue with the startup
  // sequence of the game.
  // ...

  // Retrieve the operating environment and device form factor.
  auto env = initialize_result.value().environment;
  auto form_factor = initialize_result.value().form_factor;
  // ...
} 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.
  // ...
}

C#

// 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 initializeParams = new GooglePlayInitializeParams {
        // Replace with your game's package name.
        PackageName = "com.example.game"
    };
    var result = await GooglePlayInitialization.InitializeAsync(
        initializationHandler, initializeParams);

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

        // Retrieve the operating environment and device form factor.
        var env = result.Value.Environment;
        var form_factor = result.Value.FormFactor;

        // 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. 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 Games 中的有效使用者沒有應用程式授權。

步驟 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 遊戲電腦版 (GooglePlayGames.exe) 啟動遊戲 (YourGameLauncher.exe) 的程序階層,並附上一些範例參數 (--gpg_args=abc --your_args=123)。接著,遊戲會產生使用 Play 遊戲電腦版 SDK 的子程序 (YourGame.exe)。如要允許這項操作,請讓 Google Play 遊戲電腦版啟動的遊戲程序,將收到的命令列參數轉送至子程序。

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

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

後續步驟

在 IDE 中開發時使用 SDK:

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