Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang
Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.
Sau khi ngừng sử dụng API Đăng nhập bằng Google, chúng tôi sẽ xoá SDK trò chơi phiên bản 1 vào năm 2026. Sau tháng 2 năm 2025, bạn sẽ không thể phát hành các trò chơi mới tích hợp với SDK trò chơi phiên bản 1 trên Google Play. Thay vào đó, bạn nên sử dụng SDK trò chơi v2.
Mặc dù các trò chơi hiện có tích hợp với phiên bản 1 của trò chơi trước đó sẽ tiếp tục hoạt động trong vài năm, nhưng bạn nên di chuyển sang phiên bản 2 kể từ tháng 6 năm 2025.
Hướng dẫn này dành cho việc sử dụng SDK Dịch vụ trò chơi của Play phiên bản 1. SDK C++ cho Dịch vụ trò chơi của Play phiên bản 2 chưa có sẵn.
SDK C++ của Dịch vụ trò chơi của Google Play cung cấp một API C++ để sử dụng với các dịch vụ của Google Play Games và dành cho những nhà phát triển đã triển khai C++ cho trò chơi của họ.
Hiện tại, SDK triển khai các dịch vụ sau:
Uỷ quyền
Thành tích
Bảng xếp hạng
Sự kiện
Trò chơi đã lưu
Kết nối lân cận (chỉ dành cho Android)
Số liệu thống kê về người chơi
Khái niệm
Nhìn chung, bạn có thể sử dụng SDK bằng cách làm theo các bước sau:
Thiết lập cấu hình nền tảng cho Android.
Sử dụng GameServices::Builder để định cấu hình và tạo đối tượng GameServices. Đối tượng GameServices sẽ tự động tìm cách đăng nhập và trả về kết quả thông qua lệnh gọi lại OnAuthActionFinished(). Lưu ý kết quả mà lệnh gọi lại trả về. Nếu không đăng nhập được tự động, bạn có thể hiển thị một nút để cho phép người dùng đăng nhập.
Sau khi nhận được kết quả OnAuthActionFinished(), bạn có thể sử dụng đối tượng GameServices và Trình quản lý con của đối tượng đó để thực hiện các lệnh gọi dịch vụ Play Games, bao gồm:
Đăng nhập (sau khi không uỷ quyền được): StartAuthorizationUI()
Mở khoá thành tích: Achievements().Unlock()
Hiển thị thành tích bằng giao diện người dùng tích hợp: Achievements().ShowAllUI()
Gửi điểm cao: Leaderboards().SubmitScore()
Đăng xuất: SignOut()
Khi bạn sử dụng xong đối tượng GameServices, hãy đặt lại hoặc huỷ đối tượng đó.
Ở cấp độ chi tiết hơn:
Khởi chạy cấu hình nền tảng: Đây là một đối tượng chứa thông tin khởi chạy theo nền tảng cụ thể. Trên Android, cấu hình nền tảng chứa máy ảo Java và con trỏ đến Activity hiện tại:
// In android_main(), create a platform configuration// and bind the object activity.// Alternately, attach the activity in JNI_Onload().gpg::AndroidPlatformConfigurationplatform_configuration;platform_configuration.SetActivity(state->activity->clazz);
Tạo đối tượng GameServices: Đối tượng này là điểm truy cập chính cho chức năng Dịch vụ trò chơi của Google Play. Các thực thể GameServices được tạo bằng GameServices::Builder.
Trong hầu hết các trường hợp triển khai, một đối tượng GameServices nhất định sẽ tồn tại miễn là môi trường C của bạn tồn tại; bạn không cần khởi chạy lại đối tượng đó khi Activity Android tạm dừng và tiếp tục.
// Creates a GameServices object that has lambda callbacks.game_services_=gpg::GameServices::Builder().SetDefaultOnLog(gpg::LogLevel::VERBOSE).SetOnAuthActionStarted([started_callback](gpg::AuthOperationop){is_auth_in_progress_=true;started_callback(op);}).SetOnAuthActionFinished([finished_callback](gpg::AuthOperationop,gpg::AuthStatusstatus){LOGI("Sign in finished with a result of %d",status);is_auth_in_progress_=false;finished_callback(op,status);}).Create(pc);
Sử dụng các lớp Trình quản lý để quản lý đối tượng GameServices. Bạn có thể truy cập vào trình quản lý từ một thực thể GameServices và nhóm các chức năng liên quan với nhau. Ví dụ về các thành phần này bao gồm Trình quản lý bảng xếp hạng và Thành tích. Các thành phần này không chứa trạng thái mà người dùng có thể nhìn thấy. Trình quản lý được trả về theo tham chiếu và thực thể GameServices chứa sẽ kiểm soát vòng đời của trình quản lý. Ứng dụng của bạn không được giữ lại tham chiếu Trình quản lý. Thay vào đó, ứng dụng của bạn nên giữ lại thực thể GameServices.
Trình quản lý trả về dữ liệu thông qua các đối tượng loại giá trị không thể thay đổi. Các giá trị này phản ánh một chế độ xem nhất quán về dữ liệu cơ bản tại thời điểm thực hiện truy vấn.
// Submit a high scoregame_services_->Leaderboards().SubmitScore(leaderboard_id,score);// Show the default Achievements UIgame_services_->Achievements().ShowAllUI();
Khi bạn sử dụng xong đối tượng GameServices, hãy dọn dẹp bằng cách gọi reset() trên unique_ptr sở hữu đối tượng đó hoặc bằng cách để unique_ptr tự động huỷ đối tượng đó khi ra khỏi phạm vi.
Mô hình tạo luồng
Trừ phi có ghi chú khác, tất cả phương thức GameServices và Trình quản lý đều có cách triển khai không đồng bộ, an toàn cho luồng. Bạn có thể gọi các phương thức này trên bất kỳ luồng nào mà không cần khoá bên ngoài và sẽ thực thi theo thứ tự nhất quán với thứ tự gọi.
Phương thức truy cập (những phương thức đọc trạng thái) có hai biến thể chính. Loại phương thức đầu tiên (có tên như FetchProperty()) cung cấp kết quả một cách không đồng bộ cho lệnh gọi lại được cung cấp; loại thứ hai (có tên như FetchPropertyBlocking()) trả về kết quả một cách đồng bộ cho luồng gọi.
Tất cả lệnh gọi lại của người dùng đều được gọi trên một luồng gọi lại chuyên dụng. Luồng này có thể khác với mọi khái niệm nền tảng về "luồng chính" hoặc "luồng giao diện người dùng". Bạn cũng nên cố gắng đảm bảo rằng lệnh gọi lại của người dùng được thực thi nhanh chóng; luồng gọi lại bị đình trệ có thể gây ra các vấn đề mà người dùng nhìn thấy (ví dụ: chậm hoàn tất yêu cầu đăng xuất).
Thông tin theo nền tảng
Để bắt đầu sử dụng SDK Play Games C++ trên Android, hãy tiếp tục với hướng dẫn nhanh.
Tài liệu đọc thêm
Hãy nhớ đọc tài liệu về lớp có trong SDK C++ của Dịch vụ trò chơi của Google Play để biết thêm thông tin chi tiết và xem các mẫu minh hoạ cách sử dụng SDK.
Nội dung và mã mẫu trên trang này phải tuân thủ các giấy phép như mô tả trong phần Giấy phép nội dung. Java và OpenJDK là nhãn hiệu hoặc nhãn hiệu đã đăng ký của Oracle và/hoặc đơn vị liên kết của Oracle.
Cập nhật lần gần đây nhất: 2025-07-26 UTC.
[[["Dễ hiểu","easyToUnderstand","thumb-up"],["Giúp tôi giải quyết được vấn đề","solvedMyProblem","thumb-up"],["Khác","otherUp","thumb-up"]],[["Thiếu thông tin tôi cần","missingTheInformationINeed","thumb-down"],["Quá phức tạp/quá nhiều bước","tooComplicatedTooManySteps","thumb-down"],["Đã lỗi thời","outOfDate","thumb-down"],["Vấn đề về bản dịch","translationIssue","thumb-down"],["Vấn đề về mẫu/mã","samplesCodeIssue","thumb-down"],["Khác","otherDown","thumb-down"]],["Cập nhật lần gần đây nhất: 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)."]]
