Getting title-managed Achievements

This topic covers the following:

Before you begin
Getting the achievements list
Getting the next page of achievements results
Getting a single achievement

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 your achievements 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.

Getting the achievements list

To get the achievements for the running title, call XblAchievementsGetAchievementsForTitleIdAsync, as follows.

Calling XblAchievementsGetAchievementsForTitleIdAsync

C++

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 XAsyncBlock*.

    XblAchievementsResultHandle resultHandle;
    auto hr = XblAchievementsGetAchievementsForTitleIdResult(asyncBlock, &resultHandle);

    if (SUCCEEDED(hr))
    {
        const XblAchievement* achievements = nullptr;
        size_t achievementsCount = 0;
        hr = XblAchievementsResultGetAchievements(resultHandle, &achievements, &achievementsCount);
        if (SUCCEEDED(hr))
        {
            for (size_t i = 0; i < achievementsCount; i++)
            {
                LogToScreen("Achievement %s: %s = %s", 
                    achievements[i].id, 
                    achievements[i].name,
                    (achievements[i].progressState == XblAchievementProgressState::Achieved) ? "Achieved" : "Not achieved");
            }
        }

        XblAchievementsResultCloseHandle(resultHandle); // When you're done with the handle, close it.
        achievements = nullptr; // Clear the array after calling XblAchievementsResultCloseHandle to avoid the pointer to freed memory.
        // Instead, you could keep the handle open and store it, for example to get the next page of results.
        // If you need another reference to the handle, call XblAchievementsResultDuplicateHandle().
    }
};

HRESULT hr = XblAchievementsGetAchievementsForTitleIdAsync(
    xboxLiveContext,
    xboxUserId,
    titleId,
    achievementType,
    unlockedOnly,
    orderBy,
    skipItems,
    maxItems,
    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:

Return to the top of this topic.

Getting the next page of achievements results

There might be more pages of achievements. To check, call XblAchievementsResultHasNext. To get the next page, call XblAchievementsResultGetNextAsync with the current result handle, and then call XblAchievementsResultGetNextResult in the callback. XblAchievementsResultGetNextResult returns a new result handle. Each result handle must be closed separately. Passing 0 for maxItems attempts to retrieve all items, but the service can provide a default page size and can return fewer items than requested even when more pages remain. Always check XblAchievementsResultHasNext instead of assuming that one call returns every achievement.

Processing every page of results

In the following example, instead of closing the result handle from XblAchievementsGetAchievementsForTitleIdResult, pass it to ProcessAchievementsPage. The function takes ownership of the handle that you pass to it and closes that handle exactly once. The current handle stays open until the request for the next page completes. C++

void ProcessAchievementsPage(XblAchievementsResultHandle resultHandle, XTaskQueueHandle queue, uint32_t maxItems)
{
    const XblAchievement* achievements = nullptr;
    size_t achievementsCount = 0;
    HRESULT hr = XblAchievementsResultGetAchievements(resultHandle, &achievements, &achievementsCount);
    if (SUCCEEDED(hr))
    {
        for (size_t i = 0; i < achievementsCount; i++)
        {
            LogToScreen("Achievement %s: %s = %s",
                achievements[i].id,
                achievements[i].name,
                (achievements[i].progressState == XblAchievementProgressState::Achieved) ? "Achieved" : "Not achieved");
        }
    }

    bool hasNext = false;
    if (SUCCEEDED(hr))
    {
        hr = XblAchievementsResultHasNext(resultHandle, &hasNext);
    }

    if (FAILED(hr) || !hasNext)
    {
        // This is the last page, or an error occurred. Close the handle.
        XblAchievementsResultCloseHandle(resultHandle);
        return;
    }

    struct NextPageContext
    {
        XblAchievementsResultHandle currentHandle;
        uint32_t maxItems;
    };

    auto asyncBlock = std::make_unique<XAsyncBlock>();
    asyncBlock->queue = queue;
    asyncBlock->context = new NextPageContext{ resultHandle, maxItems };
    asyncBlock->callback = [](XAsyncBlock* asyncBlock)
    {
        std::unique_ptr<XAsyncBlock> asyncBlockPtr{ asyncBlock }; // Take over ownership of XAsyncBlock*.
        std::unique_ptr<NextPageContext> context{ static_cast<NextPageContext*>(asyncBlock->context) };

        XblAchievementsResultHandle nextHandle = nullptr;
        HRESULT hr = XblAchievementsResultGetNextResult(asyncBlock, &nextHandle);

        // The request for the next page is complete, so close the handle for the previous page.
        XblAchievementsResultCloseHandle(context->currentHandle);

        if (SUCCEEDED(hr))
        {
            // Process the new page. ProcessAchievementsPage closes nextHandle.
            ProcessAchievementsPage(nextHandle, asyncBlock->queue, context->maxItems);
        }
        else
        {
            LogToScreen("XblAchievementsResultGetNextResult failed: 0x%08X", static_cast<unsigned int>(hr));
        }
    };

    hr = XblAchievementsResultGetNextAsync(resultHandle, maxItems, asyncBlock.get());
    if (SUCCEEDED(hr))
    {
        // The call succeeded, so release the std::unique_ptr ownership of XAsyncBlock* because the callback will take over ownership.
        asyncBlock.release();
    }
    else
    {
        // The callback won't run, so clean up here.
        delete static_cast<NextPageContext*>(asyncBlock->context);
        XblAchievementsResultCloseHandle(resultHandle);
    }
}

For more information, see the following:

Return to the top of this topic.

Getting a single achievement

To get a single achievement, call XblAchievementsGetAchievementAsync, 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 XAsyncBlock*.
    XblAchievementsResultHandle resultHandle;
    auto hr = XblAchievementsGetAchievementResult(asyncBlock, &resultHandle);

    if (SUCCEEDED(hr))
    {
        const XblAchievement* achievements = nullptr;
        size_t achievementsCount = 0;
        hr = XblAchievementsResultGetAchievements( resultHandle, &achievements, &achievementsCount );

        // Use the achievements array to read the achievement data.

        XblAchievementsResultCloseHandle(resultHandle); // When you're done with the handle, close it.
        achievements = nullptr; // Clear the array after calling XblAchievementsResultCloseHandle to avoid the pointer to freed memory.
    }
};

HRESULT hr = XblAchievementsGetAchievementAsync(
    xboxLiveContext,
    xboxUserId,
    scid,
    achievementId.c_str(),
    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:

Return to the top of this topic.

XBOX Services

PlayFab

Before you begin

Getting the achievements list

Calling XblAchievementsGetAchievementsForTitleIdAsync

Getting the next page of achievements results

Processing every page of results

Getting a single achievement

​Before you begin

​Getting the achievements list

​Calling XblAchievementsGetAchievementsForTitleIdAsync

​Getting the next page of achievements results

​Processing every page of results

​Getting a single achievement

Before you begin

Getting the achievements list

Calling XblAchievementsGetAchievementsForTitleIdAsync

Getting the next page of achievements results

Processing every page of results

Getting a single achievement