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

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

โหลดเพื่อน

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

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