ממשק API של Recall

‫Recall API עוזר לכם לקשר בצורה חלקה בין משתמשי Google Play Games Services לבין החשבונות שלהם במשחק, וכך מאפשר שחזור אוטומטי של ההתקדמות. אתם שומרים טוקנים של Recall בשרתי המשחק, ומקשרים את הטוקנים האלה לפרופיל של משתמש ב-Google Play Games Services. השימוש ב-Recall API הוא אופציונלי, והוא השיטה המומלצת להטמעת שחזור חלק אם אין לכם בק-אנד חזק משלכם לניהול זהויות.

הסברים על המונחים

במסמך הזה אנחנו משתמשים במונחים הבאים:

טוקן זיכרון: מפתח מאובטח שמאוחסן בשרתי המשחק ומשמש כקישור בין החשבון של השחקן ב-Play Games לבין החשבון שלו במשחק.

מזהה סשן: מזהה זמני וייחודי שנוצר על ידי Play Games Services SDK במכשיר של השחקן. הוא מציין שבקשה שנשלחה על ידי שרת הקצה העורפי שלכם הגיעה מסשן משחק לגיטימי ופעיל במכשיר של השחקן.

תרחישים לדוגמה

דוגמאות לתרחישים שבהם אפשר להשתמש ב-Recall API:

1. משתמש משחק במשחק שבו למפתח יש מערכת זהויות למעקב אחרי התקדמות המשתמש, והוא משתמש ב-PGS במקביל לשיטות אימות אחרות כדי לאפשר למשתמשים להיכנס למשחק. בדוגמה הזו, משתמשת מחוברת לחשבון שלה ב-PGS‏ Laura, ויוצרת חשבון במשחק עם מערכת הזהויות של המפתח שנקראת Racer94. במהלך המשחק, שרת הגיימינג של המפתח מסנכרן את ההתקדמות של המשתמש.

   

2. בנפרד, המפתח שומר טוקן זיכרון ב-Google, שמתאים לחשבון של המשתמש במשחק. ‫Google שומרת אוטומטית את טוקן הזיכרון הזה בפרופיל PGS של המשתמש.

   

3. המשתמש מחליט לשחק במשחק ב-GPG במחשב בפעם הראשונה. המשתמש עובר אימות אוטומטי באמצעות חשבון PGS שלו, ולקוח המשחק בודק אם יש התקדמות זמינה למשתמש הזה ב-PGS. לאחר מכן שרת גיימינג שולח שאילתה ל-Google כדי לבדוק אם יש טוקנים לחשבון הזה ב-PGS. המשחק, Google מחזירה את טוקן הזיכרון, ושרת גיימינג משתמש בטוקן הזה כדי למצוא את החשבון המשויך של המשתמש, Racer94, ולשחזר את ההתקדמות שלו. האימות באמצעות PGS הוא תהליך חלק, ולכן ההתקדמות של המשתמש משוחזרת על ידי האפליקציה בלי שהמשתמש צריך להזין שם משתמש או סיסמה. בנוסף, המפתח יכול להשתמש באימות של PGS עם מערכת הזהויות הקיימת שלו, ולהסתמך על Google כדי לאחסן את הקישור בין ההתקדמות של השחקן לבין חשבון PGS שלו.

   

כפי שאפשר לראות בדוגמה שלמעלה, יש שתי פעולות עיקריות שמבוצעות על ידי Recall API:

• שמירת הטוקן ב-Google כשמשתמש מתחבר באמצעות אחד מהחשבונות במשחק.

• אחזור האסימון של משתמש כדי לשחזר את החשבונות שלו במשחק.

בנוסף לטוקנים של זיכרון, ‏ Recall API דורש גם מזהה יציב שתואם לחשבון במשחק, שנקרא פרסונה. אפשר לחשוב על פרסונה כתווית שמייצגת את החשבון של המשתמש במשחק במערכת הזהויות של המפתח, ועל טוקן זיכרון כמפתח שמשמש לשחזור החשבון של המשתמש במשחק. אסור לעשות שימוש חוזר בערכי פרסונה וטוקן בפרויקטים שונים של PGS. בנוסף, למרות שאפשר לשנות את טוקני הזיכרון לאורך זמן, הפרסונה צריכה להיות יציבה בהתאם לחשבון של המשתמש במשחק.

תהליכים טכניים לשמירה ולאחזור של טוקנים של Recall

בקטע הזה מוסבר על התהליך הטכני בין לקוח המשחק לבין השרתים עם שרתי Google, כשמאחסנים ומאחזרים טוקנים של זיכרון.

שלב 1: מאמתים את המשתמש ב-PGS ומאחזרים את מזהה הסשן

המשחק מאתחל את PGS SDK ומנסה לאמת את המשתמש באמצעות PGS.

בהנחה שהמשתמש מאומת, מבקשים מזהה סשן מ-Games SDK בלקוח המשחק, ומבקשים טוקן OAuth 2.0 מהקצה העורפי של OAuth של Google. מזהה הסשן ואסימוני OAuth 2.0 משמשים לתקשורת עם הקצה העורפי של Google Games.

שלב 2: מאחזרים טוקן ביטול זמין

שליחת בקשה לטוקן זיכרון שמשויך לחשבון של משתמש 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.

שמירת צמד של טוקן ופרסונה

1. משתמש ללא פרופיל PGS פותח משחק שבו מופעלת תכונת הזיכרון ללא פרופיל.
2. ערכת ה-SDK של המשחקים מפעילה אימות אוטומטי של הפלטפורמה, שנכשל כי למשתמש אין פרופיל PGS.
3. ה-SDK של משחקים מציג סרגל אינטראקטיבי שמודיע למשתמש שהמשחק משולב עם Google. המשתמש יכול לבצע פעולה בסרגל האינטראקטיבי הזה – הוא יכול להשבית את התכונה 'זיכרון' עד ליצירת פרופיל.
4. המשחק מבקש גישה לזיכרון. חשוב לזכור ש-PGS דוחה בקשות גישה לריקול אם יש פרופילים של PGS במכשיר או אם אין חשבונות Google במכשיר. במקרה כזה, המשחק צריך להמשיך לפעול בלי להשתמש ב-PGS.
5. אחרי שהמשתמש מתחבר באמצעות חשבון במשחק, המשחק יוצר טוקן וזוג פרסונה עבור המשתמש, שמתאימים לחשבון שלו במשחק. המשחק שומר את הזוג הזה ב-Google. יכול להיות שהמשחק ישמור עוד טוקנים בהמשך אם המשתמש יתחבר לחשבונות אחרים במשחק.

הפעלת משחק במכשיר חדש

1. משתמש ללא פרופיל PGS פותח משחק שבו מופעלת תכונת הריקול ללא פרופיל במכשיר.
2. המשחק מתעד טוקן זיכרון ללא פרופיל, כפי שמתואר במאמר שמירת טוקן וזוג פרסונות.
3. המשתמש פותח את אותו משחק במכשיר אחר שבו מוגדר אותו חשבון.
4. ‫Games SDK מפעיל את יצירת הפרופיל. המשתמש יכול לבדוק ולדחות טוקנים של Recall שנשמרו בעבר. המשתמש יוצר פרופיל PGS בשלב הזה.
5. האימות האוטומטי של הפלטפורמה ב-PGS מסתיים, והמשחק מקבל את סטטוס האימות.
6. המשחק מאחזר את אסימוני הזיכרון של המשתמש כרגיל.

השלבים הבאים

כדי לשלב את Recall API עם הלקוח ועם שרת גיימינג, פועלים לפי ההנחיות האלה.