Play Games Services ל-C++‎

בעקבות הוצאה משימוש של Google Sign-In API, אנחנו מסירים את ה-SDK בגרסה Games v1 בשנת 2026. אחרי פברואר 2025, לא תהיה לך אפשרות לפרסם ב-Google Play משחקים ששולבו לאחרונה עם ה-SDK בגרסה Games v1. מומלץ להשתמש ב-SDK בגרסה Games v2.
פריטים קיימים עם שילובים קודמים של משחקים בגרסה 1 ימשיכו לפעול למשך כמה שנים, אבל מומלץ לעבור לגרסה 2 החל מיוני 2025.
המדריך הזה מיועד לשימוש ב-SDK של Play Games Services בגרסה 1. ה-SDK של C++‎ ל-Play Games Services בגרסה 2 עדיין לא זמין.

ה-SDK של Google Play Games Services C++‎ מספק API של C++‎ לשימוש עם Google Play Games Services, והוא מיועד למפתחים שיש להם הטמעה קיימת של C++‎ במשחק שלהם.

בשלב הזה, ערכת ה-SDK מטמיעה את השירותים הבאים:

• הרשאה
• הישגים
• לוחות לידרבורד
• אירועים
• Saved Games
• חיבורים בקרבת מקום (Android בלבד)
• נתונים סטטיסטיים של שחקנים

מושגים

באופן כללי, כדי להשתמש ב-SDK צריך לבצע את השלבים הבאים:

1. מגדירים את תצורת הפלטפורמה ל-Android.
2. משתמשים ב-GameServices::Builder כדי להגדיר ולבנות אובייקט GameServices. אובייקט GameServices מנסה להיכנס באופן אוטומטי ומחזיר את התוצאה באמצעות קריאה חוזרת (callback) של OnAuthActionFinished(). רושמים את התוצאה שהוחזרה על ידי הקריאה החוזרת. אם ניסיון הכניסה האוטומטי נכשל, אפשר להציג כפתור שיאפשר למשתמשים להיכנס.

3. אחרי שמקבלים את התוצאה OnAuthActionFinished(), אפשר להשתמש באובייקט GameServices ובמנהלים הצאצאים שלו כדי לבצע קריאות לשירותי Play Games, כולל:

   • כניסה לחשבון (אחרי שההרשאה נכשלה): StartAuthorizationUI()
   • הישגים חדשים: Achievements().Unlock()
   • הצגת ההישגים באמצעות ממשק משתמש מובנה: 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 Games Services. מופעים של 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);
   

3. אפשר להשתמש במחלקות Manager כדי לנהל את אובייקט GameServices. הגישה למנהלים היא ממופע GameServices, והפונקציונליות שקשורה לקבוצות מרוכזת במקום אחד. דוגמאות לכך הן Achievement Manager ו-Leaderboard Manager. הם לא מכילים מצב גלוי למשתמש. המנהלים מוחזרים באמצעות הפניה, ומופע GameServices שמכיל אותם שולט במחזור החיים שלהם. חשבון הלקוח לא יכול להחזיק בהפניה לחשבון ניהול. במקום זאת, הלקוח צריך לשמור את המופע GameServices.

   מנהלים מחזירים נתונים באמצעות אובייקטים מסוג ערך קבוע. הערכים האלה משקפים תצוגה עקבית של נתוני הבסיס בנקודת הזמן שבה בוצעה השאילתה.

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

4. כשמסיימים להשתמש באובייקט GameServices, צריך לנקות אותו על ידי קריאה ל-reset() באובייקט unique_ptr שבבעלותו, או על ידי מתן אפשרות לאובייקט unique_ptr להרוס אותו באופן אוטומטי כשהוא יוצא מההיקף.

מודל השרשור

אלא אם צוין אחרת, לכל השיטות של GameServices ושל חשבון הניהול יש הטמעות אסינכרוניות שמאובטחות לשימוש בכמה תהליכים בו-זמנית. אפשר לקרוא להן בכל שרשור בלי נעילה חיצונית, והן יפעלו בסדר שתואם לסדר הקריאה שלהן.

יש שני סוגים עיקריים של שיטות גישה (שיטות שקוראות מצב). הסוג הראשון של שיטה (עם שמות כמו 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);});

כל הקריאות החוזרות של המשתמש מופעלות בשרשור ייעודי של קריאות חוזרות. יכול להיות שה-thread הזה שונה מהמושג של "thread ראשי" או "thread של ממשק משתמש" בפלטפורמות אחרות. כדאי גם לוודא שהקריאות החוזרות (callback) של המשתמשים מתבצעות במהירות. שרשור של קריאה חוזרת שנתקע עלול לגרום לבעיות שגלויות למשתמשים (לדוגמה, השלמה מושהית של בקשה ליציאה מהחשבון).

מידע ספציפי לפלטפורמה

כדי להתחיל להשתמש ב-Play Games C++ SDK ב-Android, אפשר להמשיך אל המדריך למתחילים.

קריאה נוספת

כדאי לקרוא את תיעוד המחלקה שמגיע עם Google Play Game services C++ SDK כדי לקבל פרטים נוספים, ולעיין בדוגמאות שממחישות איך להשתמש ב-SDK.

אם המשחק שלכם משתמש בשרת בק-אנד, כדאי לעיין במאמר הפעלת גישה מצד השרת ל-Google Play Games Services.