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

Unity SDK

אם עדיין לא עשיתם זאת, מגדירים את Unity SDK בלקוח.

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

PlayGamesPlatform.Instance.RequestRecallAccess(
    recallAccess => {
        string recallSessionId = recallAccess.sessionId;
        // Send the recallSessionId to your game server
    });

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

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

אחסון טוקנים

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

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

אחזור טוקנים

יש שלוש אפשרויות לאחזור אסימון, בהתאם לצרכים של המשחקים שלכם. אתם יכולים לבקש את הפרטים הבאים:

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

טוקנים של ריקול ברמת המשחק

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

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, וקבלת הסכמה מתאימה ממשתמשי הקצה לשיתוף כזה, שתואמת לכל הדרישות המשפטיות הרלוונטיות.