משלבים את PGS Recall API במשחק

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

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

מגדירים את שרת המשחקים כך שישלח קריאות Recall API לשרתים של Google.

הגדרת הפרויקט ב-Play Games Services

(אם עדיין לא ביצעתם זאת) פועלים לפי ההוראות במאמר הגדרת שירותי Google Play Games.

הגדרה של חשבון שירות למשחק

מבצעים את ההוראות ליצירת שירות. חשבון. בסוף צריך להיות קובץ JSON עם פרטי כניסה של חשבון שירות.

הורדת ספריית Java בצד השרת עבור Play Games Services

הורדת הגרסה האחרונה של google-api-services-games ספרייה ולהעלות את הקובץ לשרת שלך.

הכנת פרטי הכניסה לקריאות API של Recall

הקשר נוסף זמין במאמר הכנה לביצוע קריאה להענקת גישה ל-API.

import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.services.games.Games;
import com.google.api.services.games.GamesScopes;

// ...

GoogleCredential credential =
  GoogleCredential.fromStream(new FileInputStream("<credentials>.json"))
    .createScoped(Collections.singleton(GamesScopes.ANDROIDPUBLISHER));

Games gamesApi =
    new Games.Builder(httpTransport, JSON_FACTORY, credential).build();

הגדרה של לקוח משחק

מגדירים את לקוח המשחק כך שיוכל לאחזר את מזהי הסשנים של ה-recall שבהם השרת משתמש כדי לתקשר עם שרתי Google.

Java SDK

מגדירים את Java SDK בלקוח, ומוודאים שמוגדרים com.google.android.gms:play-services-games-v2:19.0.0 ו-com.google.android.gms:play-services-tasks:18.0.2 ואילך בקובץ Gradle.

כדי לתקשר עם השרתים של Google עם המידע הנכון, צריך לבקש הכרת מזהה הסשן מה-SDK של הלקוח, שאותו אתם שולחים לשרת של המשחק:

PlayGames.getRecallClient(getActivity())
  .requestRecallAccess()
  .addOnSuccessListener { recallAccess -> val recallSessionId: String = recallAccess.getSessionId() }
  // Send the recallSessionId to your game server

PlayGames.getRecallClient(getActivity())
  .requestRecallAccess()
  .addOnSuccessListener(
    recallAccess -> {
      String recallSessionId = recallAccess.getSessionId();
      // Send the recallSessionId to your game server
  });

שימוש ב-Recall API בשרת המשחק

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

אחסון טוקנים

שומרים את דמותו של המשתמש ואת אסימון המשחק שלו באמצעות האובייקט LinkPersonaRequest. משתמשים ב-GoogleCredential כדי להפעיל ממשקי Google API. כדי לעמוד באילוץ העוצמה (cardinality) של 1:1, אפשר לקשר רק פרסונה אחת לפרופיל PGS אחד בכל פעם, ולהפך. מגדירים את מדיניות הפתרון למקרה שפרופיל ה-PGS הזה כבר מקושר לפרופיל משתמש אחר.

אפשר גם להגדיר זמן תפוגה לאסימון, שמציין את משך התוקף שלו באמצעות אובייקט Durations. אפשר להגדיר את התאריך באמצעות SetTtl() (כפי שמוצג בהמשך), שמגדיר את תאריך התפוגה לפי משך הזמן שצוין בשיטה, או באמצעות setExpireTime(), שמאפשר להגדיר תאריך מדויק שבו התוקף של האסימונים יפוג.

עליך להצפין את הפרסונה ואת אסימון המשחק, והם לא יכולים להכיל מידע אישי פרטים מזהים (PII). מחרוזות של פרסונות ואסימונים יכולות להיות באורך של עד 256 תווים, וניתן לאחסן עד 20 אסימונים או פרסונות לכל שחקן בכל משחק.

ניתן לאחסן אסימון אחד בלבד לכל פרסונה לכל שחקן בכל זמן נתון. אם תנסה כדי לאחסן אסימון אחר עם אותה פרסונה, המערכת מחליפה את המקורי ב-Assistant.

import com.google.api.services.games.Games.Recall.LinkPersona;
import com.google.protobuf.util.Durations;

// ...

Games gamesApi =
    new Games.Builder(httpTransport, JSON_FACTORY, credential).build();

String recallSessionId = ... // recallSessionID from game client
String persona = ... // encrypted opaque string, stable for in-game account
String token = ... // encrypted opaque string encoding the progress line

LinkPersonaRequest linkPersonaRequest =
  LinkPersonaRequest.newBuilder()
    .setSessionId(recallSessionId)
    .setPersona(persona)
    .setToken(token)
    .setCardinalityConstraint(ONE_PERSONA_TO_ONE_PLAYER)
    .setConflictingLinksResolutionPolicy(CREATE_NEW_LINK)
    .setTtl(Durations.fromDays(7)) // Optionally set TTL for token
    .build();

LinkPersonaResponse linkPersonaResponse =
  gamesApi.recall().linkPersona(linkPersonaRequest).execute();

if (linkPersonaResponse.getState() == LINK_CREATED) {
  // success
}

אחזור טוקנים

כדי לאחזר את אסימון הביטול, מקבלים את recallSessionId מהלקוח ומעבירים אותו ל-API של retrieveTokens:

import com.google.api.services.games.Games.Recall.RetrieveTokens;

// ...

String recallSessionId = ... // recallSessionID from game client

RetrievePlayerTokensResponse retrievePlayerTokensResponse =
  gamesApi.recall().retrieveTokens(recallSessionId).execute();

for (RecallToken recallToken : retrievePlayerTokensResponse.getTokens()) {
  String token recallToken.getToken();
  // Same string as was written in LinkPersona call
  // decrypt and recover in-game account
}

מחיקת טוקן הביטול

במקרה הצורך, אפשר גם למחוק את אסימון הריקול באמצעות הקריאה הבאה:

import com.google.api.services.games.Games.Recall.UnlinkPersona;

// ...

String recallSessionId = ...
String persona = ...
String token = ...

Games gamesApi =
    new Games.Builder(httpTransport, JSON_FACTORY, credential).build();

UnlinkPersonaRequest unlinkPersonaRequest =
  UnlinkPersonaRequest.newBuilder()
    .setSessionId(recallSessionId)
    .setPersona(persona)
    // .setToken(token) - alternatively set token, but not both
    .build();

UnlinkPersonaResponse unlinkPersonaResponse =
  gamesApi.recall().unlinkPersona(unlinkPersonaRequest).execute();

// Confirm that the unlinking process completed successfully.
boolean unlinked = unlinkPersonaResponse.isUnlinked();

הפעלת מצב ללא פרופיל

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

1. הפעלת ריקול ללא פרופיל לפרויקט המשחק שלך ב-Play Games Services ב-Play Developer מסוף.
2. אפשר לעיין בתנאים הנוספים שמתוארים בהמשך הקטע הזה.
3. מוסיפים את תג המטא-נתונים הבא למניפסט של האפליקציה:

<meta-data
  android:name="com.google.android.gms.games.PROFILELESS_RECALL_ENABLED"
  android:value="true" />

תנאים נוספים

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