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

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

טעינת חברים

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

  1. קוראים ל-method‏ 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.
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. קוראים ל-method‏ PlayersClient.getCompareProfileIntent(), שהיא קריאה אסינכרונית שמחזירה אובייקט Task.
  2. אם הקריאה תתבצע בהצלחה, שירותי Google Play Games יחזירו כוונה (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 מצרפת באופן אוטומטי את "מ-<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.
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);
          // ...
        }});