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

# イベントベース統計変更の処理

> XBOX services API (XSAPI) のコードを使用してイベントベース統計の変更を追跡し、Real-Time Activity (RTA) サービスを使用してハンドラーをクリーンアップします。

このトピックでは、イベントベース統計の変更を処理するためのサンプル コードを提供します。これらの例は、XBOX services API (XSAPI) のフラット C API を使用する C++ のコード フラグメントです。XSAPI は Real-Time Activity (RTA) サービスを通じて統計の更新を配信し、RTA サブスクリプションを自動的に管理します。

## 始める前に

これらのコード フラグメントは 1 つのスコープを共有し、次のことを前提としています。

* `xboxLiveContext` は、サインインしているユーザーの `XblContextHandle` です。作成するには、[XblContextCreateHandle](https://docs.xbox.com/ja-jp/reference/live/xsapi-c/xbox_live_context_c/functions/xblcontextcreatehandle.md) を呼び出します。
* `xboxUserId` は、統計の更新を受け取るプレイヤーの `uint64_t` 型の XBOX ユーザー ID (XUID) です。
* `scid` は、タイトルのサービス構成 ID (SCID) を含む `const char*` です。
* `TotalPuzzlesSolved` は統計名の例です。タイトルに構成されているイベントベース統計の名前に置き換えてください。
* `LogToScreen` は、アプリ内の `printf` スタイルのログ関数です。

**イベントベース統計の変更に関する通知を取得するには**

1. [統計変更ハンドラーを追加します。](#add-a-stat-changed-handler)
2. [更新を受け取る統計を追跡します。](#track-the-stats-that-you-want-updates-for)

**クリーンアップするには**

1. [統計の追跡を停止します。](#stop-tracking-stats)
2. [統計変更ハンドラーを削除します。](#remove-a-stat-changed-handler)

## 統計変更ハンドラーを追加する

次のサンプル コードを使用して、統計変更通知のイベント ハンドラーを登録します。
イベント ハンドラーは [XblStatisticChangeEventArgs](https://docs.xbox.com/ja-jp/reference/live/xsapi-c/user_statistics_c/structs/xblstatisticchangeeventargs.md) オブジェクトを受け取ります。*xboxLiveContext* またはハンドラーが null の場合、`XblUserStatisticsAddStatisticChangedHandler` は 0 を返し、ハンドラーを登録しません。

```cpp theme={null}
void* context{ nullptr };
XblFunctionContext statisticChangedFunctionContext = XblUserStatisticsAddStatisticChangedHandler(
    xboxLiveContext,
    [](XblStatisticChangeEventArgs eventArgs, void* context) 
    {
        // Handle stat change. 
        LogToScreen("Statistic changed callback: stat changed (%s = %s)",
            eventArgs.latestStatistic.statisticName, 
            eventArgs.latestStatistic.value); 
    },
    context
);

if (statisticChangedFunctionContext == 0)
{
    LogToScreen("XblUserStatisticsAddStatisticChangedHandler failed.");
}
```

## 更新を受け取る統計を追跡する

ハンドラーは、追跡している統計についてのみ更新を受け取ります。更新を受け取るユーザーと統計名を指定して [XblUserStatisticsTrackStatistics](https://docs.xbox.com/ja-jp/reference/live/xsapi-c/user_statistics_c/functions/xbluserstatisticstrackstatistics.md) を呼び出します。追跡する統計のセットは、ハンドラーとは独立していつでも変更できます。

```cpp theme={null}
const char* statisticNames[] = { "TotalPuzzlesSolved" };

HRESULT hr = XblUserStatisticsTrackStatistics(
    xboxLiveContext,
    &xboxUserId,
    1,
    scid,
    statisticNames,
    _countof(statisticNames)
);

if (FAILED(hr))
{
    LogToScreen("XblUserStatisticsTrackStatistics failed: 0x%08X", static_cast<unsigned int>(hr));
}
```

> [!NOTE]
>
> `XblUserStatisticsSubscribeToStatisticChange` と `XblUserStatisticsUnsubscribeFromStatisticChange` は非推奨です。引き続き動作しますが、今後のリリースで削除される予定であり、コンパイラの設定によっては、これらの呼び出しで非推奨の警告が発生する場合があります。代わりに `XblUserStatisticsTrackStatistics` と `XblUserStatisticsStopTrackingStatistics` を使用してください。

## 統計の追跡を停止する

特定の統計の更新が不要になったら、追跡したときと同じユーザー、SCID、統計名を指定して [XblUserStatisticsStopTrackingStatistics](https://docs.xbox.com/ja-jp/reference/live/xsapi-c/user_statistics_c/functions/xbluserstatisticsstoptrackingstatistics.md) を呼び出します。

```cpp theme={null}
hr = XblUserStatisticsStopTrackingStatistics(
    xboxLiveContext,
    &xboxUserId,
    1,
    scid,
    statisticNames,
    _countof(statisticNames)
);

if (FAILED(hr))
{
    LogToScreen("XblUserStatisticsStopTrackingStatistics failed: 0x%08X", static_cast<unsigned int>(hr));
}
```

または、一連のユーザーについて追跡しているすべての統計の更新を停止するには、`XblUserStatisticsStopTrackingStatistics` の代わりに [XblUserStatisticsStopTrackingUsers](https://docs.xbox.com/ja-jp/reference/live/xsapi-c/user_statistics_c/functions/xbluserstatisticsstoptrackingusers.md) を呼び出します。

```cpp theme={null}
hr = XblUserStatisticsStopTrackingUsers(
    xboxLiveContext,
    &xboxUserId,
    1
);

if (FAILED(hr))
{
    LogToScreen("XblUserStatisticsStopTrackingUsers failed: 0x%08X", static_cast<unsigned int>(hr));
}
```

XSAPI は追跡要求の数をカウントします。ユーザーの同じ統計を複数回追跡した場合、更新を停止するには、追跡停止関数を同じ回数呼び出してください。

## 統計変更ハンドラーを削除する

次のサンプル コードを使用して、統計変更通知のイベント ハンドラーを削除します。

```cpp theme={null}
XblUserStatisticsRemoveStatisticChangedHandler(
    xboxLiveContext,
    statisticChangedFunctionContext
);
```

## 関連項目

* [RTA サービスのプログラミング](https://docs.xbox.com/ja-jp/services/xbox-services/fundamentals/rta/how-to/live-programming-rta.md)
* [XblStatisticChangeEventArgs](https://docs.xbox.com/ja-jp/reference/live/xsapi-c/user_statistics_c/structs/xblstatisticchangeeventargs.md)
* [XblUserStatisticsAddStatisticChangedHandler](https://docs.xbox.com/ja-jp/reference/live/xsapi-c/user_statistics_c/functions/xbluserstatisticsaddstatisticchangedhandler.md)
* [XblUserStatisticsTrackStatistics](https://docs.xbox.com/ja-jp/reference/live/xsapi-c/user_statistics_c/functions/xbluserstatisticstrackstatistics.md)
* [XblUserStatisticsStopTrackingStatistics](https://docs.xbox.com/ja-jp/reference/live/xsapi-c/user_statistics_c/functions/xbluserstatisticsstoptrackingstatistics.md)
* [XblUserStatisticsStopTrackingUsers](https://docs.xbox.com/ja-jp/reference/live/xsapi-c/user_statistics_c/functions/xbluserstatisticsstoptrackingusers.md)
* [XblUserStatisticsRemoveStatisticChangedHandler](https://docs.xbox.com/ja-jp/reference/live/xsapi-c/user_statistics_c/functions/xbluserstatisticsremovestatisticchangedhandler.md)


## Related topics

- [XblUserStatisticsAddStatisticChangedHandler](https://docs.xbox.com/ja-jp/reference/live/xsapi-c/user_statistics_c/functions/xbluserstatisticsaddstatisticchangedhandler.md)
- [イベントベースの統計の取得](https://docs.xbox.com/ja-jp/services/xbox-services/player-data/stats-leaderboards/event-based/how-to/live-getting-eb-stat.md)
- [イベントベースの統計の概要](https://docs.xbox.com/ja-jp/services/xbox-services/player-data/stats-leaderboards/event-based/live-stats-eb-overview.md)
- [イベントベースの統計とリーダーボードのイベント](https://docs.xbox.com/ja-jp/services/xbox-services/player-data/stats-leaderboards/event-based/events/index.md)
- [イベントベースの統計を駆動するためのイベントの書き込み](https://docs.xbox.com/ja-jp/services/xbox-services/player-data/stats-leaderboards/event-based/how-to/live-sending-eb-stat.md)