Recall API מאפשר למשחקים לנהל קישורים בין משתמשי Google Play Games Services (PGS) לבין החשבונות שלהם במשחק, על ידי שמירת אסימוני Recall בשרתים של Google. הנה תרחיש לדוגמה לשימוש ב-Recall API.
משתמש משחק במשחק שלמפתח יש בו מערכת זהויות למעקב אחרי ההתקדמות של המשתמש, והוא משתמש ב-PGS במקביל לשיטות אימות אחרות כדי להתחבר לחשבון במשחק. בדוגמה הזו, משתמש מתחבר לחשבון PGS שלו, Laura, ויוצר חשבון בתוך המשחק באמצעות מערכת הזהויות של המפתח, שנקראת Racer94. כשהמשתמש משחק במשחק, שרת המשחק של המפתח מסנכרן את ההתקדמות שלו.
בנוסף, המפתח שומר אסימון ביטול אצל Google, שמתאים לחשבון של המשתמש במשחק. Google שומרת באופן אוטומטי את אסימון ה-recall הזה בפרופיל PGS של המשתמש.
עכשיו המשתמש מחליט לשחק במשחק ב-GPG במחשב בפעם הראשונה. המשתמש נכנס אוטומטית לחשבון PGS שלו, ותוכנת הלקוח של המשחק בודקת אם יש התקדמות של המשתמש הזה ב-PGS. לאחר מכן, שרת המשחק שולח שאילתה ל-Google כדי לבדוק אם יש אסימונים לחשבון PGS הזה. אם כן, Google שולחת בחזרה את אסימון הזיכרון, ושרת המשחק משתמש באסימון הזה כדי למצוא את החשבון המשויך של המשתמש, Racer94, ולשחזר את ההתקדמות שלו. מכיוון שהכניסה באמצעות PGS היא חוויה חלקה, האפליקציה משחזרת את ההתקדמות של המשתמש בלי שהוא יצטרך להזין שם משתמש או סיסמה. בנוסף, המפתחים יכולים להשתמש בכניסה ל-PGS באמצעות מערכת הזהויות הקיימת שלהם, ולהסתמך על Google כדי לאחסן את הקישור בין ההתקדמות של השחקנים לבין חשבון PGS שלהם.
כפי שראינו בדוגמה שלמעלה, יש שתי פעולות עיקריות שמבוצעות על ידי Recall API:
אחסון הטוקן ב-Google כשמשתמש מתחבר באמצעות אחד מהחשבונות במשחק.
אחזור האסימון של משתמש כדי לשחזר את החשבונות שלו במשחק.
בנוסף לטוקנים של Recall, כדי לאכוף אילוצים של עוצמת קבוצה, נדרש ב-Recall API גם מזהה יציב שתואם לחשבון במשחק, שנקרא פרסונה. אפשר לחשוב על 'פרסונה' בתור התווית שמייצגת את החשבון של המשתמש במשחק במערכת הזהויות של המפתח, ועל אסימון החזרה בתור מפתח שמשמש לשחזור החשבון של המשתמש במשחק. אסור לעשות שימוש חוזר בערכים של אסימונים ושל פרסונות בפרויקטים שונים של PGS. בנוסף, אסימוני Recall עשויים להשתנות עם הזמן, אבל פרופיל המשתמש צריך להיות יציב בהתאם לחשבון של המשתמש במשחק.
כללי עוצמה (cardinality)
Recall API אוכף יחס של 1:1 בין פרופילי PGS לחשבונות במשחק (שנקראים כללי עוצמה), כך שאפשר לקשר רק פרסונה אחת לפרופיל PGS אחד, ופרופיל PGS אחד אפשר לקשר רק לפרסונה אחת. הדמות משמשת כמזהה יציב לחשבון במשחק, מאחר שאסימוני קריאה חוזרת עשויים להשתנות עם הזמן.
גם הדמות שמקושרת לפרופיל PGS עשויה להשתנות עם הזמן (כי חשבונות שונים בתוך המשחק מקושרים לפרופיל PGS).
תהליכים טכניים לאחסון ולאחזור של אסימוני ה-recall
בקטע הזה נסביר על התהליך הטכני בין לקוח המשחק לשרתים עם שרתי Google, במהלך האחסון והאחזור של אסימוני ביטול.
שלב 1: נכנסים כמשתמש PGS ומאחזרים את מזהה הסשן
המשחק מאתחלל את ה-SDK של PGS ומנסה להכניס את המשתמש באמצעות PGS.
בהנחה שהמשתמש נכנס לחשבון, מבקשים מזהה סשן מ-Games SDK בלקוח המשחק ומבקשים אסימון OAuth 2.0 מקצה העורפי של OAuth ב-Google. מזהה הסשן ואסימוני OAuth 2.0 משמשים לתקשורת עם הקצה העורפי של Google Games.
שלב 2: אחזור של אסימון ביטול זמין
בקשה לאסימון Recall שמשויך לחשבון של משתמש PGS. אם יש אסימון, ממשיכים לשלב 3א' ומשחזרים את ההתקדמות. אחרת, אם מדובר במשתמש חדש שאין לו אסימון, ממשיכים לשלב 3ב ושומרים אסימון חדש.
שלב 3-א: אם יש טוקן, משחזרים את ההתקדמות
אם יש אסימון, מאחזרים ומפענחים אותו ומשחזרים את נתוני המשתמש.
שלב 3ב: אם אין טוקן, שומרים טוקן
מכיוון שאין טוקן, ההתקדמות לא משוחזרת. המשתמש ממשיך להיכנס באמצעות מערכת הזהויות של המפתח, או יוצר חשבון חדש אם אין חשבון כזה. הערה: מדובר לא בכניסה באמצעות PGS (כבר עשיתם את זה), אלא באמצעות מערכת זהויות של מפתח מחוץ ל-PGS.
יוצרים אסימון קריאה חוזרת מוצפן שמקודד את החשבון של המשתמש במשחק, ושולחים אותו ל-Google יחד עם מזהה הסשן ואסימון OAuth 2.0. בשלב הזה, Google יוצרת שיוך בין אסימון הביטול שנשלח לבין חשבון ה-PGS של השחקן.
תהליכים למשתמשים ללא פרופיל PGS
אפשר לאחסן אסימוני ריקול של משתמש שעדיין לא יצר פרופיל PGS באמצעות מצב ללא פרופיל. עם זאת, יש שתי נקודות חשובות שצריך לזכור:
- אי אפשר לאחזר טוקנים של משתמש שאין לו פרופיל PGS. המערכת מבקשת ליצור פרופיל באופן אוטומטי כשהמשתמש מנסה להתחבר למשחק באמצעות Play Games Services במכשיר שני.
- עליכם לפעול בהתאם להנחיות נוספות כדי להבטיח שתציגו הודעה מתאימה שמתארת את הפריטים הבאים ותקבלו את ההסכמה המתאימה ממשתמשי הקצה:
- שיתוף הנתונים עם Google כדי להפעיל את התכונה של קישור חשבון Play Games.
- הזמינות של הגדרות לניהול השיתוף הזה, כמו ההגדרות של Play Games.
- העיבוד של נתונים כאלה בכפוף למדיניות הפרטיות של Google.
שמירת צמד של אסימון ופרטים אישיים
- משתמש ללא פרופיל PGS פותח משחק שבו האפשרות של ריקול ללא פרופיל מופעלת.
- ה-SDK למשחקים מפעיל כניסה אוטומטית, שנכשלת כי למשתמש אין פרופיל PGS.
- ב-Games SDK מוצגת סרגל סטטוסים שמציין למשתמש שהמשחק משולב עם Google. אפשר לבצע פעולה בסרגל הנפתח הזה – המשתמש יכול להשבית את האפשרות של אחזור עד שיוצרים פרופיל.
- המשחק מבקש גישה לזיכרון. חשוב לדעת שמערכת PGS דוחה בקשות גישה לריקול כשיש במכשיר פרופילים של PGS או כשאין במכשיר חשבונות Google. במקרה כזה, המשחק אמור להמשיך בלי להשתמש ב-PGS.
- אחרי שהמשתמש נכנס לחשבון במשחק, המשחק יוצר עבורו אסימון וזוג פרסונה שתואמים לחשבון שלו במשחק. המשחק שומר את ההתאמה הזו ב-Google. יכול להיות שהמשחק ישמור אסימונים נוספים מאוחר יותר אם המשתמש יתחבר לחשבונות אחרים במשחק.
הפעלת משחק במכשיר חדש
- משתמש ללא פרופיל PGS פותח במכשיר משחק שבו האפשרות של ריקול ללא פרופיל מופעלת.
- המשחק מתעד אסימון זיכרון ללא פרופיל, כפי שמתואר בקטע אחסון של אסימון וזוג פרסונה.
- המשתמש פותח את אותו משחק במכשיר אחר עם אותה הגדרת חשבון.
- ערכת ה-SDK של Games מפעילה את יצירת הפרופיל. המשתמש יכול לבדוק ולדחות אסימוני Recall שנשמרו בעבר. המשתמש יוצר פרופיל PGS בשלב הזה.
- הכניסה האוטומטית ל-PGS מסתיימת והמשחק מקבל את הסטטוס 'מאומת'.
- המשחק מאחזר את אסימוני הזיכרון של המשתמש כרגיל.
השלבים הבאים
כדי לשלב את Recall API עם הלקוח ושרת המשחק, פועלים לפי ההנחיות האלה.