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

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

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

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

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

(אם עדיין לא סיימת) לפעול לפי ההוראות שבמאמר הגדרת שירותי המשחקים של Google Play.

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

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

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

מורידים את הספרייה האחרונה google-api-services-gamesומעלים אותה לשרת.

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

למידע נוסף, ראו את המאמר הכנה לביצוע קריאה ל-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();

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

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

SDK של Java

מגדירים את 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 עם המידע הנכון, צריך לבקש מזהה סשן של Recall מ-SDK של הלקוח, שאותו אתם שולחים לשרת של המשחק:

Kotlin

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

Java

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

שימוש ב-Recall API בתוך שרת המשחקים שלכם

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

אסימוני חנויות

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

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

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

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

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
}

אחזור אסימונים

כדי לאחזר את אסימון Recall, מקבלים את 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();