Handle an event-based stat change

This topic provides example code for handling an event-based stat change. The examples are C++ code fragments that use the flat C API of the XBOX services API (XSAPI). XSAPI delivers the stat updates through the Real-Time Activity (RTA) service and manages the RTA subscriptions for you.

Before you begin

The code fragments share one scope and assume the following:

xboxLiveContext is an XblContextHandle for the signed-in user. To create one, call XblContextCreateHandle.
xboxUserId is the uint64_t XBOX user ID (XUID) of the player whose stats you want updates for.
scid is a const char* that contains the Service Configuration ID (SCID) for your title.
TotalPuzzlesSolved is an example stat name. Replace it with the name of an event-based stat that’s configured for your title.
LogToScreen is a printf-style logging function in your app.

To get notifications about event-based stat changes

Add a stat-changed handler.
Track the stats that you want updates for.

To clean up

Stop tracking stats.
Remove a stat-changed handler.

Add a stat-changed handler

Register an event handler for statistic change notifications by using the following example code. The event handler receives an XblStatisticChangeEventArgs object. If xboxLiveContext or the handler is null, XblUserStatisticsAddStatisticChangedHandler returns 0 and doesn’t register the handler.

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.");
}

Track the stats that you want updates for

Your handler receives updates only for stats that you track. Call XblUserStatisticsTrackStatistics with the users and stat names that you want updates for. You can change the set of tracked stats at any time, independently of your handlers.

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));
}

XblUserStatisticsSubscribeToStatisticChange and XblUserStatisticsUnsubscribeFromStatisticChange are deprecated. They still work, but they’ll be removed in a future release, and depending on your compiler settings, calls to them can produce deprecation warnings. Use XblUserStatisticsTrackStatistics and XblUserStatisticsStopTrackingStatistics instead.

Stop tracking stats

When you no longer need updates for specific stats, call XblUserStatisticsStopTrackingStatistics with the same users, SCID, and stat names that you tracked.

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

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

Alternatively, to stop updates for all the stats that you track for a set of users, call XblUserStatisticsStopTrackingUsers instead of XblUserStatisticsStopTrackingStatistics.

hr = XblUserStatisticsStopTrackingUsers(
    xboxLiveContext,
    &xboxUserId,
    1
);

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

XSAPI counts tracking requests. If you track the same stat for a user more than once, call a stop-tracking function the same number of times to stop the updates.

Remove a stat-changed handler

Remove an event handler for statistic change notifications by using the following example code.

XblUserStatisticsRemoveStatisticChangedHandler(
    xboxLiveContext,
    statisticChangedFunctionContext
);

XBOX Services

PlayFab

Before you begin

Add a stat-changed handler

Track the stats that you want updates for

Stop tracking stats

Remove a stat-changed handler

See also

​Before you begin

​Add a stat-changed handler

​Track the stats that you want updates for

​Stop tracking stats

​Remove a stat-changed handler

​See also

Before you begin

Add a stat-changed handler

Track the stats that you want updates for

Stop tracking stats

Remove a stat-changed handler

See also