Vue d'ensemble de l'API XBOX Achievements Manager - XBOX Game Development Documentation

L’API XBOX Achievements Manager simplifie le suivi et la mise à jour de l’état des succès d’un utilisateur XBOX Live. XBOX permet de suivre la progression et les accomplissements d’un utilisateur dans ses jeux en attribuant des succès à certains moments. Utiliser les API de succès de XBOX Services API (XSAPI) pour maintenir à jour les informations de succès de chaque utilisateur local peut être compliqué. Une mauvaise implémentation peut entraîner des problèmes de performances, des données obsolètes ou une limitation due à des appels aux services de succès XBOX plus fréquents que nécessaire. Social Manager résout ce problème en :

Créant une API simple à appeler.
Créant des informations à jour à l’aide du service d’activité en temps réel en arrière-plan.
Permettant aux développeurs d’appeler l’API Achievements Manager de manière synchrone sans charge supplémentaire sur le service.

Achievements Manager masque la complexité de la gestion de plusieurs abonnements RTA, de l’actualisation des données des utilisateurs et de la réduction du nombre d’appels au service de succès, et permet aux développeurs d’obtenir facilement les données de succès à jour.

Fonctionnalités

Achievements Manager offre les fonctionnalités suivantes :

API de succès simplifiée
État et progression des succès à jour pour chaque utilisateur
Réduction du nombre d’appels aux services XBOX
- Cela se traduit directement par une réduction de la latence globale d’acquisition des données
Sécurité des threads
Maintien efficace des données à jour

Concepts fondamentaux

Succès : un succès comprend du gamerscore et d’autres récompenses, comme des illustrations numériques, de nouvelles cartes, des personnages et des bonus de statistiques, ainsi que la progression actuelle vers son accomplissement. Pour maintenir à jour l’état des succès d’un utilisateur, la fonction XblAchievementsManagerDoWork doit être appelée à chaque trame.

Sur Windows, il ne peut y avoir qu’un seul utilisateur local

Vue d’ensemble de l’API

Vous utiliserez le plus souvent les API clés suivantes. Vous trouverez une description complète des API Achievements Manager dans la référence de l’API XBOX Live. Vous pouvez également trouver les API dans la documentation des éléments préfixés par XblAchievementsManager.

Ajout d’utilisateurs locaux à Achievements Manager

Fonction de l’API C : XblAchievementsManagerAddLocalUser

L’ajout d’un utilisateur local à Achievements Manager entraîne la récupération auprès du service de l’état de tous les succès de cet utilisateur pour le titre actuel, ainsi que leur enregistrement local. Achievements Manager maintient à jour chacun des succès de cet utilisateur pour le titre actuel.

Obtention de l’état des succès d’un utilisateur

Fonction de l’API C : XblAchievementsManagerGetAchievements

L’appel de cette fonction renvoie un handle vers le ou les succès correspondant aux critères spécifiés. Les succès pointés par le handle sont des copies thread-safe des succès correspondants. Les données pointées par le handle existent jusqu’à la fermeture du handle, mais peuvent devenir obsolètes si le titre conserve le handle au-delà de l’appel suivant à XblAchievementsManagerDoWork.

Utilisation

Utilisation des événements d’Achievements Manager

Achievements Manager vous indique ce qui s’est passé, sous forme d’événements. Vous pouvez utiliser ces événements pour mettre à jour votre interface utilisateur ou exécuter une autre logique. API C

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

Référence

Événements renvoyés

Local User Initial State Synced : se déclenche lorsque Achievements Manager a fini de récupérer l’état actuel de tous les succès du titre actuel pour l’utilisateur.

API C : XblAchievementsManagerEventType::LocalUserInitialStateSynced

Achievement Progress Updated : se déclenche lorsque la progression d’un utilisateur pour un succès du titre actuel a été mise à jour.

API C : XblAchievementsManagerEventType::AchievementProgressUpdated

Achievement Unlocked : se déclenche lorsqu’un utilisateur remplit toutes les conditions d’un succès du titre actuel.

API C : XblAchievementsManagerEventType::AchievementUnlocked

Informations supplémentaires

Au lieu de récupérer fréquemment l’état des succès auprès du service pendant la boucle de jeu, Achievements Manager récupère l’état de tous les succès d’un utilisateur lorsque celui-ci est inscrit auprès d’Achievements Manager. Achievements Manager reçoit ensuite du service des événements détaillant les mises à jour des succès de l’utilisateur, qui sont ensuite transmis au titre sous forme d’events renvoyés par la fonction * XblAchievementsManagerDoWork. events est une liste de XblAchievementsManagerEvent, et chaque XblAchievementsManagerEvent contient une modification apportée à un succès au cours de la dernière trame. Vous trouverez plus d’informations dans la documentation de l’API XblAchievementsManagerEvent.

Inscrire un utilisateur dont les succès doivent être suivis

Dans ce scénario, vous souhaitez inscrire un utilisateur auprès d’Achievements Manager pour commencer à suivre les mises à jour de ses succès et mettre en cache localement l’état de tous ses succès. API C

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

Référence

Événements renvoyés

Local User Initial State Synced : se déclenche lorsque Achievements Manager a fini de récupérer l’état actuel de tous les succès du titre actuel pour l’utilisateur.

