> ## 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.

# Información general sobre la API XBOX Achievements Manager

> Cómo la API XBOX Achievements Manager de XSAPI simplifica el sondeo, las suscripciones RTA y el estado actualizado de los logros de un usuario de XBOX Live.

La API XBOX Achievements Manager simplifica el seguimiento y la actualización del estado de los logros de un usuario de XBOX Live.

XBOX proporciona una manera de hacer un seguimiento del progreso y las metas de un usuario en sus juegos concediendo logros en ciertos momentos.
Usar las API de logros de la API de servicios de XBOX (XSAPI) para mantener actualizada la información de logros de cada usuario local puede ser complicado.
No hacerlo correctamente puede provocar problemas de rendimiento, datos obsoletos o una limitación por llamar a los servicios de logros de XBOX con más frecuencia de la necesaria.

El Social Manager resuelve este problema:

* Creando una API sencilla a la que llamar.
* Creando información actualizada mediante el servicio de actividad en tiempo real de forma transparente.
* Los desarrolladores pueden llamar a la API Achievements Manager de forma sincrónica sin ninguna sobrecarga adicional para el servicio.

El Achievements Manager oculta la complejidad de tratar con varias suscripciones RTA, actualizar los datos de los usuarios y reducir el número de llamadas al servicio de logros, y permite a los desarrolladores obtener fácilmente los datos de logros actualizados.

## Características

El Achievements Manager proporciona las características siguientes:

* API de logros simplificada
* Estado y progreso de los logros actualizados para cada usuario
* Reducción del número de llamadas a los servicios de XBOX
  * Esto se correlaciona directamente con la reducción general de la latencia en la adquisición de datos
* Seguridad para subprocesos
* Mantenimiento eficiente de los datos actualizados

## Conceptos básicos

**Logros**: un logro incluye el gamerscore y otras recompensas, como arte digital, mapas nuevos, personajes y mejoras de estadísticas, así como el progreso actual hacia su finalización.

Para mantener actualizado el estado de los logros de un usuario, se debe llamar a la función [XblAchievementsManagerDoWork](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerdowork) en cada fotograma.

<Note>En Windows solo puede haber un usuario local</Note>

## Información general sobre la API

Usará con más frecuencia las siguientes API clave.

