Writing title-managed stats

This topic provides example code showing how to write title-managed stats.

The stored stat value reflects the value most recently written through these APIs. However, the global leaderboard for that stat retains only the highest recorded value per player, so writing a lower value doesn’t lower the player’s leaderboard position. For details and alternatives, see the title-managed Stats overview and the XblLeaderboardQuery reference.

Updating only the specified title-managed stats

You can send specified stats that you want to update, by calling XblTitleManagedStatsUpdateStatsAsync, which selectively updates the calling user’s stats. A specified stat will only be overwritten if it already exists. Any stats that aren’t specified in the call to XblTitleManagedStatsUpdateStatsAsync stay unchanged. C API

// "HighScore" represents a stat that your game already wrote for this user.
XblTitleManagedStatistic stats[] =
{
    { "HighScore", XblTitleManagedStatType::Number, 1200.0, nullptr }
};

auto asyncBlock = std::make_unique<XAsyncBlock>();
asyncBlock->queue = queue; // Your game's task queue.
asyncBlock->context = nullptr;
asyncBlock->callback = [](XAsyncBlock* asyncBlock)
{
    std::unique_ptr<XAsyncBlock> asyncBlockPtr{ asyncBlock }; // Take over ownership of the XAsyncBlock*
    HRESULT hr = XAsyncGetStatus(asyncBlock, false);
    if (FAILED(hr))
    {
        // The outcome of the update isn't confirmed. Keep the stat values in your game's data and
        // submit them again later.
    }
};

// xboxLiveContext is the XblContextHandle for the user whose stats you're updating.
HRESULT hr = XblTitleManagedStatsUpdateStatsAsync(
    xboxLiveContext,
    stats,
    _countof(stats),
    asyncBlock.get()
);

if (SUCCEEDED(hr))
{
    // The call succeeded, so release the std::unique_ptr ownership of XAsyncBlock* since the callback will take over ownership.
    asyncBlock.release();
}
else
{
    // The request didn't start, and the std::unique_ptr deletes the XAsyncBlock*.
    // Keep the stat values in your game's data and submit them again later.
}

If the call fails for any reason, your game is responsible for submitting the request again. Reference

Writing all the stats you want to keep, and deleting the rest

To write only the title-managed stats that you want to keep, and delete the rest, call XblTitleManagedStatsWriteAsync with all the stats you want to write. Any stats that are not included in the call will be removed. This call replaces the last stats document on the service with a new stats document that contains only the values you sent. The xboxUserId argument must be the user that the XblContextHandle was created for; otherwise, the call returns E_INVALIDARG. C API

std::vector<XblTitleManagedStatistic> statList;
statList.push_back(XblTitleManagedStatistic{ "MyStatName1", XblTitleManagedStatType::Number, 200 });
statList.push_back(XblTitleManagedStatistic{ "MyStatName2", XblTitleManagedStatType::String, 0, "SomeValue" });

auto asyncBlock = std::make_unique<XAsyncBlock>();
asyncBlock->queue = queue;
asyncBlock->context = nullptr;
asyncBlock->callback = [](XAsyncBlock* asyncBlock)
{
    std::unique_ptr<XAsyncBlock> asyncBlockPtr{ asyncBlock }; // Take over ownership of the XAsyncBlock*
    HRESULT hr = XAsyncGetStatus(asyncBlock, false);
};

HRESULT hr = XblTitleManagedStatsWriteAsync(
    xboxLiveContext, 
    xboxUserId, 
    statList.data(), statList.size(), 
    asyncBlock.get());
if (SUCCEEDED(hr))
{
    // The call succeeded, so release the std::unique_ptr ownership of XAsyncBlock* since the callback will take over ownership.
    // If the call fails, the std::unique_ptr will keep ownership and delete the XAsyncBlock*
    asyncBlock.release();
}

Reference

XBOX Services

PlayFab

Updating only the specified title-managed stats

Writing all the stats you want to keep, and deleting the rest

​Updating only the specified title-managed stats

​Writing all the stats you want to keep, and deleting the rest

Updating only the specified title-managed stats

Writing all the stats you want to keep, and deleting the rest