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

בצעו את השלבים במדריך הזה כדי להטמיע את ממשקי ה-API של חברים בקוד המשחק ב-Java.

טעינת חברים

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

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

  3. אם השחקן צריך להעניק גישה לרשימת החברים, השיחה תיכשל ב-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.
PlayGames.getPlayersClient(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 מחזיר כוונה להציג מסך שבו המשתמש יכול להשוות את עצמו לפרופיל של שחקן אחר.
  3. אפשר להשתמש בIntent בשלב הקודם כדי להתחיל פעילות.
// Retrieve and launch an Intent to show a player profile within the game.
PlayGames.getPlayersClient(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 מצרף באופן אוטומטי את "from-game-name>"):

// 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.
PlayGames.PlayersClient(this)
    .getCompareProfileIntentWithAlternativeNameHints(otherPlayerId, otherPlayerInGameName, currentPlayerInGameName)
    .addOnSuccessListener(new OnSuccessListener<Intent>() {
        @Override
        public void onSuccess(Intent  intent) {
          startActivityForResult(intent, RC_SHOW_PROFILE);
          // ...
        }});