Puede encontrar una descripción completa de las API de Achievements Manager en la [referencia de API de XBOX Live](https://aka.ms/xboxliveuwpdocs).
También puede encontrar las API en la documentación con el prefijo **XblAchievementsManager**.

### Adición de usuarios locales al Achievements Manager

* Función de la API de C: [XblAchievementsManagerAddLocalUser](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanageraddlocaluser)

Agregar un usuario local al Achievements Manager hace que el estado de todos los logros de ese usuario para el título actual se obtenga del servicio y se guarde localmente.

El Achievements Manager mantendrá actualizados todos los logros de ese usuario para el título actual.

### Obtención del estado de los logros de un usuario

* Función de la API de C: [XblAchievementsManagerGetAchievements](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagergetachievements)

La llamada a esta función devuelve un identificador a los logros que coinciden con los criterios especificados.

Los logros a los que apunta el identificador son copias seguras para subprocesos de los logros coincidentes.
Los datos a los que apunta el identificador existirán hasta que se cierre el identificador, pero pueden quedar obsoletos si el título mantiene el identificador después de la siguiente llamada a [XblAchievementsManagerDoWork](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerdowork).

## Uso

### Uso de eventos de Achievements Manager

El Achievements Manager le indica lo que ha ocurrido en forma de eventos.
Puede usar esos eventos para actualizar la interfaz de usuario o ejecutar otra lógica.

**C API**

```cpp theme={null}
// some update loop in the game
while(true) 
{ 
    size_t eventsCount{}; 
    const XblAchievementsManagerEvent* events{}; 
    HRESULT hr = XblAchievementsManagerDoWork(&events, &eventsCount); 
    if (FAILED(hr))
    {
        // handle the error
    }

    for (uint32_t i = 0; i < eventsCount; ++i) 
    { 
        // act on the event
        switch (events[i].eventType) 
        { 
        case XblAchievementsManagerEventType::LocalUserInitialStateSynced: 
            // ...
            break; 
        case XblAchievementsManagerEventType::AchievementProgressUpdated: 
            // ...
            break; 
        case XblAchievementsManagerEventType::AchievementUnlocked: 
            // ...
            break; 
        default: 
            break; 
        } 
    } 
} 
```

**Referencia**

* [XblAchievementsManagerDoWork](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerdowork)
* [XblAchievementsManagerEvent](/reference/live/xsapi-c/achievements_manager_c/structs/xblachievementsmanagerevent)

#### Eventos devueltos

**Local User Initial State Synced**: se desencadena cuando el administrador de logros ha completado la obtención del estado actual de todos los logros del título actual para el usuario.

* API de C: [XblAchievementsManagerEventType](/reference/live/xsapi-c/achievements_manager_c/enums/xblachievementsmanagereventtype)::LocalUserInitialStateSynced

**Achievement Progress Updated**: se desencadena cuando se ha actualizado el progreso de un usuario en un logro del título actual.

* API de C: [XblAchievementsManagerEventType](/reference/live/xsapi-c/achievements_manager_c/enums/xblachievementsmanagereventtype)::AchievementProgressUpdated

**Achievement Unlocked**: se desencadena cuando un usuario completa todos los requisitos de un logro del título actual.

* API de C: [XblAchievementsManagerEventType](/reference/live/xsapi-c/achievements_manager_c/enums/xblachievementsmanagereventtype)::AchievementUnlocked

#### Detalles adicionales

En lugar de obtener el estado de los logros del servicio con frecuencia durante el bucle del juego, el Achievements Manager obtiene el estado de todos los logros de un usuario cuando este se registra en el Achievements Manager.
Después, el Achievements Manager recibe eventos del servicio que detallan las actualizaciones de los logros de un usuario, que luego se reenvían al título como **events** devueltos por la función \* [XblAchievementsManagerDoWork](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerdowork).

**events** es una lista de [XblAchievementsManagerEvent](/reference/live/xsapi-c/achievements_manager_c/structs/xblachievementsmanagerevent), y cada [XblAchievementsManagerEvent](/reference/live/xsapi-c/achievements_manager_c/structs/xblachievementsmanagerevent) contiene un cambio en un logro que se produjo durante el último fotograma.

Puede encontrar más información en la documentación de la API [XblAchievementsManagerEvent](/reference/live/xsapi-c/achievements_manager_c/structs/xblachievementsmanagerevent).

### Registro de un usuario cuyos logros se van a seguir

En este escenario, quiere registrar un usuario en el administrador de logros para empezar a hacer un seguimiento de las actualizaciones de los logros de ese usuario y almacenar en caché localmente el estado de todos los logros de ese usuario.

**C API**

```cpp theme={null}
HRESULT hr = XblAchievementsManagerAddLocalUser(userHandle, nullptr);

if (!SUCCEEDED(hr))
{
    return;
}

// some update loop in the game 
while(true)
{
    const XblAchievementsManagerEvent* events{ nullptr };
    size_t eventCount{ 0 };
    HRESULT hr = XblAchievementsManagerDoWork(&events, &eventCount);
    if (SUCCEEDED(hr))
    {
        return;   
    }
    for (size_t i = 0; i < eventCount; i++)
    {
        // Act on the event
    }
}
```

**Referencia**

* [XblAchievementsManagerAddLocalUser](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanageraddlocaluser)
* [XblAchievementsManagerDoWork](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerdowork)
* [XblAchievementsManagerEvent](/reference/live/xsapi-c/achievements_manager_c/structs/xblachievementsmanagerevent)

#### Eventos devueltos

**Local User Initial State Synced**: se desencadena cuando el administrador de logros ha completado la obtención del estado actual de todos los logros del título actual para el usuario.

* API de C: [XblAchievementsManagerEventType](/reference/live/xsapi-c/achievements_manager_c/enums/xblachievementsmanagereventtype)::LocalUserInitialStateSynced

#### Detalles adicionales

El ejemplo anterior muestra cómo inicializar el Achievements Manager para un usuario y mantenerlo actualizado.

En el bucle del juego, la función [XblAchievementsManagerDoWork](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerdowork) procesa y aplica cualquier actualización realizada en los logros de los usuarios.

### Recuperación de un único logro de un usuario

En este escenario quiere obtener el estado de un único logro de un usuario.

**C API**

```cpp theme={null}
HRESULT hr = XblAchievementsManagerAddLocalUser(userHandle, nullptr);

if (!XblAchievementsManagerIsUserInitialized(xboxUserId))
{
    return;
}

const XblAchievement* achievement = nullptr; 
uint64_t size; 
XblAchievementsManagerResultHandle resultHandle; 

HRESULT hr = XblAchievementsManagerGetAchievement( 
    xboxUserId, 
    achievementId, 
    &resultHandle 
); 

if(FAILED(hr)) 
{ 
    return; 
} 

hr = XblAchievementsManagerResultGetAchievements( 
    resultHandle, 
    &achievement, 
    &size 
); 
if(FAILED(hr)) 
{ 
    return; 
} 

// make use of achievement struct

XblAchievementsManagerResultCloseHandle(resultHandle); 
```

**Referencia**

* [XblAchievement](/reference/live/xsapi-c/achievements_c/structs/xblachievement)
* [XblAchievementsManagerAddLocalUser](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanageraddlocaluser)
* [XblAchievementsManagerIsUserInitialized](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerisuserinitialized)
* [XblAchievementsManagerGetAchievement](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagergetachievement)
* [XblAchievementsManagerResultGetAchievements](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerresultgetachievements)
* [XblAchievementsManagerResultCloseHandle](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerresultclosehandle)

#### Eventos devueltos

**Local User Initial State Synced**: se desencadena cuando el administrador de logros ha completado la obtención del estado actual de todos los logros del título actual para el usuario.

* API de C: [XblAchievementsManagerEventType](/reference/live/xsapi-c/achievements_manager_c/enums/xblachievementsmanagereventtype)::LocalUserInitialStateSynced

### Recuperación de todos los logros de un usuario

En este escenario quiere obtener el estado de todos los logros de un usuario.

**C API**

```cpp theme={null}
HRESULT hr = XblAchievementsManagerAddLocalUser(userHandle, nullptr);

if (!XblAchievementsManagerIsUserInitialized(xboxUserId))
{
    return;
}

XblAchievementsManagerResultHandle resultHandle; 
const XblAchievement* achievements; 
uint64_t achievementsCount; 

hr = XblAchievementsManagerGetAchievements( 
    xboxUserId, 
    XblAchievementOrderBy::DefaultOrder, 
    XblAchievementsManagerSortOrder::Unsorted, 
    &resultHandle 
); 

if(FAILED(hr)) 
{ 
    return; 
} 

hr = XblAchievementsManagerResultGetAchievements( 
    resultHandle, 
    &achievements, 
    &achievementsCount 
); 

if(FAILED(hr)) 
{ 
    return; 
} 
 
for (uint32_t i = 0; i < achievementsCount; ++i) 
{ 
    // ... 
} 
XblAchievementsManagerResultCloseHandle(resultHandle); 
```

**Referencia**

* [XblAchievement](/reference/live/xsapi-c/achievements_c/structs/xblachievement)
* [XblAchievementOrderBy](/reference/live/xsapi-c/achievements_c/enums/xblachievementorderby)
* [XblAchievementsManagerSortOrder](/reference/live/xsapi-c/achievements_manager_c/enums/xblachievementsmanagersortorder)
* [XblAchievementsManagerAddLocalUser](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanageraddlocaluser)
* [XblAchievementsManagerIsUserInitialized](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerisuserinitialized)
* [XblAchievementsManagerGetAchievements](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagergetachievements)
* [XblAchievementsManagerResultGetAchievements](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerresultgetachievements)
* [XblAchievementsManagerResultCloseHandle](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerresultclosehandle)

#### Eventos devueltos

**Local User Initial State Synced**: se desencadena cuando el administrador de logros ha completado la obtención del estado actual de todos los logros del título actual para el usuario.

* API de C: [XblAchievementsManagerEventType](/reference/live/xsapi-c/achievements_manager_c/enums/xblachievementsmanagereventtype)::LocalUserInitialStateSynced

### Recuperación de un subconjunto de logros de un usuario

En este escenario quiere obtener el estado de un subconjunto de logros de un usuario.

**C API**

```cpp theme={null}
HRESULT hr = XblAchievementsManagerAddLocalUser(userHandle, nullptr);

if (!XblAchievementsManagerIsUserInitialized(xboxUserId))
{
    return;
}

XblAchievementsManagerResultHandle resultHandle; 
const XblAchievement* achievements; 
uint64_t achievementsCount; 

hr = XblAchievementsManagerGetAchievements( 
    xboxUserId, 
    XblAchievementOrderBy::UnlockTime, 
    XblAchievementsManagerSortOrder::Descending, 
    &resultHandle 
); 

if(FAILED(hr)) 
{ 
    return; 
} 

hr = XblAchievementsManagerResultGetAchievements( 
    resultHandle, 
    &achievements, 
    &achievementsCount 
); 

if(FAILED(hr)) 
{ 
    return; 
} 
 
for (uint32_t i = 0; i < achievementsCount; ++i) 
{ 
    // ... 
} 
XblAchievementsManagerResultCloseHandle(resultHandle); 
```

**Referencia**

* [XblAchievement](/reference/live/xsapi-c/achievements_c/structs/xblachievement)
* [XblAchievementOrderBy](/reference/live/xsapi-c/achievements_c/enums/xblachievementorderby)
* [XblAchievementsManagerSortOrder](/reference/live/xsapi-c/achievements_manager_c/enums/xblachievementsmanagersortorder)
* [XblAchievementsManagerAddLocalUser](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanageraddlocaluser)
* [XblAchievementsManagerIsUserInitialized](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerisuserinitialized)
* [XblAchievementsManagerGetAchievements](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagergetachievements)
* [XblAchievementsManagerResultGetAchievements](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerresultgetachievements)
* [XblAchievementsManagerResultCloseHandle](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerresultclosehandle)

#### Eventos devueltos

**Local User Initial State Synced**: se desencadena cuando el administrador de logros ha completado la obtención del estado actual de todos los logros del título actual para el usuario.

* API de C: [XblAchievementsManagerEventType](/reference/live/xsapi-c/achievements_manager_c/enums/xblachievementsmanagereventtype)::LocalUserInitialStateSynced

### Recuperación de un subconjunto de logros en un estado específico para un usuario

En este escenario quiere obtener el estado de un subconjunto de logros en un estado de progreso específico para un usuario.

**C API**

```cpp theme={null}
HRESULT hr = XblAchievementsManagerAddLocalUser(userHandle, nullptr);

if (!XblAchievementsManagerIsUserInitialized(xboxUserId))
{
    return;
}

XblAchievementsManagerResultHandle resultHandle; 
const XblAchievement* achievements; 
uint64_t achievementsCount; 

hr = XblAchievementsManagerGetAchievementsByState( 
    xboxUserId, 
    XblAchievementOrderBy::DefaultOrder, 
    XblAchievementsManagerSortOrder::Unsorted, 
    XblAchievementProgressState::NotStarted, 
    &resultHandle 
); 

if(FAILED(hr)) 
{ 
    return; 
} 

hr = XblAchievementsManagerResultGetAchievements( 
    resultHandle, 
    &achievements, 
    &achievementsCount 
); 

if(FAILED(hr)) 
{ 
    return; 
} 
 
for (uint32_t i = 0; i < achievementsCount; ++i) 
{ 
    // ... 
} 
XblAchievementsManagerResultCloseHandle(resultHandle); 
```

**Referencia**

* [XblAchievement](/reference/live/xsapi-c/achievements_c/structs/xblachievement)
* [XblAchievementOrderBy](/reference/live/xsapi-c/achievements_c/enums/xblachievementorderby)
* [XblAchievementProgressState](/reference/live/xsapi-c/achievements_c/enums/xblachievementprogressstate)
* [XblAchievementsManagerSortOrder](/reference/live/xsapi-c/achievements_manager_c/enums/xblachievementsmanagersortorder)
* [XblAchievementsManagerAddLocalUser](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanageraddlocaluser)
* [XblAchievementsManagerIsUserInitialized](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerisuserinitialized)
* [XblAchievementsManagerGetAchievementsByState](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagergetachievementsbystate)
* [XblAchievementsManagerResultGetAchievements](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerresultgetachievements)
* [XblAchievementsManagerResultCloseHandle](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerresultclosehandle)

#### Eventos devueltos

**Local User Initial State Synced**: se desencadena cuando el administrador de logros ha completado la obtención del estado actual de todos los logros del título actual para el usuario.

* API de C: [XblAchievementsManagerEventType](/reference/live/xsapi-c/achievements_manager_c/enums/xblachievementsmanagereventtype)::LocalUserInitialStateSynced

### Actualización de un logro de un usuario

Actualiza el progreso de un logro de un usuario.

**C API**

```cpp theme={null}
HRESULT hr = XblAchievementsManagerAddLocalUser(userHandle, nullptr);

if (!XblAchievementsManagerIsUserInitialized(xboxUserId))
{
    return;
}

XblAchievementsManagerUpdateAchievement(xboxUserId, achievementId.c_str(), progress);
```

**Referencia**

* [XblAchievementsManagerAddLocalUser](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanageraddlocaluser)
* [XblAchievementsManagerIsUserInitialized](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerisuserinitialized)
* [XblAchievementsManagerUpdateAchievement](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerupdateachievement)

#### Eventos devueltos

**Local User Initial State Synced**: se desencadena cuando el administrador de logros ha completado la obtención del estado actual de todos los logros del título actual para el usuario.

* API de C: [XblAchievementsManagerEventType](/reference/live/xsapi-c/achievements_manager_c/enums/xblachievementsmanagereventtype)::LocalUserInitialStateSynced

#### Detalles adicionales

Solo los logros administrados por el título se pueden actualizar mediante [XblAchievementsManagerUpdateAchievement](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerupdateachievement).
Consulte [Escritura de un evento para activar un logro basado en eventos](/services/xbox-services/player-data/achievements/event-based/how-to/live-writing-event-based-achievement) para actualizar logros basados en eventos.

### Limpieza del Achievements Manager

Quitar un usuario del Achievements Manager elimina los logros almacenados en caché de ese usuario del Achievements Manager.
No se deberían recibir más eventos para el usuario quitado.

**C API**

```cpp theme={null}
HRESULT hr = XblAchievementsManagerRemoveLocalUser(userHandle);
```

**Referencia**

* [XblAchievementsManagerRemoveLocalUser](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerremovelocaluser)


## Related topics

- [Achievements Manager](/es/services/xbox-services/player-data/achievements/achievements-manager/live-achievements-manager-nav.md)
- [Administrador de logros](/es/services/xbox-services/player-data/achievements/achievements-manager/index.md)
- [Información general sobre la API de Multiplayer Manager](/es/services/xbox-services/multiplayer/mpm/concepts/live-multiplayer-manager-api-overview.md)
- [Información general sobre la API de servicios XBOX](/es/services/xbox-services/fundamentals/xbox-services-api/live-introduction-to-xbox-live-apis.md)
- [Información general sobre Multiplayer Manager](/es/services/xbox-services/multiplayer/mpm/live-multiplayer-manager-overview.md)