Información general sobre la API XBOX Achievements Manager

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 en cada fotograma.

En Windows solo puede haber un usuario local

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

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

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.

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

// 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

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::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::AchievementProgressUpdated

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

API de C: 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. events es una lista de XblAchievementsManagerEvent, y cada 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.

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

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

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::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 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

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

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::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

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

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::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

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

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::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

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

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::LocalUserInitialStateSynced

Actualización de un logro de un usuario

Actualiza el progreso de un logro de un usuario. C API

HRESULT hr = XblAchievementsManagerAddLocalUser(userHandle, nullptr);

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

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

Referencia

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::LocalUserInitialStateSynced

Detalles adicionales

Solo los logros administrados por el título se pueden actualizar mediante XblAchievementsManagerUpdateAchievement. Consulte Escritura de un evento para activar un logro basado en eventos 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

HRESULT hr = XblAchievementsManagerRemoveLocalUser(userHandle);

Referencia

XblAchievementsManagerRemoveLocalUser

XBOX Services

PlayFab

Información general sobre la API XBOX Achievements Manager

Características

Conceptos básicos

Información general sobre la API

Adición de usuarios locales al Achievements Manager

Obtención del estado de los logros de un usuario

Uso

Uso de eventos de Achievements Manager

Eventos devueltos

Detalles adicionales

Registro de un usuario cuyos logros se van a seguir

Eventos devueltos

Detalles adicionales

Recuperación de un único logro de un usuario

Eventos devueltos

Recuperación de todos los logros de un usuario

Eventos devueltos

Recuperación de un subconjunto de logros de un usuario

Eventos devueltos

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

Eventos devueltos

Actualización de un logro de un usuario

Eventos devueltos

Detalles adicionales

Limpieza del Achievements Manager

​Características

​Conceptos básicos

​Información general sobre la API

​Adición de usuarios locales al Achievements Manager

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

​Uso

​Uso de eventos de Achievements Manager

​Eventos devueltos

​Detalles adicionales

​Registro de un usuario cuyos logros se van a seguir

​Eventos devueltos

​Detalles adicionales

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

​Eventos devueltos

​Recuperación de todos los logros de un usuario

​Eventos devueltos

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

​Eventos devueltos

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

​Eventos devueltos

​Actualización de un logro de un usuario

​Eventos devueltos

​Detalles adicionales

​Limpieza del Achievements Manager

Características

Conceptos básicos

Información general sobre la API

Adición de usuarios locales al Achievements Manager

Obtención del estado de los logros de un usuario

Uso

Uso de eventos de Achievements Manager

Eventos devueltos

Detalles adicionales

Registro de un usuario cuyos logros se van a seguir

Eventos devueltos

Detalles adicionales

Recuperación de un único logro de un usuario

Eventos devueltos

Recuperación de todos los logros de un usuario

Eventos devueltos

Recuperación de un subconjunto de logros de un usuario

Eventos devueltos

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

Eventos devueltos

Actualización de un logro de un usuario

Eventos devueltos

Detalles adicionales

Limpieza del Achievements Manager