เพื่อนในเกม Android

คู่มือนี้จะอธิบายวิธีใช้ API Friends ในโปรเจ็กต์ Android Studio

โหลดเพื่อน

คุณสามารถดึงข้อมูลและแสดง (ในเกม) รายชื่อผู้เล่นที่เป็นเพื่อนกับผู้ใช้ปัจจุบัน ในฐานะผู้ใช้ คุณสามารถควบคุมได้ว่าเกมใดบ้างที่มีสิทธิ์เข้าถึงรายชื่อเพื่อน เมื่อเรียกข้อมูลรายชื่อเพื่อน คุณต้องจัดการในกรณีที่ต้องใช้สิทธิ์ ข้อมูลทั้งหมดนี้รวมอยู่ใน API เพื่อให้การขอสิทธิ์เข้าถึงและการใช้รายชื่อเพื่อนในภายหลังเป็นเรื่องง่าย หากต้องการโหลดรายชื่อเพื่อน ให้ทำตามขั้นตอนต่อไปนี้

  1. เรียกใช้เมธอด PlayersClient.loadFriends() ซึ่งเป็นการเรียกใช้แบบไม่พร้อมกันที่แสดงผลออบเจ็กต์ Task
  2. หากการเรียกใช้สำเร็จ (ผู้ใช้ให้สิทธิ์เข้าถึงรายการเพื่อนแล้ว) บริการ Google Play Games จะแสดง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 จะแสดง 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 ตั้งชื่อเล่นของผู้เล่นที่ส่งคำเชิญให้เพื่อนจากในเกมเป็น "<ชื่อเฉพาะเกม> จาก <ชื่อเกมของคุณ>" โดย Play Games จะใส่ "จาก <ชื่อเกมของคุณ>" ต่อท้ายโดยอัตโนมัติ

// 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);
          // ...
        }});