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

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

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

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

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

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

.

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

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

3. הורדת ספריית Java בצד השרת ל-PlayGamesServices

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

4. הכנת פרטי הכניסה לקריאות ל-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();

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

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

אחסון טוקנים

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

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

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

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

import com.google.api.services.games.Games.Recall.LinkPersona;
import com.google.api.services.games.model.LinkPersonaRequest;
import com.google.api.services.games.model.LinkPersonaResponse;
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;
import com.google.api.services.games.model.RetrievePlayerTokensResponse;
import com.google.api.services.games.model.RecallToken;

// ...

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
}

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

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

import com.google.api.services.games.Games;
import com.google.api.services.games.model.RetrieveDeveloperGamesLastPlayerTokenResponse;
import com.google.api.services.games.model.GamePlayerToken;
import com.google.api.services.games.model.RecallToken;

// ...

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

RetrieveDeveloperGamesLastPlayerTokenResponse response =
        gamesApi.recall().lastTokenFromAllDeveloperGames(recallSessionId)
        .execute();

if (response.hasGamePlayerToken()) {
    GamePlayerToken gamePlayerToken = response.getGamePlayerToken();

    // The ID of the application that the token is associated with.
    String applicationId = gamePlayerToken.getApplicationId();

    // Same string as was written in LinkPersona call.
    RecallToken recallToken = gamePlayerToken.getRecallToken();

    // Decrypt and recover in-game account.
}

כל אסימוני הביטול ברשימת משחקים נתונה שבבעלות חשבון הפיתוח

כדי לאחזר את כל האסימונים שמשויכים לרשימת משחקים שבבעלות חשבון הפיתוח שלכם ב-Google Play Console, צריך לקבל את recallSessionId מהלקוח ולהעביר אותו ל-API של gamesPlayerTokens. מספקים רשימה של מזהי אפליקציות.

import com.google.api.services.games.Games;
import com.google.api.services.games.model.RetrieveGamesPlayerTokensResponse;
import com.google.api.services.games.model.GamePlayerToken;
import com.google.api.services.games.model.RecallToken;

// ...

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

// Application IDs for which you would like to retrieve the recall tokens.
List<String> applicationIds = ...

RetrieveGamesPlayerTokensResponse response =
gamesApiClient
        .recall()
        .gamesPlayerTokens(recallSessionId)
        .setApplicationIds(applicationIds)
        .execute();

for (GamePlayerToken gamePlayerToken : response.getGamePlayerTokens()) {
    // The ID of the application that the token is associated with.
    String applicationId  = gamePlayerToken.getApplicationId();


    // Same string as was written in LinkPersona call.
    RecallToken recallToken = gamePlayerToken.getRecallToken();

    // Decrypt and recover in-game account.
}

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

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

import com.google.api.services.games.Games;
import com.google.api.services.games.model.UnlinkPersonaRequest;
import com.google.api.services.games.model.UnlinkPersonaResponse;

// ...

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();

boolean unlinked = unlinkPersonaResponse.isUnlinked();

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

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

  1. מפעילים ריקול ללא פרופיל בפרויקט המשחק ב-PGS במסוף הפיתוח של Play. בוחרים באפשרות &#39;הפעלת אחסון&#39;.
  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, וקבלת הסכמה מתאימה ממשתמשי הקצה לשיתוף כזה, שתואמת לכל הדרישות המשפטיות הרלוונטיות.