API C : XblAchievementsManagerEventType::LocalUserInitialStateSynced

Informations supplémentaires

L’exemple ci-dessus montre comment initialiser Achievements Manager pour un utilisateur et le maintenir à jour. Dans la boucle de jeu, la fonction XblAchievementsManagerDoWork traite et applique toutes les mises à jour apportées aux succès des utilisateurs.

Récupération d’un seul succès d’un utilisateur

Dans ce scénario, vous souhaitez obtenir l’état d’un seul succès d’un utilisateur. API C

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); 

Référence

Événements renvoyés

Local User Initial State Synced : se déclenche lorsque Achievements Manager a fini de récupérer l’état actuel de tous les succès du titre actuel pour l’utilisateur.

API C : XblAchievementsManagerEventType::LocalUserInitialStateSynced

Récupération de tous les succès d’un utilisateur

Dans ce scénario, vous souhaitez obtenir l’état de tous les succès d’un utilisateur. API C

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); 

Référence

Événements renvoyés

Local User Initial State Synced : se déclenche lorsque Achievements Manager a fini de récupérer l’état actuel de tous les succès du titre actuel pour l’utilisateur.

API C : XblAchievementsManagerEventType::LocalUserInitialStateSynced

Récupération d’un sous-ensemble de succès d’un utilisateur

Dans ce scénario, vous souhaitez obtenir l’état d’un sous-ensemble de succès d’un utilisateur. API C

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); 

Référence

Événements renvoyés

Local User Initial State Synced : se déclenche lorsque Achievements Manager a fini de récupérer l’état actuel de tous les succès du titre actuel pour l’utilisateur.

API C : XblAchievementsManagerEventType::LocalUserInitialStateSynced

Récupération d’un sous-ensemble de succès dans un état spécifique pour un utilisateur

Dans ce scénario, vous souhaitez obtenir l’état d’un sous-ensemble de succès se trouvant dans un état de progression spécifique pour un utilisateur. API C

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); 

Référence

Événements renvoyés

Local User Initial State Synced : se déclenche lorsque Achievements Manager a fini de récupérer l’état actuel de tous les succès du titre actuel pour l’utilisateur.

API C : XblAchievementsManagerEventType::LocalUserInitialStateSynced

Mise à jour d’un succès pour un utilisateur

Met à jour la progression d’un succès pour un utilisateur. API C

HRESULT hr = XblAchievementsManagerAddLocalUser(userHandle, nullptr);

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

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

Référence

Événements renvoyés

Local User Initial State Synced : se déclenche lorsque Achievements Manager a fini de récupérer l’état actuel de tous les succès du titre actuel pour l’utilisateur.

API C : XblAchievementsManagerEventType::LocalUserInitialStateSynced

Informations supplémentaires

Seuls les succès gérés par le titre peuvent être mis à jour à l’aide de XblAchievementsManagerUpdateAchievement. Consultez Écriture d’un événement pour alimenter un succès basé sur les événements pour la mise à jour des succès basés sur les événements.

Nettoyage d’Achievements Manager

La suppression d’un utilisateur d’Achievements Manager supprime les succès mis en cache de cet utilisateur dans Achievements Manager. Plus aucun événement ne devrait être reçu pour l’utilisateur supprimé. API C

HRESULT hr = XblAchievementsManagerRemoveLocalUser(userHandle);

Référence

XblAchievementsManagerRemoveLocalUser

​Fonctionnalités

​Concepts fondamentaux

​Vue d’ensemble de l’API

​Ajout d’utilisateurs locaux à Achievements Manager

​Obtention de l’état des succès d’un utilisateur

​Utilisation

​Utilisation des événements d’Achievements Manager

​Événements renvoyés

​Informations supplémentaires

​Inscrire un utilisateur dont les succès doivent être suivis

​Événements renvoyés

​Informations supplémentaires

​Récupération d’un seul succès d’un utilisateur

​Événements renvoyés

​Récupération de tous les succès d’un utilisateur

​Événements renvoyés

​Récupération d’un sous-ensemble de succès d’un utilisateur

​Événements renvoyés

​Récupération d’un sous-ensemble de succès dans un état spécifique pour un utilisateur

​Événements renvoyés

​Mise à jour d’un succès pour un utilisateur

​Événements renvoyés

​Informations supplémentaires

​Nettoyage d’Achievements Manager

Fonctionnalités

Concepts fondamentaux

Vue d’ensemble de l’API

Ajout d’utilisateurs locaux à Achievements Manager

Obtention de l’état des succès d’un utilisateur

Utilisation

Utilisation des événements d’Achievements Manager

Événements renvoyés

Informations supplémentaires

Inscrire un utilisateur dont les succès doivent être suivis

Événements renvoyés

Informations supplémentaires

Récupération d’un seul succès d’un utilisateur

Événements renvoyés

Récupération de tous les succès d’un utilisateur

Événements renvoyés

Récupération d’un sous-ensemble de succès d’un utilisateur

Événements renvoyés

Récupération d’un sous-ensemble de succès dans un état spécifique pour un utilisateur

Événements renvoyés

Mise à jour d’un succès pour un utilisateur

Événements renvoyés

Informations supplémentaires

Nettoyage d’Achievements Manager