> ## 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.

# 社群統計資料

> 建立 PlayFab 社群統計資料，彙總遊戲中所有玩家的值，以支援全域目標、活動和共同里程碑。

社群統計資料是提高參與度並促進玩家投入遊戲的強大工具。透過在遊戲層級彙總統計資料，開發人員可以建立鼓勵玩家合作的共同目標和挑戰。此做法會將個別玩家的動作轉變為對整個社群目標的貢獻，在玩家共同努力達成集體里程碑的過程中，推動持續的參與。玩家會覺得自己的個人貢獻對更大的社群很重要，進而加強他們與遊戲和其他玩家之間的連結。

例如，假設實作一場全域首領戰，整個玩家群必須在一週內共同完成 1000 萬次擊殺，才能解鎖特殊的遊戲內活動。當玩家看到社群進度列隨著他們的每一次貢獻而前進時，就會受到激勵而協助達成目標。這種行為會形成強大的投入和參與回饋循環，特別是在搭配即時進度更新和沿途的里程碑獎勵時。

使用 PlayFab，您可以透過定義兩個統計資料來輕鬆管理社群統計資料：一個在玩家層級 (彙總來源)，另一個在遊戲或群組層級 (彙總目的地)。對玩家統計資料所做的更新會自動彙總至目的地統計資料。若要擷取目前的社群分數，請讀取目的地實體的統計資料。

PlayFab 支援兩種類型的社群統計資料：

* **遊戲層級**：將所有玩家更新彙總至單一遊戲範圍的統計資料。非常適合整個玩家群共享的全域目標。
* **群組層級**：將玩家更新彙總至群組實體統計資料。非常適合部落挑戰、公會目標，或部分玩家朝共同目標努力的團隊目標。

## 遊戲層級社群統計資料

### 建立來源統計資料定義

首先，為玩家建立統計資料定義，作為彙總來源：

```C# theme={null}
// Use the PlayFabAuthenticationContext to call the API
PlayFabProgressionInstanceAPI statsAPI = new PlayFabProgressionInstanceAPI(context);
CreateStatisticDefinitionRequest statDefinitionRequest = new CreateStatisticDefinitionRequest()
{
    Name = "sourceStat",
    AuthenticationContext = context,
    EntityType = "title_player_account",
    VersionConfiguration = new VersionConfiguration()
    {
        MaxQueryableVersions = 1,
        ResetInterval = ResetInterval.Manual,
    },
    Columns = new List<StatisticColumn>()
    {
        new StatisticColumn()
        {
            Name = "Eliminations",
            AggregationMethod = StatisticAggregationMethod.Sum,
        },
    },
};

PlayFabResult<PlayFab.LeaderboardsModels.EmptyResponse> createStatDefResult = await statsAPI.CreateStatisticDefinitionAsync(statDefinitionRequest);
```

### 建立目的地統計資料定義

接著，為遊戲建立統計資料定義，作為彙總目的地。將玩家統計資料定義指定為遊戲統計資料定義的彙總來源：

```C# theme={null}
// Use the PlayFabAuthenticationContext to call the API
PlayFabProgressionInstanceAPI statsAPI = new PlayFabProgressionInstanceAPI(context);
CreateStatisticDefinitionRequest statDefinitionRequest = new CreateStatisticDefinitionRequest()
{
    Name = "communityStat",
    AuthenticationContext = context,
    EntityType = "title",
    Columns = new List<StatisticColumn>()
    {
        new StatisticColumn()
        {
            Name = "Eliminations",
            AggregationMethod = StatisticAggregationMethod.Sum,
        },
    },
    AggregationSources = new string[] { "sourceStat" };
};

PlayFabResult<PlayFab.LeaderboardsModels.EmptyResponse> createStatDefResult = await statsAPI.CreateStatisticDefinitionAsync(statDefinitionRequest);
```

<Note>
  ***注意：*** 將
</Note>

`EntityType` 設定為 `title`，並將 `AggregationSources` 設定為參考在玩家層級定義的統計資料。

建立社群統計資料後，在玩家層級所做的任何更新都會開始在遊戲層級彙總。系統只會彙總新的更新。如果來源統計資料已存在一段時間，系統不會在遊戲層級回填這些歷史值。

### 讀取遊戲社群統計資料

若要取得遊戲層級統計資料的目前分數，請讀取遊戲實體的統計資料：

```C# theme={null}
// Use the PlayFabAuthenticationContext to call the API
PlayFabProgressionInstanceAPI statsAPI = new PlayFabProgressionInstanceAPI(context);

GetStatisticsRequest request = new GetStatisticsRequest()
{
    AuthenticationContext = context,
    Entity = new PlayFab.LeaderboardsModels.EntityKey()
    {
        Id = "<title id in hex>",
        Type = "title"
    },
};

PlayFabResult<GetStatisticsResponse> result = await statsAPI.GetStatisticsAsync(request); 
```

## 群組層級社群統計資料

群組層級社群統計資料可讓您彙總特定群組 (例如部落或公會) 內的玩家動作。這種彙總適用於部落挑戰之類的案例，其中成員共同朝共同目標努力。

### 建立目的地統計資料定義

建立 `EntityType` 設定為 `group` 的統計資料定義。將玩家統計資料定義指定為彙總來源：

