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

# XBOX 成就管理員 API 概觀

> XSAPI 中的 XBOX 成就管理員 API 如何簡化輪詢、RTA 訂閱，並為使用者的 XBOX Live 成就保持最新狀態。

XBOX 成就管理員 API 可簡化 XBOX Live 使用者成就狀態的追蹤與更新。

XBOX 提供一種方式，透過在特定時間點授予成就，來追蹤使用者在遊戲中的進度與成就。
使用 XBOX Services API (XSAPI) 中的成就 API 讓每位本機使用者的成就資訊保持最新，可能相當複雜。
若未正確執行，可能會導致效能問題、資料過時，或因呼叫 XBOX 成就服務的頻率高於必要而遭到節流。

Social Manager 透過下列方式解決此問題：

* 建立簡單易呼叫的 API。
* 在背景使用即時活動服務建立最新資訊。
* 開發人員可以同步呼叫成就管理員 API，而不會對服務造成任何額外負擔。

成就管理員隱藏了處理多個 RTA 訂閱、為使用者重新整理資料以及減少成就服務呼叫次數的複雜度，讓開發人員可以輕鬆取得最新的成就資料。

## 功能

成就管理員提供下列功能：

* 簡化的成就 API
* 每位使用者最新的成就狀態與進度
* 減少對 XBOX 服務的呼叫次數
  * 這直接關係到資料擷取整體延遲的降低
* 執行緒安全
* 有效率地讓資料保持最新

## 核心概念

**成就**：成就包含玩家分數以及其他獎勵 (例如數位圖稿、新地圖、角色與統計資料加成)，以及目前的完成進度。

若要讓使用者的成就狀態保持最新，必須在每個畫面格呼叫 [XblAchievementsManagerDoWork](/zh-TW/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerdowork) 函式。

<Note>在 Windows 上只能有一位本機使用者</Note>

## API 概觀

您最常使用的是下列主要 API。

