קל לארגן דפים בעזרת אוספים
אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.
בעקבות ההוצאה משימוש של API של כניסה באמצעות חשבון Google, אנחנו מסירים את ה-SDK של גרסה 1 למשחקים ב-2026. אחרי פברואר 2025, לא תוכלו לפרסם ב-Google Play כותרים ששולבו לאחרונה עם ערכת ה-SDK של גרסה 1 של משחקים. במקום זאת, מומלץ להשתמש ב-games v2 SDK.
כותרים קיימים עם השילובים הקודמים של המשחקים בגרסה 1 ימשיכו לפעול במשך כמה שנים, אבל מומלץ להעביר אותם לגרסה 2 החל מיוני 2025.
המדריך הזה מיועד לשימוש ב-SDK של Play Games Services v1. עדיין לא זמין SDK ל-C++ עבור Play Games Services v2.
ה-SDK של Google Play Games Services ב-C++ מספק ממשק API ל-C++ לשימוש עם Google Play Games Services, והוא מיועד למפתחים שיש להם הטמעה קיימת של C++ במשחק שלהם.
נכון לעכשיו, ערכת ה-SDK מיישמת את השירותים הבאים:
הרשאה
הישגים
לוחות לידרבורד
אירועים
Saved Games
Nearby Connections (Android בלבד)
נתונים סטטיסטיים של שחקנים
מושגים
באופן כללי, כדי להשתמש ב-SDK:
מגדירים הגדרות פלטפורמה ל-Android.
משתמשים ב-GameServices::Builder כדי להגדיר ולבנות אובייקט GameServices. האובייקט GameServices ינסה להיכנס באופן אוטומטי ויחזיר את התוצאה באמצעות קריאה חוזרת (callback) של OnAuthActionFinished(). שימו לב לתוצאה שחוזרת מהשיחה החוזרת. אם ניסיון הכניסה האוטומטי נכשל, תוכלו להציג לחצן כדי לאפשר למשתמשים להיכנס לחשבון.
אחרי קבלת התוצאה OnAuthActionFinished(), אפשר להשתמש באובייקט GameServices ובמנהלים הצאצאים שלו כדי לבצע קריאות לשירותי Play Games, כולל:
הצגת ההישגים באמצעות ממשק משתמש מובנה: Achievements().ShowAllUI()
שליחת תוצאה גבוהה: Leaderboards().SubmitScore()
יציאה מהחשבון: SignOut()
כשמסיימים להשתמש באובייקט GameServices, צריך לאפס אותו או להשמיד אותו.
ברמה מפורטת יותר:
אתחול של הגדרות פלטפורמה: אובייקט שמכיל מידע על אתחול ספציפי לפלטפורמה. ב-Android, הגדרת הפלטפורמה מכילה את Java VM ואת הפונקציה Activity הנוכחית:
// 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);
יוצרים אובייקט GameServices: האובייקט הזה הוא נקודת הכניסה הראשית לפונקציונליות של Google Play Games Services. מכונות 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::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);
משתמשים ב-Manager classes כדי לנהל את האובייקט GameServices. הגישה למנהלים מתבצעת ממכונת GameServices ומקבץ את הפונקציונליות הקשורה לקבוצות. דוגמאות לכך כוללות את מנהלי ההישגים ואת לוחות הדירוג. הם לא מכילים מצב שגלוי למשתמשים. המנהלים מוחזרים לפי הפניה, ומופע ה-GameServices שמכיל אותם שולט במחזור החיים שלהם. הלקוח שלכם אף פעם לא צריך לשמור את פרטי החשבון של חשבון הניהול. במקום זאת, הלקוח צריך לשמור את המכונה GameServices.
מנהלי מודולים מחזירים נתונים באמצעות אובייקטים מסוג ערך בלתי ניתן לשינוי. הערכים האלה משקפים תצוגה עקבית של נתוני הבסיס בנקודת הזמן שבה בוצעה השאילתה.
// Submit a high scoregame_services_->Leaderboards().SubmitScore(leaderboard_id,score);// Show the default Achievements UIgame_services_->Achievements().ShowAllUI();
כשמסיימים להשתמש באובייקט GameServices, צריך לבצע ניקוי על ידי קריאה ל-reset() ב-unique_ptr שבבעלותו, או לאפשר ל-unique_ptr להשמיד אותו באופן אוטומטי כשהוא יוצא מההיקף.
מודל של שרשור
אלא אם צוין אחרת, לכל השיטות של GameServices ושל Manager יש הטמעות אסינכרוניות ללא סיכון לשרשור (thread-safe). אפשר להפעיל אותם בכל חוט ללא נעילת צדדים חיצוניים, והם יבוצעו בסדר שתואם לסדר ההפעלה שלהם.
שיטות גישה (אלה שקוראות את המצב) מגיעות בשתי גרסאות עיקריות. הסוג הראשון של שיטות (עם שמות כמו FetchProperty()) מספק את התוצאות שלו באופן אסינכרוני ל-callback שסופק. הסוג השני (עם שמות כמו FetchPropertyBlocking()) מחזיר את התוצאות שלו באופן סינכרוני לשרשור הקורא.
כל הקריאות החוזרות של המשתמשים מופעלות בשרשור ייעודי. ה-thread הזה עשוי להיות שונה מכל מושג פלטפורמה של 'thread ראשי' או 'thread של ממשק משתמש'. כדאי גם לוודא שהפעלת קריאות החזרה (callbacks) של המשתמשים מתבצעת במהירות. שרשור של קריאת חזרה שנתקע עלול לגרום לבעיות שגלויות למשתמשים (לדוגמה, עיכוב בהשלמת בקשת יציאה).
מידע ספציפי לפלטפורמה
כדי להתחיל להשתמש ב-Play Games C++ SDK ב-Android, אפשר להמשיך למדריך למתחילים.
מקורות מידע נוספים
מומלץ לקרוא את מסמכי התיעוד של הכיתה שכלולים ב-Google Play Game Services C++ SDK כדי לקבל פרטים נוספים, ולעיין בדוגמאות שממחישות איך משתמשים ב-SDK.
דוגמאות התוכן והקוד שבדף הזה כפופות לרישיונות המפורטים בקטע רישיון לתוכן. Java ו-OpenJDK הם סימנים מסחריים או סימנים מסחריים רשומים של חברת Oracle ו/או של השותפים העצמאיים שלה.
עדכון אחרון: 2025-07-26 (שעון UTC).
[[["התוכן קל להבנה","easyToUnderstand","thumb-up"],["התוכן עזר לי לפתור בעיה","solvedMyProblem","thumb-up"],["סיבה אחרת","otherUp","thumb-up"]],[["חסרים לי מידע או פרטים","missingTheInformationINeed","thumb-down"],["התוכן מורכב מדי או עם יותר מדי שלבים","tooComplicatedTooManySteps","thumb-down"],["התוכן לא עדכני","outOfDate","thumb-down"],["בעיה בתרגום","translationIssue","thumb-down"],["בעיה בדוגמאות/בקוד","samplesCodeIssue","thumb-down"],["סיבה אחרת","otherDown","thumb-down"]],["עדכון אחרון: 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)."]]
