חברים במשחקי Android

במדריך זה מוסבר איך להשתמש בממשקי ה-API של חברים ב: פרויקטים של Android Studio.

טעינת חברים

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

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

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

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

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

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

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

// 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 Games Services יחזיר Intent יציג מסך שבו המשתמש יכול להשוות את עצמו למשתמש אחר הפרופיל של השחקן.
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 מצרפת באופן אוטומטי את המחרוזת <your-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);
          // ...
        }});