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