Play Games Services ל-C++‎

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

‫Google Play games Services C++ SDK מספק C++ API לשימוש עם Google Play Game 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, והפונקציונליות שקשורה לקבוצות מרוכזת במקום אחד. דוגמאות לכך הן מנהלי ההישגים וטבלת המובילים. הם לא מכילים מצב גלוי למשתמש. המנהלים מוחזרים באמצעות הפניה, והמופע 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.

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