Play Games Services ל-C++‎

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

ה-SDK ל-C++‎ של Google Play Games Services מספק 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, אפשר לעבור אל מדריך ההתחלה המהירה.

קריאה נוספת

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

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