บริการเกมของ Play สำหรับ C++
จัดทุกอย่างให้เป็นระเบียบอยู่เสมอด้วยคอลเล็กชัน
บันทึกและจัดหมวดหมู่เนื้อหาตามค่ากำหนดของคุณ
เราจะนำ SDK เวอร์ชัน 1 ของเกมออกในปี 2026 ตามการเลิกใช้งาน Google Sign-In API หลังจากเดือนกุมภาพันธ์ 2025 คุณจะไม่สามารถเผยแพร่เกมที่ผสานรวมกับ SDK เวอร์ชัน 1 ของเกมใหม่ใน Google Play เราขอแนะนําให้ใช้ SDK ของ Google Play Games v2 แทน
แม้ว่าเกมที่มีอยู่ซึ่งผสานรวมกับเกมเวอร์ชัน 1 ก่อนหน้านี้จะยังคงใช้งานได้อีก 2-3 ปี แต่เราขอแนะนำให้คุณย้ายข้อมูลไปยัง v2 ตั้งแต่วันที่ 1 มิถุนายน 2025 เป็นต้นไป
คู่มือนี้มีไว้สำหรับการใช้ SDK บริการเกมของ Play เวอร์ชัน 1 SDK สำหรับ C++ ของบริการเกมของ Play เวอร์ชัน 2 ยังไม่พร้อมใช้งาน
SDK สำหรับ C++ ของบริการเกม Google Play มี C++ API สำหรับใช้กับบริการเกม Google Play และเหมาะสำหรับนักพัฒนาแอปที่มีการใช้งาน C++ ในเกมอยู่แล้ว
ปัจจุบัน SDK ใช้บริการต่อไปนี้
- การให้สิทธิ์
- ความสำเร็จ
- ลีดเดอร์บอร์ด
- กิจกรรม
- เกมที่บันทึกไว้
- การเชื่อมต่อใกล้เคียง (Android เท่านั้น)
- สถิติผู้เล่น
แนวคิด
ขั้นตอนคร่าวๆ ในการใช้ SDK มีดังนี้
- ตั้งค่าการกำหนดค่าแพลตฟอร์มสำหรับ Android
- ใช้
GameServices::Builder เพื่อกําหนดค่าและสร้างออบเจ็กต์ GameServices
ออบเจ็กต์ GameServices จะพยายามลงชื่อเข้าใช้โดยอัตโนมัติและแสดงผลลัพธ์ผ่าน OnAuthActionFinished() callback จดผลลัพธ์ที่ได้จากระบบเรียกกลับ หากพยายามลงชื่อเข้าใช้อัตโนมัติไม่สำเร็จ คุณสามารถแสดงปุ่มเพื่อให้ผู้ใช้ลงชื่อเข้าใช้ได้
หลังจากได้รับผลลัพธ์ OnAuthActionFinished() แล้ว คุณจะใช้ออบเจ็กต์ GameServices และผู้จัดการย่อยเพื่อเรียกใช้บริการ Play Games ได้ ดังนี้
- ลงชื่อเข้าใช้ (หลังจากให้สิทธิ์ไม่สำเร็จ):
StartAuthorizationUI()
- ปลดล็อกรางวัลพิเศษ:
Achievements().Unlock()
- แสดงรางวัลพิเศษโดยใช้ UI ในตัว:
Achievements().ShowAllUI()
- ส่งคะแนนสูงสุด:
Leaderboards().SubmitScore()
- ออกจากระบบ:
SignOut()
เมื่อใช้ออบเจ็กต์ GameServices เสร็จแล้ว ให้รีเซ็ตหรือทำลายออบเจ็กต์
ในระดับรายละเอียดมากขึ้น
เริ่มต้นการกำหนดค่าแพลตฟอร์ม: นี่คือออบเจ็กต์ที่มีข้อมูลการเริ่มต้นเฉพาะแพลตฟอร์ม ใน Android การกําหนดค่าแพลตฟอร์มประกอบด้วย VM ของ Java และเคอร์เซอร์ไปยัง 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);
สร้างออบเจ็กต์ GameServices: ออบเจ็กต์นี้เป็นจุดแรกเข้าหลักสำหรับฟังก์ชันการทำงานของบริการเกมของ Google Play GameServices อินสแตนซ์สร้างขึ้นด้วย GameServices::Builder
ในการใช้งานส่วนใหญ่ ออบเจ็กต์ GameServices หนึ่งๆ จะยังคงอยู่ตราบใดที่สภาพแวดล้อม C ยังคงอยู่ คุณไม่จําเป็นต้องเริ่มต้นใหม่เมื่อ 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);
ใช้คลาสตัวจัดการเพื่อจัดการออบเจ็กต์ GameServices ผู้จัดการจะเข้าถึงได้จากอินสแตนซ์ GameServices และฟังก์ชันการทำงานที่เกี่ยวข้องกับกลุ่มร่วมกัน ตัวอย่างของฟีเจอร์เหล่านี้ ได้แก่ เครื่องมือจัดการรางวัลพิเศษและลีดเดอร์บอร์ด โดยไม่มีสถานะที่ผู้ใช้มองเห็น ระบบจะแสดงผลผู้จัดการตามการอ้างอิง และอินสแตนซ์ GameServices ที่รวมอยู่จะควบคุมวงจรชีวิตของผู้จัดการ ลูกค้าไม่ควรเก็บข้อมูลอ้างอิงผู้จัดการไว้ แต่ลูกค้าควรเก็บอินสแตนซ์ GameServices ไว้
ผู้จัดการจะแสดงผลข้อมูลผ่านออบเจ็กต์ประเภทค่าแบบคงที่ ค่าเหล่านี้แสดงมุมมองที่สอดคล้องกันของข้อมูลพื้นฐาน ณ เวลาที่มีการค้นหา
// Submit a high score
game_services_->Leaderboards().SubmitScore(leaderboard_id, score);
// Show the default Achievements UI
game_services_->Achievements().ShowAllUI();
เมื่อใช้ออบเจ็กต์ GameServices เสร็จแล้ว ให้ล้างข้อมูลโดยเรียกใช้ reset() ใน unique_ptr ที่เป็นเจ้าของ หรือปล่อยให้ unique_ptr ทำลายออบเจ็กต์โดยอัตโนมัติเมื่ออยู่นอกขอบเขต
รูปแบบการต่อด้าย
เว้นแต่จะระบุไว้เป็นอย่างอื่น เมธอด GameServices และ Manager ทั้งหมดมีการใช้งานแบบไม่พร้อมกันที่ปลอดภัยสำหรับเธรด เรียกใช้บนเธรดใดก็ได้โดยไม่ต้องล็อกภายนอก และจะดำเนินการตามลำดับที่สอดคล้องกับลําดับการเรียกใช้
เมธอดการเข้าถึง (เมธอดที่อ่านสถานะ) มี 2 รูปแบบหลักๆ เมธอดประเภทแรก (ที่มีชื่ออย่างเช่น FetchProperty()) จะส่งผลลัพธ์แบบไม่พร้อมกันไปยังการเรียกกลับที่ระบุไว้ ส่วนเมธอดประเภทที่ 2 (ที่มีชื่ออย่างเช่น 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" ของแพลตฟอร์ม นอกจากนี้ คุณควรตรวจสอบด้วยว่าระบบเรียกกลับของผู้ใช้ทำงานอย่างรวดเร็ว เนื่องจากเธรดการเรียกกลับที่หยุดชะงักอาจทำให้เกิดปัญหาที่ผู้ใช้มองเห็นได้ (เช่น คำขอออกจากระบบที่ดำเนินการเสร็จล่าช้า)
หากต้องการเริ่มต้นใช้งาน Play Games C++ SDK บน Android ให้ไปที่คู่มือเริ่มต้นใช้งานฉบับย่อ
อ่านเพิ่มเติม
โปรดอ่านเอกสารประกอบของคลาสที่มาพร้อมกับ SDK สำหรับ C++ ของบริการเกมของ Google Play เพื่อดูรายละเอียดเพิ่มเติม และดูตัวอย่างที่สาธิตวิธีใช้ SDK
หากเกมใช้เซิร์ฟเวอร์แบ็กเอนด์ โปรดดูหัวข้อการเปิดใช้การเข้าถึงฝั่งเซิร์ฟเวอร์ไปยังบริการเกมของ Google Play
ตัวอย่างเนื้อหาและโค้ดในหน้าเว็บนี้ขึ้นอยู่กับใบอนุญาตที่อธิบายไว้ในใบอนุญาตการใช้เนื้อหา Java และ OpenJDK เป็นเครื่องหมายการค้าหรือเครื่องหมายการค้าจดทะเบียนของ Oracle และ/หรือบริษัทในเครือ
อัปเดตล่าสุด 2025-07-26 UTC
[null,null,["อัปเดตล่าสุด 2025-07-26 UTC"],[],[],null,["# Play Games Services for C++\n\nFollowing the deprecation of the\n[Google Sign-In](https://android-developers.googleblog.com/2024/09/streamlining-android-authentication-credential-manager-replaces-legacy-apis.html)\nAPI, we are removing the games v1 SDK in 2026. After February 2025, you will be unable to publish\ntitles that are newly integrated with games v1 SDK, on Google Play. We recommend that you use the\ngames v2 SDK instead. \n\nWhile existing titles with the previous games v1 integrations continue to function for a\ncouple of years, you are encouraged to\n[migrate to v2](/games/pgs/android/migrate-to-v2)\nstarting June 2025. \n\nThis guide is for using the Play Games Services v1 SDK. The C++ SDK for\nPlay Games Services v2 is not yet available.\n\nThe Google Play games Services C++ SDK provides a C++ API for use with Google Play Game\nservices, and is meant for developers who have an existing C++ implementation\nof their game.\n\nCurrently, the SDK implements the following services:\n\n- Authorization\n- Achievements\n- Leaderboards\n- Events\n- Saved Games\n- Nearby Connections (Android only)\n- Player Statistics\n\nConcepts\n--------\n\nAt a high level, you use the SDK by following these steps:\n\n1. Set up a platform configuration for Android.\n2. Use a `GameServices::Builder` to configure and construct a `GameServices` object. The `GameServices` object automatically attempts to sign in, and returns the result via an `OnAuthActionFinished()` callback. Take note of the result returned by the callback. If the automatic sign-in attempt failed, you can display a button to let users sign in.\n3. After receiving the `OnAuthActionFinished()` result, you can use the\n `GameServices` object and its child Managers to make Play Games services calls,\n including:\n\n - Sign in (after authorization fails): `StartAuthorizationUI()`\n - Unlock achievements: `Achievements().Unlock()`\n - Show achievements using built-in UI: `Achievements().ShowAllUI()`\n - Submit a high score: `Leaderboards().SubmitScore()`\n - Sign out: `SignOut()`\n4. When you are done using the `GameServices` object, reset or destroy it.\n\nAt a more detailed level:\n\n1. Initialize a platform configuration: This is an object that contains\n platform-specific initialization information. On Android, the platform configuration contains the\n Java VM and a pointer to the current `Activity`:\n\n // In android_main(), create a platform configuration\n // and bind the object activity.\n // Alternately, attach the activity in JNI_Onload().\n gpg::AndroidPlatformConfiguration platform_configuration;\n platform_configuration.SetActivity(state-\u003eactivity-\u003eclazz);\n\n2. Construct a `GameServices` object: This object is the main entry point for\n Google Play games Services functionality. `GameServices` instances are created\n with `GameServices::Builder`.\n\n In most implementations, a given `GameServices` object will persist as long as\n your C environment does; you do not need to reinitialize it when your\n Android `Activity` pauses and resumes. \n\n // Creates a GameServices object that has lambda callbacks.\n game_services_ = gpg::GameServices::Builder()\n .SetDefaultOnLog(gpg::LogLevel::VERBOSE)\n .SetOnAuthActionStarted([started_callback](gpg::AuthOperation op) {\n is_auth_in_progress_ = true;\n started_callback(op);\n })\n .SetOnAuthActionFinished([finished_callback](gpg::AuthOperation op,\n gpg::AuthStatus status) {\n LOGI(\"Sign in finished with a result of %d\", status);\n is_auth_in_progress_ = false;\n finished_callback(op, status);\n })\n .Create(pc);\n\n3. Use the Manager classes to manage your `GameServices` object. Managers are accessed from a `GameServices` instance and group related functionality\n together. Examples of these\n include the Achievement and Leaderboard Managers. They contain no user-visible\n state themselves. Managers are returned by reference, and the containing\n `GameServices` instance controls their lifecycle. Your client should never hold\n onto a Manager reference. Instead, your client should hold on to the\n `GameServices` instance.\n\n Managers return data via immutable value type objects. These values\n reflect a consistent view of the underlying data at the point in time when\n the query was made. \n\n // Submit a high score\n game_services_-\u003eLeaderboards().SubmitScore(leaderboard_id, score);\n\n // Show the default Achievements UI\n game_services_-\u003eAchievements().ShowAllUI();\n\n4. When you are finished using the `GameServices` object, clean up by\n calling `reset()` on the `unique_ptr` that owns it, or by letting the\n `unique_ptr` automatically destroy it when going out of scope.\n\nThreading model\n---------------\n\nUnless otherwise noted, all `GameServices` and Manager methods have\nthread-safe, asynchronous implementations. They can be called on any thread without\nexternal locking, and will execute in an order consistent with their invocation\norder.\n\nAccessor methods (those that read state) come in two major variants. The first\ntype of method (with names like `FetchProperty()`) asynchronously supplies its results\nto a provided callback; the second (with names like\n`FetchPropertyBlocking()`) synchronously returns its results to the calling\nthread. \n\n // Blocking callback\n gpg::AchievementManager::FetchAllResponse fetchResponse =\n game_services_-\u003eAchievements().FetchAllBlocking(std::chrono::milliseconds(1000));\n\n // Non-blocking callback\n game_services_-\u003eAchievements().FetchAll(gpg::DataSource::CACHE_OR_NETWORK,\n [] (gpg::AchievementManager::FetchAllResponse response) {\n LogI(\"Achievement response status: %d\", response.status);});\n\nAll user callbacks are invoked on a dedicated callback thread. This thread is\npotentially distinct from any platform concept of a \"main thread\" or \"UI\nthread\". You should also try to ensure that user callbacks execute quickly; a stalled callback thread\nmay cause user-visible issues (for example, delayed completion of a sign-out\nrequest).\n\nPlatform-specific information\n-----------------------------\n\nTo get started using the Play Games C++ SDK on Android, continue to the\n[quickstart guide](/games/pgs/v1/cpp/quickstart).\n\nFurther reading\n---------------\n\nBe sure to read the class documentation that comes in the Google Play Game\nservices C++ SDK for further details, and check out the\n[samples](https://github.com/playgameservices/) that demonstrate how to use the SDK.\n\nIf your game uses a backend server, see\n[Enabling Server-Side Access to Google Play Games Services](/games/pgs/v1/android/server-access)."]]