您可以在 [XBOX Live API 參考](https://aka.ms/xboxliveuwpdocs)中找到成就管理員 API 的完整說明。
您也可以在 **XblAchievementsManager** 首碼文件中找到這些 API。

### 將本機使用者新增至成就管理員

* C API 函式：[XblAchievementsManagerAddLocalUser](/zh-TW/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanageraddlocaluser)

將本機使用者新增至成就管理員，會讓系統從服務擷取該使用者在目前遊戲中所有成就的狀態，並儲存在本機。

成就管理員會讓該使用者在目前遊戲中的每項成就保持最新。

### 取得使用者的成就狀態

* C API 函式：[XblAchievementsManagerGetAchievements](/zh-TW/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagergetachievements)

呼叫此函式會傳回符合指定條件之成就的控制代碼。

控制代碼所指向的成就，是相符成就的執行緒安全複本。
控制代碼所指向的資料會一直存在，直到控制代碼關閉為止；但如果遊戲在下一次呼叫 [XblAchievementsManagerDoWork](/zh-TW/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerdowork) 之後仍保留控制代碼，資料就可能過時。

## 使用方式

### 使用成就管理員事件

成就管理員會以事件的形式告訴您發生了什麼事。
您可以使用這些事件來更新 UI 或執行其他邏輯。

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

**參考**

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

#### 傳回的事件

**Local User Initial State Synced**：當成就管理員已完成擷取使用者在目前遊戲中所有成就的目前狀態時觸發。

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

**Achievement Progress Updated**：當使用者在目前遊戲中某項成就的進度已更新時觸發。

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

**Achievement Unlocked**：當使用者完成目前遊戲中某項成就的所有需求時觸發。

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

#### 其他詳細資料

成就管理員不會在遊戲迴圈中頻繁地從服務擷取成就狀態，而是在使用者向成就管理員註冊時，擷取該使用者所有成就的狀態。
接著，成就管理員會從服務接收詳述使用者成就更新的事件，然後以 \* [XblAchievementsManagerDoWork](/zh-TW/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerdowork) 函式傳回的 **events** 形式轉送給遊戲。

**events** 是 [XblAchievementsManagerEvent](/zh-TW/reference/live/xsapi-c/achievements_manager_c/structs/xblachievementsmanagerevent) 的清單，而每個 [XblAchievementsManagerEvent](/zh-TW/reference/live/xsapi-c/achievements_manager_c/structs/xblachievementsmanagerevent) 都包含上一個畫面格期間發生的成就變更。

如需詳細資訊，請參閱 [XblAchievementsManagerEvent](/zh-TW/reference/live/xsapi-c/achievements_manager_c/structs/xblachievementsmanagerevent) API 文件。

### 註冊要追蹤成就的使用者

在此情境中，您想要向成就管理員註冊使用者，以開始追蹤該使用者的成就更新，並在本機快取該使用者所有成就的狀態。

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

**參考**

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

#### 傳回的事件

**Local User Initial State Synced**：當成就管理員已完成擷取使用者在目前遊戲中所有成就的目前狀態時觸發。

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

#### 其他詳細資料

上述範例顯示如何為使用者初始化成就管理員，並讓它保持最新。

在遊戲迴圈中，[XblAchievementsManagerDoWork](/zh-TW/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerdowork) 函式會處理並套用對使用者成就所做的任何更新。

### 擷取使用者的單一成就

在此情境中，您想要取得使用者單一成就的狀態。

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

**參考**

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

#### 傳回的事件

**Local User Initial State Synced**：當成就管理員已完成擷取使用者在目前遊戲中所有成就的目前狀態時觸發。

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

### 擷取使用者的所有成就

在此情境中，您想要取得使用者所有成就的狀態。

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

**參考**

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

#### 傳回的事件

**Local User Initial State Synced**：當成就管理員已完成擷取使用者在目前遊戲中所有成就的目前狀態時觸發。

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

### 擷取使用者的部分成就

在此情境中，您想要取得使用者部分成就的狀態。

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

**參考**

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

#### 傳回的事件

**Local User Initial State Synced**：當成就管理員已完成擷取使用者在目前遊戲中所有成就的目前狀態時觸發。

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

### 擷取使用者處於特定狀態的部分成就

在此情境中，您想要取得使用者處於特定進度狀態之部分成就的狀態。

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

**參考**

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

#### 傳回的事件

**Local User Initial State Synced**：當成就管理員已完成擷取使用者在目前遊戲中所有成就的目前狀態時觸發。

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

### 更新使用者的成就

更新使用者某項成就的進度。

**C API**

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

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

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

**參考**

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

#### 傳回的事件

**Local User Initial State Synced**：當成就管理員已完成擷取使用者在目前遊戲中所有成就的目前狀態時觸發。

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

#### 其他詳細資料

只有遊戲管理型成就可以使用 [XblAchievementsManagerUpdateAchievement](/zh-TW/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerupdateachievement) 進行更新。
如需更新事件型成就，請參閱[寫入事件以驅動事件型成就](/zh-TW/services/xbox-services/player-data/achievements/event-based/how-to/live-writing-event-based-achievement)。

### 清除成就管理員

從成就管理員移除使用者時，會從成就管理員中移除該使用者的快取成就。
已移除的使用者應該不會再收到任何事件。

**C API**

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

**參考**

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


## Related topics

- [成就管理員](/zh-TW/services/xbox-services/player-data/achievements/achievements-manager/index.md)
- [多人遊戲管理員 API 概觀](/zh-TW/services/xbox-services/multiplayer/mpm/concepts/live-multiplayer-manager-api-overview.md)
- [成就](/zh-TW/services/xbox-services/player-data/achievements/index.md)
- [使用者成就系統](/zh-TW/services/xbox-services/player-data/achievements/live-achievements-nav.md)
- [遊戲管理型](/zh-TW/services/xbox-services/player-data/achievements/title-managed/index.md)