C++ 適用的 Play 遊戲服務

Google 登入 API 淘汰後，我們將於 2026 年移除遊戲服務第 1 版 SDK。2025 年 2 月後，新整合遊戲服務第 1 版 SDK 的遊戲將無法在 Google Play 發布，建議改用遊戲服務第 2 版 SDK。
雖然整合舊版遊戲第 1 版的現有遊戲仍可運作幾年，但我們建議您自 2025 年 6 月起遷移至第 2 版。
本指南適用於 Play 遊戲服務第 1 版 SDK。Play 遊戲服務第 2 版的 C++ SDK 尚未推出。

Google Play 遊戲服務 C++ SDK 提供 C++ API，可搭配 Google Play 遊戲服務使用，適合遊戲已採用 C++ 實作的開發人員。

目前 SDK 會實作下列服務：

• 授權
• 成就
• 排行榜
• 事件
• 遊戲進度存檔
• Nearby Connections (僅限 Android)
• 玩家統計資料

概念

整體來說，使用 SDK 的步驟如下：

1. 設定 Android 的平台設定。
2. 使用 GameServices::Builder 設定及建構 GameServices 物件。GameServices 物件會自動嘗試登入，並透過 OnAuthActionFinished() 回呼傳回結果。請注意回呼傳回的結果。如果自動登入嘗試失敗，您可以顯示按鈕，讓使用者登入。

3. 收到 OnAuthActionFinished() 結果後，您可以使用 GameServices 物件及其子項管理工具呼叫 Play 遊戲服務，包括：

   • 登入 (授權失敗後)：StartAuthorizationUI()
   • 解鎖成就：Achievements().Unlock()
   • 使用內建 UI 顯示成就：Achievements().ShowAllUI()
   • 送出最高分：Leaderboards().SubmitScore()
   • 登出：SignOut()

4. 使用 GameServices 物件完畢後，請重設或銷毀該物件。

更詳細的說明如下：

1. 初始化平台設定：這是包含平台專屬初始化資訊的物件。在 Android 上，平台設定包含 Java VM 和目前 Activity 的指標：

   // In android_main(), create a platform configuration
   // and bind the object activity.
   // Alternately, attach the activity in JNI_Onload().
   gpg::AndroidPlatformConfiguration platform_configuration;
   platform_configuration.SetActivity(state->activity->clazz);
   

2. 建構 GameServices 物件：這個物件是 Google Play 遊戲服務功能的主要進入點。系統會使用 GameServices::Builder 建立 GameServices 執行個體。

   在大多數實作中，只要 C 環境持續存在，指定的 GameServices 物件就會持續存在；當 Android Activity 暫停及恢復時，您不需要重新初始化。

   // Creates a GameServices object that has lambda callbacks.
   game_services_ = gpg::GameServices::Builder()
           .SetDefaultOnLog(gpg::LogLevel::VERBOSE)
           .SetOnAuthActionStarted([started_callback](gpg::AuthOperation op) {
               is_auth_in_progress_ = true;
               started_callback(op);
           })
           .SetOnAuthActionFinished([finished_callback](gpg::AuthOperation op,
                                                        gpg::AuthStatus status) {
               LOGI("Sign in finished with a result of %d", status);
               is_auth_in_progress_ = false;
               finished_callback(op, status);
           })
           .Create(pc);
   

3. 使用管理工具類別管理 GameServices 物件。管理員可從 GameServices 執行個體存取，並將相關功能歸類在一起。例如成就和排行榜管理工具。本身不含任何使用者可見的狀態。管理員會依參照傳回，而包含的 GameServices 執行個體會控管其生命週期。您的用戶端絕不應保留管理員參照。因此，客戶應保留 GameServices 執行個體。

   管理員會透過不可變動的值型別物件傳回資料。這些值反映了查詢時基礎資料的一致性檢視畫面。

   // Submit a high score
   game_services_->Leaderboards().SubmitScore(leaderboard_id, score);
   
   // Show the default Achievements UI
   game_services_->Achievements().ShowAllUI();
   

4. 使用完 GameServices 物件後，請在擁有該物件的 unique_ptr 上呼叫 reset()，或讓 unique_ptr 在超出範圍時自動銷毀該物件，藉此進行清理。

執行緒模型

除非另有註明，否則所有 GameServices 和 Manager 方法都具有執行緒安全非同步實作。這些函式可在任何執行緒上呼叫，不需要外部鎖定，且會按照呼叫順序執行。

存取子方法 (讀取狀態的方法) 主要有兩種變體。第一種方法 (名稱類似 FetchProperty()) 會以非同步方式將結果提供給指定的回呼；第二種方法 (名稱類似 FetchPropertyBlocking()) 則會以同步方式將結果傳回給呼叫執行緒。

// Blocking callback
gpg::AchievementManager::FetchAllResponse fetchResponse =
        game_services_->Achievements().FetchAllBlocking(std::chrono::milliseconds(1000));

// Non-blocking callback
game_services_->Achievements().FetchAll(gpg::DataSource::CACHE_OR_NETWORK,
    [] (gpg::AchievementManager::FetchAllResponse response) {
    LogI("Achievement response status: %d", response.status);});

所有使用者回呼都會在專屬的回呼執行緒上叫用。這個執行緒可能與任何平台「主要執行緒」或「UI 執行緒」的概念不同。此外，您也應盡量確保使用者回呼快速執行；回呼執行緒停滯可能會導致使用者可見的問題 (例如登出要求延遲完成)。

平台專屬資訊

如要在 Android 上開始使用 Play 遊戲 C++ SDK，請參閱快速入門指南。

其他資訊

如需更多詳細資料，請務必閱讀 Google Play 遊戲服務 C++ SDK 隨附的類別說明文件，並查看範例，瞭解如何使用 SDK。

如果遊戲使用後端伺服器，請參閱「啟用 Google Play 遊戲服務的伺服器端存取功能」。