Play Games Services برای C++
با مجموعه‌ها، منظم بمانید
ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
پس از منسوخ شدن Google Sign-In API، ما بازی‌ها v1 SDK را در سال 2026 حذف می‌کنیم. پس از فوریه 2025، نمی‌توانید عناوینی را که به تازگی با بازی‌های v1 SDK ادغام شده‌اند، در Google Play منتشر کنید. توصیه می کنیم به جای آن از بازی ها v2 SDK استفاده کنید.
در حالی که عناوین موجود با ادغام های قبلی نسخه 1 برای چند سال به کار خود ادامه می دهند، شما تشویق می شوید که از ژوئن 2025 به نسخه 2 مهاجرت کنید .
این راهنما برای استفاده از Play Games Services v1 SDK است. C++ SDK برای Play Games Services v2 هنوز در دسترس نیست.
Google Play Games Services C++ SDK یک API C++ را برای استفاده با سرویس‌های بازی Google Play ارائه می‌کند و برای توسعه‌دهندگانی است که یک پیاده‌سازی C++ از بازی خود دارند.
در حال حاضر، SDK خدمات زیر را پیاده سازی می کند:
- مجوز
- دستاوردها
- تابلوهای امتیازات
- رویدادها
- بازی های ذخیره شده
- اتصالات نزدیک (فقط اندروید)
- آمار بازیکنان
مفاهیم
در سطح بالایی، با دنبال کردن مراحل زیر از SDK استفاده می‌کنید:
- یک پیکربندی پلتفرم برای Android تنظیم کنید.
- از
GameServices::Builder برای پیکربندی و ساخت شی GameServices استفاده کنید. شی GameServices به طور خودکار سعی می کند وارد سیستم شود و نتیجه را از طریق یک پاسخ تماس OnAuthActionFinished() برمی گرداند. به نتیجه ای که با تماس برگشت داده شده است توجه داشته باشید. اگر تلاش برای ورود خودکار به سیستم ناموفق بود، می‌توانید دکمه‌ای را نمایش دهید که به کاربران اجازه ورود به سیستم را می‌دهد. پس از دریافت نتیجه OnAuthActionFinished() ، می‌توانید از شی GameServices و مدیران فرزند آن برای برقراری تماس‌های خدمات بازی‌های Play استفاده کنید، از جمله:
- ورود به سیستم (بعد از ناموفق بودن مجوز):
StartAuthorizationUI() - باز کردن قفل دستاوردها:
Achievements().Unlock() - نمایش دستاوردها با استفاده از رابط کاربری داخلی:
Achievements().ShowAllUI() - امتیاز بالا را ارسال کنید:
Leaderboards().SubmitScore() - خروج از سیستم:
SignOut()
وقتی استفاده از شی GameServices تمام شد، آن را بازنشانی یا نابود کنید.
در سطح دقیق تر:
Initialize a platform configuration: این شیئی است که حاوی اطلاعات مقداردهی اولیه پلتفرم خاص است. در اندروید، پیکربندی پلتفرم شامل جاوا 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);
یک شی GameServices بسازید: این شی نقطه ورود اصلی برای عملکرد خدمات خدمات بازی های Google Play است. نمونه های GameServices با GameServices::Builder ایجاد می شوند.
در بیشتر پیاده‌سازی‌ها، یک شی GameServices تا زمانی که محیط C شما باقی می‌ماند، باقی می‌ماند. هنگامی که Activity Android شما متوقف می شود و از سر گرفته می شود، نیازی به تنظیم مجدد آن ندارید.
// 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);
از کلاس های Manager برای مدیریت شی 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 دارای پیاده‌سازی ناهمزمان و ایمن با موضوع هستند. آنها را می توان روی هر رشته ای بدون قفل خارجی فراخوانی کرد و به ترتیبی مطابق با ترتیب فراخوانی آنها اجرا می شوند.
متدهای دسترسی (آنهایی که حالت را می خوانند) در دو نوع اصلی ارائه می شوند. اولین نوع متد (با نام‌هایی مانند 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" متمایز است. همچنین باید سعی کنید از اجرای سریع تماس های کاربر اطمینان حاصل کنید. یک رشته پاسخ تماس متوقف شده ممکن است باعث مشکلات قابل مشاهده توسط کاربر شود (به عنوان مثال، تکمیل درخواست خروج با تاخیر).
برای شروع استفاده از Play Games C++ SDK در Android، به راهنمای شروع سریع بروید.
در ادامه مطلب
برای جزئیات بیشتر، اسناد کلاس را که در Google Play Services C++ SDK ارائه می‌شود، بخوانید و نمونه‌هایی را که نحوه استفاده از SDK را نشان می‌دهند، بررسی کنید.
اگر بازی شما از سرور پشتیبان استفاده می‌کند، به فعال کردن دسترسی سمت سرور به خدمات بازی‌های Google Play مراجعه کنید.
محتوا و نمونه کدها در این صفحه مشمول پروانههای توصیفشده در پروانه محتوا هستند. جاوا و OpenJDK علامتهای تجاری یا علامتهای تجاری ثبتشده Oracle و/یا وابستههای آن هستند.
تاریخ آخرین بهروزرسانی 2025-07-29 بهوقت ساعت هماهنگ جهانی.
[null,null,["تاریخ آخرین بهروزرسانی 2025-07-29 بهوقت ساعت هماهنگ جهانی."],[],[],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)."]]
