תחילת השימוש ב-Play Games Services ב-C++

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

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

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

מושגים

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

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

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

    • כניסה (לאחר שההרשאה נכשלה): StartAuthorizationUI()
    • יש לך הזדמנות לזכות בהישגים: Achievements().Unlock()
    • הצגת הישגים באמצעות ממשק משתמש מובנה: Achievements().ShowAllUI()
    • שליחת תוצאה גבוהה: Leaderboards().SubmitScore()
    • יציאה: SignOut()

  4. בסיום השימוש באובייקט GameServices, יש לאפס או להשמיד אותו.

ברמה מפורטת יותר:

  1. אתחול תצורת פלטפורמה: אובייקט שמכיל מידע על אתחול ספציפי לפלטפורמה. ב-Android, תצורת הפלטפורמה מכילה את הקטע VM של Java ומצביע אל 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. אתם יכולים להשתמש במחלקות הניהול כדי לנהל את האובייקט 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);});

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

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

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

קריאה נוספת

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

אם המשחק משתמש בשרת עורפי: הפעלת גישה מצד השרת לשירותי Google Play Games.