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

# Actualización de logros administrados por el título

> Código de ejemplo de XSAPI que muestra cómo desbloquear un logro administrado por el título de los servicios de XBOX o notificar el progreso de finalización con XblAchievementsUpdateAchievementAsync.

En este tema se tratan los siguientes puntos:

* [Antes de empezar](#before-you-begin)
* [Desbloqueo de un logro](#unlocking-an-achievement)
* [Actualización del progreso de finalización de un logro](#updating-an-achievement)
* [Solución de problemas](#troubleshooting)

## Antes de empezar

* Su producto usa el conjunto completo de características de los servicios de XBOX. Los productos nuevos empiezan con servicios de XBOX limitados, y los logros y el gamerscore no están disponibles hasta que se incorpora el producto. Para obtener más información, consulte [Solicitar la incorporación del producto para habilitar todos los servicios de XBOX](https://docs.xbox.com/es/home/onboarding.md#request-product-onboarding-to-enable-full-xbox-services).
* Configuró el logro en Partner Center y publicó la configuración de los servicios de XBOX en su sandbox de desarrollo. Para obtener más información, consulte [Configuración de logros administrados por el título en Partner Center](https://docs.xbox.com/es/services/xbox-services/player-data/achievements/title-managed/config/live-achievements-tm-config.md).
* Su kit de desarrollo o PC con Windows usa el mismo sandbox de desarrollo e inicia sesión con una cuenta de prueba que tiene acceso a ese sandbox. Para obtener más información, consulte [Información general sobre los sandboxes de los servicios de XBOX](https://docs.xbox.com/es/services/xbox-services/fundamentals/sandboxes/live-setup-sandbox.md).
* Su juego inicializó Gaming Runtime y, a continuación, llamó a [XblInitialize](https://docs.xbox.com/es/reference/live/xsapi-c/xbox_live_global_c/functions/xblinitialize.md) con una estructura [XblInitArgs](https://docs.xbox.com/es/reference/live/xsapi-c/xbox_live_global_c/structs/xblinitargs.md) cuyo miembro `scid` contiene su identificador de configuración de servicio (SCID). El SCID distingue mayúsculas de minúsculas. Para obtener más información, consulte [Cómo usar las API de servicios de XBOX](https://docs.xbox.com/es/services/xbox-services/fundamentals/xbox-services-api/live-gs-xbl-apis.md).
* Inició la sesión de un usuario y creó un `XblContextHandle` para ese usuario llamando a [XblContextCreateHandle](https://docs.xbox.com/es/reference/live/xsapi-c/xbox_live_context_c/functions/xblcontextcreatehandle.md).

Para restablecer los logros de una cuenta de prueba entre ejecuciones de prueba, use la [herramienta de restablecimiento de datos de jugador (XblPlayerDataReset.exe)](https://docs.xbox.com/es/tools/tools-services/live-player-data-reset.md). Para restablecer un jugador por XUID, la cuenta de desarrollador con la que inicia sesión mediante XblDevAccount.exe necesita el permiso "Tools Access" en el nivel de producto.

## Desbloqueo de un logro

Después de configurar los logros mediante Partner Center y publicarlos en su sandbox de desarrollo, su título puede desbloquearlos llamando a la API [XblAchievementsUpdateAchievementAsync](https://docs.xbox.com/es/reference/live/xsapi-c/achievements_c/functions/xblachievementsupdateachievementasync.md).
Para obtener más información, consulte el código de ejemplo de la sección siguiente.

Para desbloquear un logro, establezca `percentComplete` en 100.
Si el usuario está en línea, la solicitud se envía inmediatamente al servicio de logros de los servicios XBOX y desencadena las siguientes experiencias de usuario.

* El usuario recibe una notificación de logro desbloqueado.
* El logro especificado aparece como desbloqueado en la lista de logros del usuario para el título.
* El logro desbloqueado se agrega a la fuente de actividades del usuario.

> [!NOTE]
>
> La experiencia de usuario es visualmente la misma para los logros que usan logros basados en eventos o logros administrados por el título.

Si el usuario está sin conexión, la solicitud de desbloqueo se pone en cola localmente en el dispositivo del usuario.
Cuando se restablece la conectividad de red, la solicitud se envía automáticamente al servicio de logros (no se requiere ninguna acción del juego para desencadenar esto) y se producen las experiencias de usuario anteriores tal como se describe.

## Actualización del progreso de finalización de un logro

Para actualizar el progreso de un usuario hacia el desbloqueo de un logro, llame a [XblAchievementsUpdateAchievementAsync](https://docs.xbox.com/es/reference/live/xsapi-c/achievements_c/functions/xblachievementsupdateachievementasync.md). Establezca el argumento `percentComplete` en un número entero entre 1 y 100.
Para obtener más información, consulte el siguiente código de ejemplo.

El progreso de un logro solo puede aumentar.
Si `percentComplete` se establece en un número menor que el último valor de `percentComplete` del logro, la actualización se ignora.
Por ejemplo, si el `percentComplete` del logro se había establecido previamente en 75, el envío de una actualización con un valor de 25 se ignora. El logro se sigue mostrando como completado al 75 por ciento.

Si `percentComplete` se establece en 100, el logro se desbloquea.

Si `percentComplete` se establece en un número mayor que 100, la API se comporta como si hubiera establecido el número exactamente en 100.

### Actualización de logros para el título actual

Puede actualizar los logros del título actual llamando a [XblAchievementsUpdateAchievementAsync](https://docs.xbox.com/es/reference/live/xsapi-c/achievements_c/functions/xblachievementsupdateachievementasync.md), como se muestra a continuación.

**API de C plana**

```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 obtener más información, consulte lo siguiente:

* [XAsyncBlock](https://docs.xbox.com/es/reference/system/xasync/structs/xasyncblock.md)
* [XAsyncGetStatus](https://docs.xbox.com/es/reference/system/xasync/functions/xasyncgetstatus.md)
* [XblAchievementsUpdateAchievementAsync](https://docs.xbox.com/es/reference/live/xsapi-c/achievements_c/functions/xblachievementsupdateachievementasync.md)

### Actualización de logros para un título diferente

Puede actualizar los logros de otro `titleId` usando [XblAchievementsUpdateAchievementForTitleIdAsync](https://docs.xbox.com/es/reference/live/xsapi-c/achievements_c/functions/xblachievementsupdateachievementfortitleidasync.md), como se muestra a continuación.

**API de C plana**

```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 obtener más información, consulte lo siguiente:

* [XAsyncBlock](https://docs.xbox.com/es/reference/system/xasync/structs/xasyncblock.md)
* [XAsyncGetStatus](https://docs.xbox.com/es/reference/system/xasync/functions/xasyncgetstatus.md)
* [XblAchievementsUpdateAchievementForTitleIdAsync](https://docs.xbox.com/es/reference/live/xsapi-c/achievements_c/functions/xblachievementsupdateachievementfortitleidasync.md)

## Solución de problemas

Para agrupar un HRESULT de error en una categoría sobre la que se pueda actuar, llame a [XblGetErrorCondition](https://docs.xbox.com/es/reference/live/xsapi-c/errors_c/functions/xblgeterrorcondition.md).

No reintente usted mismo las actualizaciones con error. Si una actualización produce un error debido a un problema de red o de autenticación, a una limitación (HTTP 429), a un error del servidor (HTTP 5xx) o a un error sin clasificar, XSAPI la pone en cola como un evento sin conexión y la envía cuando el dispositivo vuelve a estar en línea. En ese caso, `XAsyncGetStatus` devuelve el resultado de poner en cola el evento, que normalmente es `S_OK`. Si reintenta la actualización, el servicio puede recibirla dos veces.

Los siguientes resultados pueden llegar a su juego:

| Resultado | Causa posible | Qué hacer |
| - | - | - |
| `HTTP_E_STATUS_NOT_MODIFIED` (`XblErrorCondition::Http304NotModified`) | El logro ya está desbloqueado o el nuevo valor de progreso no es mayor que el valor que ha registrado el servicio. | No es necesario realizar ninguna acción. |
| Otro estado HTTP 4xx, como 400, 403 o 404 | El servicio rechazó la solicitud, por ejemplo, porque el identificador del logro no está configurado para su título o sandbox. | Compruebe el identificador del logro y la configuración del título. Si reintenta la misma solicitud, se producirá el mismo error. |
| `E_INVALIDARG` | El contexto, el identificador del logro o el bloque asincrónico es NULL. | Compruebe los argumentos. Pase un valor de `percentComplete` entre 1 y 100. |
| `E_XBL_NOT_INITIALIZED` | XSAPI no está inicializado. | Llame a `XblInitialize` antes de actualizar los logros. |

[Volver al principio de este tema.](#top)


## Related topics

- [Ejemplos de logros administrados por el título](https://docs.xbox.com/es/services/xbox-services/player-data/achievements/title-managed/how-to/index.md)
- [Código de ejemplo de logros administrados por el título (contenido)](https://docs.xbox.com/es/services/xbox-services/player-data/achievements/title-managed/how-to/live-achievements-howto-nav.md)
- [Estadísticas y logros](https://docs.xbox.com/es/build/steam-porting-guide/features/stats-and-achievements.md)
- [Desarrollo con Unreal para PC: introducción (versiones anteriores)](https://docs.xbox.com/es/build/gdk-and-engines/unreal/unreal-legacy.md)
- [Logros administrados por el título](https://docs.xbox.com/es/services/xbox-services/player-data/achievements/title-managed/index.md)