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

# Atualizando conquistas gerenciadas pelo título

> Código de exemplo da XSAPI que mostra como desbloquear uma conquista do XBOX Live gerenciada pelo título ou relatar o progresso de conclusão com XblAchievementsUpdateAchievementAsync.

<a id="top" />

Este tópico aborda o seguinte:

* [Desbloqueando uma conquista](#unlocking-an-achievement)
* [Atualizando o progresso de conclusão de uma conquista](#updating-an-achievement)

<a id="unlocking-an-achievement" />

## Desbloqueando uma conquista

Depois que suas conquistas forem configuradas no Partner Center e publicadas na sua sandbox de desenvolvimento, seu título poderá desbloqueá-las chamando a API [XblAchievementsUpdateAchievementAsync](/pt-BR/reference/live/xsapi-c/achievements_c/functions/xblachievementsupdateachievementasync).
Para obter mais informações, veja o código de exemplo na próxima seção.

Para desbloquear uma conquista, defina `percentComplete` como 100.
Se o usuário estiver online, a solicitação será enviada imediatamente ao serviço de conquistas dos serviços XBOX e disparará as seguintes experiências do usuário.

* O usuário recebe uma notificação de Conquista desbloqueada.
* A conquista especificada aparece como desbloqueada na lista de conquistas do usuário para o título.
* A conquista desbloqueada é adicionada ao feed de atividades do usuário.

<Note>A experiência do usuário é visualmente a mesma para conquistas que usam conquistas baseadas em eventos ou conquistas gerenciadas pelo título.</Note>

Se o usuário estiver offline, a solicitação de desbloqueio será colocada em fila localmente no dispositivo do usuário.
Quando a conectividade de rede for restabelecida, a solicitação será enviada automaticamente ao serviço de conquistas (nenhuma ação do jogo é necessária para disparar isso), e as experiências do usuário anteriores ocorrerão conforme descrito.

<a id="updating-an-achievement" />

## Atualizando o progresso de conclusão de uma conquista

Para atualizar o progresso de um usuário para desbloquear uma conquista, chame [XblAchievementsUpdateAchievementAsync](/pt-BR/reference/live/xsapi-c/achievements_c/functions/xblachievementsupdateachievementasync). Defina o argumento `percentComplete` como um número inteiro entre 1 e 100.
Para obter mais informações, veja o código de exemplo a seguir.

O progresso de uma conquista só pode aumentar.
Se `percentComplete` for definido como um número menor que o último valor de `percentComplete` da conquista, a atualização será ignorada.
Por exemplo, se o `percentComplete` da conquista tiver sido definido anteriormente como 75, o envio de uma atualização com o valor 25 será ignorado. A conquista continuará sendo exibida como 75% concluída.

Se `percentComplete` for definido como 100, a conquista será desbloqueada.

Se `percentComplete` for definido como um número maior que 100, a API se comportará como se você tivesse definido o número como exatamente 100.

### Atualizando conquistas para o título atual

Você pode atualizar conquistas para o título atual chamando [XblAchievementsUpdateAchievementAsync](/pt-BR/reference/live/xsapi-c/achievements_c/functions/xblachievementsupdateachievementasync), da seguinte forma.

**API Flat C**

```cpp theme={null}
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();
}
```

Para obter mais informações, veja o seguinte:

* [XAsyncBlock](/pt-BR/reference/system/xasync/structs/xasyncblock)
* [XAsyncGetStatus](/pt-BR/reference/system/xasync/functions/xasyncgetstatus)
* [XblAchievementsUpdateAchievementAsync](/pt-BR/reference/live/xsapi-c/achievements_c/functions/xblachievementsupdateachievementasync)

### Atualizando conquistas para um título diferente

Você pode atualizar conquistas para outro `titleId` usando [XblAchievementsUpdateAchievementForTitleIdAsync](/pt-BR/reference/live/xsapi-c/achievements_c/functions/xblachievementsupdateachievementfortitleidasync), da seguinte forma.

**API Flat C**

```cpp theme={null}
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();
}
```

Para obter mais informações, veja o seguinte:

* [XAsyncBlock](/pt-BR/reference/system/xasync/structs/xasyncblock)
* [XAsyncGetStatus](/pt-BR/reference/system/xasync/functions/xasyncgetstatus)
* [XblAchievementsUpdateAchievementForTitleIdAsync](/pt-BR/reference/live/xsapi-c/achievements_c/functions/xblachievementsupdateachievementfortitleidasync)

[Voltar ao início deste tópico.](#top)


## Related topics

- [Código de exemplo de conquistas gerenciadas pelo título](/pt-BR/services/xbox-services/player-data/achievements/title-managed/how-to/live-achievements-howto-nav.md)
- [Estatísticas e conquistas](/pt-BR/build/steam-porting-guide/features/stats-and-achievements.md)
- [Instruções](/pt-BR/services/xbox-services/player-data/achievements/title-managed/how-to/index.md)
- [Integrar o GDK a um projeto do Unreal Engine anterior à versão 4.26](/pt-BR/build/gdk-and-engines/unreal/unreal-legacy.md)
- [Conquistas gerenciadas pelo título](/pt-BR/services/xbox-services/player-data/achievements/title-managed/live-achievements-tm-nav.md)