> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 好友清單

> 在 Unity 中建置 PlayFab 好友清單的快速入門教學課程，涵蓋如何新增、移除和顯示好友，以及連結 Steam、Facebook 和 XBOX 好友。

好友清單是提升玩家社交能力的絕佳功能。它們很容易使用，而且能讓排行榜對使用者更具吸引力。

## 必要條件

### SDK：Unity

* 已在 `PlayFabSharedSettings` 物件中設定遊戲 ID。
* 專案可以成功登入使用者。
* 遊戲至少有兩位已註冊的使用者。

## 關於好友

您遊戲中的任何玩家都可以與遊戲中的任何其他玩家成為好友。值得注意的是，PlayFab 上的好友關係是單向的。

如果 **Albert** 將 **Bob** 新增為好友，**Bob** *不需要*經過任何核准程序。事實上，**Bob** 可能毫不知情。

**Bob** 必須另外將 **Albert** 新增為好友，雙方的好友關係才會是*互相*的。如果您希望採用互惠規則，則必要時應由您的遊戲負責透過自訂遊戲伺服器或 CloudScript 邏輯來強制執行這些條件。

如果玩家已連結其 Steam、Facebook 或 XBOX Live 帳戶，而且其平台專屬好友也在玩您的遊戲，則也可以顯示這些好友。

## 結交好友

範例程式碼使用函式 `DisplayFriends()` 和 `DisplayError(string error)` 作為您應用程式 UI 的代理。您可以將這些函式貼到編輯器中，不需額外工作即可運作，或是以您自己的程式碼取代這些呼叫。

```csharp theme={null}
void DisplayFriends(List<FriendInfo> friendsCache) { friendsCache.ForEach(f => Debug.Log(f.FriendPlayFabId)); }
void DisplayPlayFabError(PlayFabError error) { Debug.Log(error.GenerateErrorReport()); }
void DisplayError(string error) { Debug.LogError(error); }
```

1. 玩家登入後，就可以存取好友的 UI。此功能通常至少包括新增、移除和顯示好友。
2. 若要取得玩家目前的好友清單，請使用 [GetFriendsList](xref:titleid.playfabapi.com.client.friendlistmanagement.getfriendslist) API 呼叫。

```csharp theme={null}
List<FriendInfo> _friends = null;

void GetFriends() {
    PlayFabClientAPI.GetFriendsList(new GetFriendsListRequest {
        IncludeSteamFriends = false,
        IncludeFacebookFriends = false,
        XboxToken = null
    }, result => {
        _friends = result.Friends;
        DisplayFriends(_friends); // triggers your UI
    }, DisplayPlayFabError);
}
```

[GetFriendsList](xref:titleid.playfabapi.com.client.friendlistmanagement.getfriendslist) 結果包含參數 friends，這是 [FriendInfo](xref:titleid.playfabapi.com.client.friendlistmanagement.getfriendslist#friendinfo) 物件的清單。

3. 若要將好友新增至玩家的好友清單，請使用 [AddFriend](xref:titleid.playfabapi.com.client.friendlistmanagement.addfriend) API 呼叫。

```csharp theme={null}
enum FriendIdType { PlayFabId, Username, Email, DisplayName };

void AddFriend(FriendIdType idType, string friendId) {
    var request = new AddFriendRequest();
    switch (idType) {
        case FriendIdType.PlayFabId:
            request.FriendPlayFabId = friendId;
            break;
        case FriendIdType.Username:
            request.FriendUsername = friendId;
            break;
        case FriendIdType.Email:
            request.FriendEmail = friendId;
            break;
        case FriendIdType.DisplayName:
            request.FriendTitleDisplayName = friendId;
            break;
    }
    // Execute request and update friends when we are done
    PlayFabClientAPI.AddFriend(request, result => {
        Debug.Log("Friend added successfully!");
    }, DisplayPlayFabError);
}
```

4. 若要從玩家的好友清單中移除玩家，請使用 [RemoveFriend](xref:titleid.playfabapi.com.client.friendlistmanagement.removefriend) API 呼叫。

```csharp theme={null}
// unlike AddFriend, RemoveFriend only takes a PlayFab ID
// you can get this from the FriendInfo object under FriendPlayFabId
void RemoveFriend(FriendInfo friendInfo) {
    PlayFabClientAPI.RemoveFriend(new RemoveFriendRequest {
        FriendPlayFabId = friendInfo.FriendPlayFabId
    }, result => {
        _friends.Remove(friendInfo);
    }, DisplayPlayFabError);
}
```

## 進一步了解

除了新增、移除和顯示之外，您還可以對好友執行其他操作。

### 為好友加上標籤

從 [GetFriendsList](xref:titleid.playfabapi.com.client.friendlistmanagement.getfriendslist) 擷取的 [FriendInfo](xref:titleid.playfabapi.com.client.friendlistmanagement.getfriendslist#friendinfo) 物件包含該好友的標籤清單。更新清單時，您會想要在此清單中新增和移除標籤，並將其包含在 API 呼叫中 (如下所示)。

```csharp theme={null}
// this REPLACES the list of tags on the server
// for updates, make sure this includes the original tag list
void SetFriendTags(FriendInfo friend, List<string> newTags)
{
    // update the tags with the edited list
    PlayFabClientAPI.SetFriendTags(new SetFriendTagsRequest
    {
        FriendPlayFabId = friend.FriendPlayFabId,
        Tags = newTags
    }, tagresult => {
        // Make sure to save new tags locally. That way you do not have to hard-update friendlist
        friend.Tags = newTags;
    }, DisplayPlayFabError);
}
```

您可以使用標籤來提供配對資訊 (例如，玩家不喜歡在困難難度下與標記為 **2tuff** 的好友一起遊玩)、實作好友群組，或只是用來儲存您需要的任何與關係相關的中繼資料。

請務必注意，PlayFab 目前不會以任何方式為這些標籤建立索引。[GetFriendsList](xref:titleid.playfabapi.com.client.friendlistmanagement.getfriendslist) 無法根據標籤進行篩選，因此必須在本機完成篩選。

考量此系統可能造成的任何效能影響時，請記住這一點。


## Related topics

- [XBOX 需求](/zh-TW/services/playfab/multiplayer/networking/xbox-requirements.md)
- [PlayFab Party 邀請與安全性模型](/zh-TW/services/playfab/multiplayer/networking/concepts-invitations-security-model.md)
- [XR070 好友清單](/zh-TW/publishing/certification/fma/xr-070.md)
- [人員系統 (好友清單)](/zh-TW/services/xbox-services/community/people-system/live-people-system-nav.md)
- [好友](/zh-TW/services/playfab/community/associations/friends/index.md)