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

# Vue d'ensemble de l'API XBOX Achievements Manager

> Comment l'API XBOX Achievements Manager de XSAPI simplifie l'interrogation, les abonnements RTA et la mise à jour de l'état des succès XBOX Live d'un utilisateur.

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](/fr/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerdowork) doit être appelée à chaque trame.

<Note>Sur Windows, il ne peut y avoir qu'un seul utilisateur local</Note>

## 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](https://aka.ms/xboxliveuwpdocs).
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](/fr/reference/live/xsapi-c/achievements_manager_c/functions/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](/fr/reference/live/xsapi-c/achievements_manager_c/functions/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](/fr/reference/live/xsapi-c/achievements_manager_c/functions/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**

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

**Référence**

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

#### É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](/fr/reference/live/xsapi-c/achievements_manager_c/enums/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](/fr/reference/live/xsapi-c/achievements_manager_c/enums/xblachievementsmanagereventtype)::AchievementProgressUpdated

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

* API C : [XblAchievementsManagerEventType](/fr/reference/live/xsapi-c/achievements_manager_c/enums/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](/fr/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerdowork).

**events** est une liste de [XblAchievementsManagerEvent](/fr/reference/live/xsapi-c/achievements_manager_c/structs/xblachievementsmanagerevent), et chaque [XblAchievementsManagerEvent](/fr/reference/live/xsapi-c/achievements_manager_c/structs/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](/fr/reference/live/xsapi-c/achievements_manager_c/structs/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**

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

**Référence**

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

#### É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](/fr/reference/live/xsapi-c/achievements_manager_c/enums/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](/fr/reference/live/xsapi-c/achievements_manager_c/functions/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**

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

**Référence**

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

#### É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](/fr/reference/live/xsapi-c/achievements_manager_c/enums/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**

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

**Référence**

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

#### É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](/fr/reference/live/xsapi-c/achievements_manager_c/enums/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**

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

**Référence**

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

#### É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](/fr/reference/live/xsapi-c/achievements_manager_c/enums/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**

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

**Référence**

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

#### É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](/fr/reference/live/xsapi-c/achievements_manager_c/enums/xblachievementsmanagereventtype)::LocalUserInitialStateSynced

### Mise à jour d'un succès pour un utilisateur

Met à jour la progression d'un succès pour un utilisateur.

**API C**

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

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

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

**Référence**

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

#### É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](/fr/reference/live/xsapi-c/achievements_manager_c/enums/xblachievementsmanagereventtype)::LocalUserInitialStateSynced

#### Informations supplémentaires

Seuls les succès gérés par le titre peuvent être mis à jour à l'aide de [XblAchievementsManagerUpdateAchievement](/fr/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerupdateachievement).
Consultez [Écriture d'un événement pour alimenter un succès basé sur les événements](/fr/services/xbox-services/player-data/achievements/event-based/how-to/live-writing-event-based-achievement) 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**

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

**Référence**

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


## Related topics

- [Achievements Manager](/fr/services/xbox-services/player-data/achievements/achievements-manager/live-achievements-manager-nav.md)
- [Gestionnaire de succès](/fr/services/xbox-services/player-data/achievements/achievements-manager/index.md)
- [Vue d'ensemble de l'API Multiplayer Manager](/fr/services/xbox-services/multiplayer/mpm/concepts/live-multiplayer-manager-api-overview.md)
- [Vue d'ensemble de Multiplayer Manager](/fr/services/xbox-services/multiplayer/mpm/live-multiplayer-manager-overview.md)
- [Vue d'ensemble de Social Manager](/fr/services/xbox-services/community/social-manager/live-social-manager-overview.md)