請按照本指南中的步驟,在 Java 遊戲程式碼中實作 Friends API。
載入好友
您可以擷取並顯示 (遊戲中) 目前使用者好友的玩家名單。使用者可以管理哪些遊戲可以存取好友名單。擷取好友名單時,您必須處理有權限要求的情況。這些都會在 API 中封裝以要求存取權,然後才能以直接的工作方式使用好友清單。如要載入好友名單,請按照下列步驟操作:
- 呼叫
PlayersClient.loadFriends()
方法,此方法會傳回Task
物件的非同步呼叫。 - 如果呼叫成功 (使用者已獲授權可存取好友清單),Google Play 遊戲服務就會傳回已加上註解的
PlayerBuffer
,代表使用者的好友。 如果玩家需要授予好友名單的存取權,呼叫就會失敗並顯示
FriendsResolutionRequiredException
。此時尚未顯示任何對話方塊。- 這個例外狀況包含會觸發對話方塊的
Intent
,要求玩家取得同意。您可以立即啟動此Intent
以開啟同意聲明對話方塊。此Intent
只能使用一次。 如果
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 遊戲個人資料檢視畫面。此檢視畫面可讓玩家針對檢視的目標玩家傳送及接受好友邀請。此檢視畫面不需要存取好友名單。另外,如果遊戲的玩家名稱概念與 Play 遊戲玩家 ID 不同,您可以將這些名稱傳遞至個人資料檢視畫面,方便納入好友邀請中,提供額外背景資訊。
如要顯示其他玩家的個人資料,請按照下列步驟操作:
- 呼叫
PlayersClient.getCompareProfileIntent()
方法 (非同步呼叫,可傳回Task
物件)。 - 如果呼叫成功,Google Play 遊戲服務會傳回意圖並顯示畫面,讓使用者可以比較自己與其他玩家的個人資料。
- 使用上一個步驟中的
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 新增至 API 呼叫。這樣一來,玩家在您的遊戲中傳送好友邀請至「<your-game-name> 的 <game-specific-name>」時,Play Games 就會自動「從 <your-game-name>」附加,Play 遊戲就可以設定玩家的暱稱:
// 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);
// ...
}});