שילוב ממשקי ה-API של Friends (Java)

עליכם לפעול לפי השלבים במדריך הזה כדי להטמיע את Friends APIs בקוד המשחק של Java.

טעינת חברים

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

1. קוראים לפונקציה PlayersClient.loadFriends() , שהיא קריאה אסינכרונית שמחזירה אובייקט Task.
2. אם השיחה בוצעה בהצלחה (המשתמש כבר קיבל גישה לחברים רשימה), Google Play Games Services מחזירה הודעה עם הערות PlayerBuffer שמייצג את החברים של המשתמש.

3. אם השחקן צריך להעניק גישה לרשימת החברים, השיחה תיכשל עם A FriendsResolutionRequiredException עדיין לא מוצגות תיבות דו-שיח.

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

   2. אם התוצאה של הפעילות של Intent היא Activity.RESULT_OK, אז התקבלה הסכמה. אפשר להתקשר שוב אל loadFriends() כדי להחזיר את החברים חדשה. אם התוצאה היא Activity.RESULT_CANCELLED, המשתמש לא מסכים/ה, ו-loadFriends() ימשיך להחזיר FriendsResolutionRequiredException.

הקוד הבא מראה איך להטמיע את הטעינה של רשימת החברים:

// Attempt loading friends.
// Register a success listener to handle the successfully loaded friends list.
// Register a failure listener to handle asking for permission to access the list.
Games.getPlayersClient(this, GoogleSignIn.getLastSignedInAccount(this))
    .loadFriends(PAGE_SIZE, /* forceReload= */ false)
    .addOnSuccessListener(
        new OnSuccessListener<AnnotatedData<PlayerBuffer>>() {
            @Override
            public void onSuccess(AnnotatedData<PlayerBuffer>  data) {
          PlayerBuffer playerBuffer = data.get();
          // ...
        })

    .addOnFailureListener(
        exception -> {
      if (exception instanceof FriendsResolutionRequiredException) {
        PendingIntent pendingIntent =
            ((FriendsResolutionRequiredException) task.getException())
            .getResolution();
        parentActivity.startIntentSenderForResult(
            pendingIntent.getIntentSender(),
            /* requestCode */ SHOW_SHARING_FRIENDS_CONSENT,
            /* fillInIntent */ null,
            /* flagsMask */ 0,
            /* flagsValues */ 0,
            /* extraFlags */ 0,
            /* options */ null);
     }
   });
 return;
}

הקוד הבא מראה איך לטפל בתוצאה של הבקשה לקבלת הסכמה:

/** Handle the activity result from the request for consent. */
@Override
public void onActivityResult(int requestCode, int result, Intent data) {
  if (requestCode == SHOW_SHARING_FRIENDS_CONSENT) {
    if (result == Activity.RESULT_OK) {
      // We got consent from the user to access their friends. Retry loading the friends
      callLoadFriends();
    } else {
      // User did not grant consent.
    }
  }
}

הצגת פרופיל של שחקן אחר

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

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

1. קוראים לפונקציה PlayersClient.getCompareProfileIntent() , שהיא קריאה אסינכרונית שמחזירה אובייקט Task.
2. אם הקריאה תתבצע בהצלחה, שירותי המשחקים של Google Play מחזירים Intent יציג מסך שבו המשתמש יכול להשוות את עצמו למשתמש אחר הפרופיל של השחקן.
3. כדי להתחיל פעילות, צריך להשתמש בIntent מהשלב הקודם.

// Retrieve and launch an Intent to show a player profile within the game.
Games.getPlayersClient(this, GoogleSignIn.getLastSignedInAccount(this))
    .getCompareProfileIntent(otherPlayerId)
    .addOnSuccessListener(new OnSuccessListener<Intent>() {
        @Override
        public void onSuccess(Intent  intent) {
          startActivityForResult(intent, RC_SHOW_PROFILE);
          // ...
        }});

אם למשחק יש שם משלו לשחקנים, ניתן להוסיף את השמות האלה לקריאה ל-API. כך Play Games יכול להגדיר את הכינוי של שחקנים ששולחים חבר הזמנות מתוך המשחק שלך ל-"<game-specific-name> מתוך <your-game-name>" (קובץ Play Games מוסיף באופן אוטומטי את המחרוזת "מ-" &lt;your-game-name&gt;&quot;):

// Show a player profile within the game, with additional hints containing the
// game-specific names for both players.
// - otherPlayerId is the Play Games playerId of the player to view.
// - otherPlayerInGameName is the game-specific name of the player being viewed.
// - currentPlayerInGameName is the game-specific name of the player who is signed
//   in. Hence if the player sends an invitation to the profile they are viewing,
//   their game-specific name can be included.
Games.PlayersClient(this, GoogleSignIn.getLastSignedInAccount(this))
    .getCompareProfileIntentWithAlternativeNameHints(otherPlayerId, otherPlayerInGameName, currentPlayerInGameName)
    .addOnSuccessListener(new OnSuccessListener<Intent>() {
        @Override
        public void onSuccess(Intent  intent) {
          startActivityForResult(intent, RC_SHOW_PROFILE);
          // ...
        }});