Updating title-managed Achievements

This topic covers the following:

Before you begin
Unlocking an achievement
Updating completion progress for an achievement
Troubleshooting

Before you begin

Your product uses the full XBOX services feature set. New products start with limited XBOX services, and achievements and gamerscore aren’t available until your product is onboarded. For more information, see Request product onboarding to enable full XBOX services.
You configured the achievement in Partner Center and published the XBOX services configuration to your development sandbox. For more information, see Configuring title-managed Achievements in Partner Center.
Your dev kit or Windows PC uses the same development sandbox, and you sign in with a test account that has access to that sandbox. For more information, see XBOX services sandboxes overview.
Your game initialized the Gaming Runtime and then called XblInitialize with an XblInitArgs structure whose scid member contains your Service Configuration ID (SCID). The SCID is case-sensitive. For more information, see How to use XBOX services APIs.
You signed in a user and created an XblContextHandle for that user by calling XblContextCreateHandle.

To reset achievements for a test account between test runs, use the Player Data Reset tool (XblPlayerDataReset.exe). To reset a player by XUID, the developer account that you sign in with by using XblDevAccount.exe needs the product-level Tools Access permission.

Unlocking an achievement

After your achievements are configured via Partner Center and published to your development sandbox, your title can unlock them by calling the XblAchievementsUpdateAchievementAsync API. For more information, see the example code in the next section. To unlock an achievement, set percentComplete to 100. If the user is online, the request is immediately sent to the XBOX services Achievements service and triggers the following user experiences.

The user receives an Achievement Unlocked notification.
The specified achievement appears as unlocked in the user’s achievement list for the title.
The unlocked achievement is added to the user’s activity feed.

The user experience is visually the same for achievements that use either event-based Achievements or title-managed Achievements.

If the user is offline, the unlock request is queued locally on the user’s device. When it has reestablished network connectivity, the request is automatically sent to the Achievements service (no action is required from the game to trigger this), and the previous user experiences occur as described.

Updating completion progress for an achievement

To update a user’s progress toward unlocking an achievement, call XblAchievementsUpdateAchievementAsync. Set the percentComplete argument to a whole number between 1-100. For more information, see the following example code. An achievement’s progress can only increase. If percentComplete is set to a number less than the achievement’s last percentComplete value, the update is ignored. For example, if the achievement’s percentComplete had previously been set to 75, sending an update with a value of 25 is ignored. The achievement is still displayed as 75 percent complete. If percentComplete is set to 100, the achievement is unlocked. If percentComplete is set to a number greater than 100, the API behaves as if you set the number to exactly 100.

Updating achievements for the current title

You can update achievements for the current title by calling XblAchievementsUpdateAchievementAsync, as follows. Flat C API

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*.
    auto result = XAsyncGetStatus(asyncBlock, false);
    if (SUCCEEDED(result))
    {
        // The achievement was updated.
    }
    else if (result == HTTP_E_STATUS_NOT_MODIFIED)
    {
        // The achievement wasn't updated.
    }
    else
    {
        // The achievement failed to update.
    }
};

HRESULT hr = XblAchievementsUpdateAchievementAsync(
    xboxLiveContext,
    xboxUserId,
    achievementId.c_str(),
    percentComplete,
    asyncBlock.get()
);
if (SUCCEEDED(hr))
{
    // The call succeeded, so release the std::unique_ptr ownership of XAsyncBlock* because the callback will take over ownership.
    // If the call fails, std::unique_ptr will keep ownership and delete XAsyncBlock*.
    asyncBlock.release();
}

For more information, see the following:

Updating achievements for a different title

You can update achievements for another titleId by using XblAchievementsUpdateAchievementForTitleIdAsync, as follows. Flat C API

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*.
    auto result = XAsyncGetStatus(asyncBlock, false);
    if (SUCCEEDED(result))
    {
        // The achievement was updated.
    }
    else if (result == HTTP_E_STATUS_NOT_MODIFIED)
    {
        // The achievement wasn't updated.
    }
    else
    {
        // The achievement failed to update.
    }
};

HRESULT hr = XblAchievementsUpdateAchievementForTitleIdAsync(
    xboxLiveContext,
    xboxUserId,
    titleId,
    scid,
    achievementId.c_str(),
    percentComplete,
    asyncBlock.get()
);
if (SUCCEEDED(hr))
{
    // The call succeeded, so release the std::unique_ptr ownership of XAsyncBlock* because the callback will take over ownership.
    // If the call fails, std::unique_ptr will keep ownership and delete XAsyncBlock*.
    asyncBlock.release();
}

For more information, see the following:

Troubleshooting

To group a failure HRESULT into an actionable category, call XblGetErrorCondition. Don’t retry failed updates yourself. If an update fails because of a network or authentication problem, throttling (HTTP 429), a server error (HTTP 5xx), or an unclassified error, XSAPI queues it as an offline event and sends it when the device is back online. In that case, XAsyncGetStatus returns the result of queuing the event, which is normally S_OK. If you retry, the service can receive the update twice. The following results can reach your game:

Result	Possible cause	What to do
`HTTP_E_STATUS_NOT_MODIFIED` (`XblErrorCondition::Http304NotModified`)	The achievement is already unlocked, or the new progress value isn’t higher than the value that the service has recorded.	No action is required.
Another HTTP 4xx status, such as 400, 403, or 404	The service rejected the request, for example because the achievement ID isn’t configured for your title or sandbox.	Check the achievement ID and your title’s configuration. Retrying the same request fails the same way.
`E_INVALIDARG`	The context, achievement ID, or async block is null.	Check the arguments. Pass a `percentComplete` value from 1 to 100.
`E_XBL_NOT_INITIALIZED`	XSAPI isn’t initialized.	Call `XblInitialize` before you update achievements.

Return to the top of this topic.

XBOX Services

PlayFab

Before you begin

Unlocking an achievement

Updating completion progress for an achievement

Updating achievements for the current title

Updating achievements for a different title

Troubleshooting

​Before you begin

​Unlocking an achievement

​Updating completion progress for an achievement

​Updating achievements for the current title

​Updating achievements for a different title

​Troubleshooting

Before you begin

Unlocking an achievement

Updating completion progress for an achievement

Updating achievements for the current title

Updating achievements for a different title

Troubleshooting