透過 Play 遊戲電腦版 SDK,您可以存取 Google Play 服務,在電腦上建構遊戲並營利。使用 Play 結帳服務銷售數位內容、透過 Play 遊戲流暢登入,以及使用 Play Integrity 驗證使用者是否擁有應用程式的有效授權。
如要概略瞭解即將推出的功能、穩定版,以及整合架構,請參閱「Play Games 電腦版發展藍圖」。
準備踏出第一步了嗎?
必要條件
在 Play 管理中心內建立應用程式項目,並聲明 Play 套件名稱。
下載並安裝 Google Play Games 電腦版,然後登入 Google 帳戶。
步驟 1:將 SDK 新增至專案
C++
將 API 標頭資料夾
includes/複製到應用程式的程式碼庫。根據目標架構,將可轉散發的檔案從
imports/目錄複製到應用程式專案:64 位元 (x64):從
imports/x64/複製檔案。32 位元 (x86):從
imports/x86/複製檔案。連結專案,
play_pc_sdk.lib允許存取play_pc_sdk.dll的內容。
C#
以 tar 檔案 (
.tgz) 形式下載 Play 遊戲電腦版 Unity SDK。SDK 以與 Unity Package Manager (UPM) 相容的 tar 檔案 (
.tgz) 形式發布。如要匯入套件,請參閱「從本機 tar 檔案安裝 UPM 套件」一文。如需詳細說明文件、設定操作說明和其他指引,請參閱「Play PC Unity Package」頁面。
步驟 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 互動的遊戲程序。
Google Play Games 電腦版直接啟動的程序必須驗證Play Games 電腦版 SDK 是否已成功初始化。
這樣一來,系統就能盡快顯示錯誤,提供最佳使用者體驗。請注意,除了直接啟動的程序外,使用 SDK 的子程序也必須執行初始化作業。
如要在子程序中使用 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 遊戲電腦版啟動的遊戲程序,將收到的命令列參數轉送至子程序。遊戲停止執行時,結束所有程序。
如果使用者關閉遊戲,或遊戲因 SDK 初始化失敗 (例如
kActionRequiredShutdownClientProcess) 而結束,請關閉遊戲衍生的所有程序。這樣一來,下次透過 Google Play 遊戲電腦版用戶端啟動遊戲時,系統就會套用新變更,例如切換至其他有效帳戶。
後續步驟
在 IDE 中開發時使用 SDK:
- 啟用開發人員模式
在應用程式中新增 Google Play 電腦版功能:
- 透過 Play 帳款服務銷售數位商品
- 使用 Play Install Referrer 評估行銷成效
- 使用 Play Integrity for PC 保護遊戲