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 API, נדרש גם מזהה יציב שתואם לחשבון במשחק, שנקרא persona, כדי לאכוף מגבלות עוצמה (cardinality). אפשר לחשוב על 'פרסונה' בתור התווית שמייצגת את החשבון של המשתמש במשחק במערכת הזהויות של המפתח, ועל אסימון החזרה בתור מפתח שמשמש לשחזור החשבון של המשתמש במשחק. אסור לעשות שימוש חוזר בערכי פרסונה ואסימון בפרויקטים שונים של Play Games Services. כמו כן, למרות שאסימוני הזיכרון עשויים להשתנות עם הזמן, הפרסונה צריכה להיות יציבה בהתאם לחשבון של המשתמש בתוך המשחק.
כללי עוצמה (cardinality)
Recall API אוכף יחס 1:1 בין פרופילים ב-PGS לבין חשבונות במשחק (שנקראים כללי עוצמה (cardinality)), כך שאפשר לקשר פרסונה אחת רק לפרופיל PGS אחד, ואפשר לקשר פרופיל PGS אחד בלבד לפרסונה אחת. הדמות משמשת כמזהה יציב לחשבון במשחק, מאחר שאסימוני קריאה חוזרת עשויים להשתנות עם הזמן.
גם הדמות שמקושרת לפרופיל PGS עשויה להשתנות עם הזמן (כי חשבונות שונים בתוך המשחק מקושרים לפרופיל PGS).
תהליכי עבודה טכניים לאחסון ולאחזור של אסימוני Recall
בקטע הזה מוסבר על התהליך הטכני בין לקוח המשחק לבין השרתים של Google בזמן האחסון והאחזור של אסימוני Recall.
שלב 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
באמצעות מצב ללא פרופיל, אפשר לשמור אסימוני Recall למשתמשים שעדיין לא יצר פרופיל 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 עם שרת הלקוח והמשחק שלכם, פועלים לפי ההנחיות האלה.