```C# theme={null}
// Use the PlayFabAuthenticationContext to call the API
PlayFabProgressionInstanceAPI statsAPI = new PlayFabProgressionInstanceAPI(context);
CreateStatisticDefinitionRequest statDefinitionRequest = new CreateStatisticDefinitionRequest()
{
    Name = "groupCommunityStat",
    AuthenticationContext = context,
    EntityType = "group",
    Columns = new List<StatisticColumn>()
    {
        new StatisticColumn()
        {
            Name = "Eliminations",
            AggregationMethod = StatisticAggregationMethod.Sum,
        },
    },
    AggregationSources = new string[] { "sourceStat" }
};

PlayFabResult<PlayFab.LeaderboardsModels.EmptyResponse> createStatDefResult = await statsAPI.CreateStatisticDefinitionAsync(statDefinitionRequest);
```

<Note>
  來源統計資料定義 (玩家層級) 與用於遊戲層級社群統計資料的定義相同。您可以重複使用現有的來源統計資料定義。
</Note>

### 更新來源統計資料

為群組層級彙總更新玩家的來源統計資料時，請在 `StatisticUpdate` 物件的 `AggregationTargetEntityKeys` 屬性中指定目標群組實體。此屬性會告訴 PlayFab 要將更新彙總至哪個群組實體。

```C# theme={null}
// Use the PlayFabAuthenticationContext to call the API
PlayFabProgressionInstanceAPI statsAPI = new PlayFabProgressionInstanceAPI(context);

UpdateStatisticsRequest request = new UpdateStatisticsRequest()
{
    AuthenticationContext = context,
    Entity = new PlayFab.LeaderboardsModels.EntityKey()
    {
        Id = "<player entity id>",
        Type = "title_player_account"
    },
    Statistics = new List<StatisticUpdate>()
    {
        new StatisticUpdate()
        {
            Name = "sourceStat",
            Scores = new List<string> { "5" },
            AggregationTargetEntityKeys = new List<PlayFab.LeaderboardsModels.EntityKey>()
            {
                new PlayFab.LeaderboardsModels.EntityKey()
                {
                    Id = "<group entity id>",
                    Type = "group"
                }
            }
        }
    }
};

PlayFabResult<UpdateStatisticsResponse> result = await statsAPI.UpdateStatisticsAsync(request);
```

<Info>
  對於遊戲層級社群統計資料，不需要 `AggregationTargetEntityKeys`，因為遊戲是預設的彙總目標。對於群組層級社群統計資料，您必須指定群組實體索引鍵。目前，您只能在 `AggregationTargetEntityKeys` 中指定一個實體索引鍵。
</Info>

### 讀取群組社群統計資料

若要取得群組社群統計資料的目前分數，請讀取群組實體的統計資料：

```C# theme={null}
// Use the PlayFabAuthenticationContext to call the API
PlayFabProgressionInstanceAPI statsAPI = new PlayFabProgressionInstanceAPI(context);

GetStatisticsRequest request = new GetStatisticsRequest()
{
    AuthenticationContext = context,
    Entity = new PlayFab.LeaderboardsModels.EntityKey()
    {
        Id = "<group entity id>",
        Type = "group"
    },
};

PlayFabResult<GetStatisticsResponse> result = await statsAPI.GetStatisticsAsync(request);
```

## 限制

* 您只能為社群統計資料指定一個彙總來源。
* 您無法為社群統計資料指定版本設定。您為來源統計資料指定的版本設定也會套用至社群統計資料。
* 社群統計資料的 `EntityType` 必須是 `title` 或 `group`。
* 您無法對任何資料行使用 `Last` 彙總。
* 更新來源統計資料時，您只能在 `AggregationTargetEntityKeys` 中指定一個實體索引鍵。

## 另請參閱

* [建立基本統計資料](/zh-TW/services/playfab/player-progression/statistics/create-basic-statistics)
* [統計資料的進階運用](/zh-TW/services/playfab/player-progression/statistics/doing-more-statistics)
* [季節性統計資料](/zh-TW/services/playfab/player-progression/statistics/seasonal-statistics)
* [將內容資料新增至統計資料](/zh-TW/services/playfab/player-progression/statistics/metadata-statistics)
* [API 參考](/zh-TW/services/playfab/player-progression/statistics/api-reference)
* [限制](/zh-TW/services/playfab/player-progression/statistics/limits-statistics)
* [配額](/zh-TW/services/playfab/player-progression/statistics/quota-statistics)
* [統計資料計量](/zh-TW/services/playfab/pricing/meters/statistics-meters)


## Related topics

- [PlayFab 玩家進度文件](/zh-TW/services/playfab/player-progression/index.md)
- [統計資料計量](/zh-TW/services/playfab/pricing/meters/statistics-meters.md)
- [事件型統計資料與遊戲管理型統計資料](/zh-TW/services/xbox-services/player-data/stats-leaderboards/live-stats-eb-vs-tm.md)
- [遊戲管理型統計資料概觀](/zh-TW/services/xbox-services/player-data/stats-leaderboards/title-managed/live-stats-tm-overview.md)
- [精選統計資料概觀](/zh-TW/services/xbox-services/player-data/stats-leaderboards/featured-stats/live-featuredstats-overview.md)