Actualización de logros administrados por el título

En este tema se tratan los siguientes puntos:

Antes de empezar
Desbloqueo de un logro
Actualización del progreso de finalización de un logro
Solución de problemas

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.
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.
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.
Su juego inicializó Gaming Runtime y, a continuación, llamó a XblInitialize con una estructura XblInitArgs 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.
Inició la sesión de un usuario y creó un XblContextHandle para ese usuario llamando a XblContextCreateHandle.

Para restablecer los logros de una cuenta de prueba entre ejecuciones de prueba, use la herramienta de restablecimiento de datos de jugador (XblPlayerDataReset.exe). 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. 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.

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. 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, como se muestra a continuación. API de C plana

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:

Actualización de logros para un título diferente

Puede actualizar los logros de otro titleId usando XblAchievementsUpdateAchievementForTitleIdAsync, como se muestra a continuación. API de C plana

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:

Solución de problemas

Para agrupar un HRESULT de error en una categoría sobre la que se pueda actuar, llame a XblGetErrorCondition. 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.

XBOX Services

PlayFab

Antes de empezar

Desbloqueo de un logro

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

Actualización de logros para el título actual

Actualización de logros para un título diferente

Solución de problemas

​Antes de empezar

​Desbloqueo de un logro

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

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

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

​Solución de problemas

Antes de empezar

Desbloqueo de un logro

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

Actualización de logros para el título actual

Actualización de logros para un título diferente

Solución de problemas