> ## 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 Achievements Manager API の概要

> XSAPI の XBOX Achievements Manager API がポーリング、RTA サブスクリプション、ユーザーの XBOX Live 実績の最新状態管理を簡素化する方法。

XBOX Achievements Manager API は、XBOX Live ユーザーの実績状態の追跡および更新を簡素化します。

XBOX では、ゲーム中の特定のポイントで実績を付与することで、ユーザーの進行状況や達成を記録できます。
XBOX Services API (XSAPI) の実績 API を使用して、各ローカル ユーザーの実績情報を最新に保つのは複雑になり得ます。
これを正しく行わないと、パフォーマンス上の問題、古いデータ、あるいは必要以上に頻繁に XBOX 実績サービスを呼び出したことによるスロットリングが発生する可能性があります。

Social Manager は次の方法でこの問題を解決します。

* 呼び出しやすいシンプルな API の提供。
* 内部でリアルタイム アクティビティ サービスを利用して最新情報を作成。
* 開発者はサービスへの余計な負荷をかけることなく、Achievements Manager API を同期的に呼び出せます。

Achievements Manager は、複数の RTA サブスクリプションの扱い、ユーザー データの更新、実績サービスへの呼び出し回数の削減といった複雑さを隠蔽し、開発者が最新の実績データを簡単に取得できるようにします。

## 機能

Achievements Manager では次の機能が提供されます。

* 簡素化された実績 API
* 各ユーザーの最新の実績状態と進行状況
* XBOX services への呼び出し回数の削減
  * データ取得における全体的なレイテンシの低減に直結します
* スレッドセーフ
* データを効率的に最新に保つ

## 主要な概念

**実績 (Achievements)**: 実績には Gamerscore や、デジタル アートワーク、新しいマップ、キャラクター、ステータス ブーストなどのその他の報酬、および完了までの現在の進行状況が含まれます。

ユーザーの実績状態を最新に保つには、[XblAchievementsManagerDoWork](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerdowork) 関数を毎フレーム呼び出す必要があります。

<Note>Windows ではローカル ユーザーは 1 人しか存在できません。</Note>

## API の概要

次に示す主要な API を最も頻繁に使用することになります。

Achievements Manager API の完全な説明は、[XBOX Live API リファレンス](https://aka.ms/xboxliveuwpdocs) にあります。
また、**XblAchievementsManager** プレフィックスのドキュメントでも API を確認できます。

### Achievements Manager へのローカル ユーザーの追加

* C API 関数: [XblAchievementsManagerAddLocalUser](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanageraddlocaluser)

Achievements Manager にローカル ユーザーを追加すると、現在のタイトルにおけるそのユーザーのすべての実績の状態がサービスから取得され、ローカルに保存されます。

Achievements Manager は、現在のタイトルにおけるそのユーザーの各実績を最新に保ちます。

### ユーザーの実績状態の取得

* C API 関数: [XblAchievementsManagerGetAchievements](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagergetachievements)

この関数を呼び出すと、指定した条件に一致する実績へのハンドルが返されます。

ハンドルが指す実績は、一致する実績のスレッドセーフなコピーです。
ハンドルが指すデータはハンドルが閉じられるまで存在しますが、[XblAchievementsManagerDoWork](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerdowork) の次の呼び出しをタイトルがハンドルを保持したまま超えると、古くなる可能性があります。

## 使用方法

### Achievements Manager イベントの使用

Achievements Manager は、発生した内容をイベントの形式で通知します。
これらのイベントを利用して 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](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerdowork)
* [XblAchievementsManagerEvent](/reference/live/xsapi-c/achievements_manager_c/structs/xblachievementsmanagerevent)

#### 返されるイベント

**Local User Initial State Synced**: Achievements Manager が、ユーザーの現在のタイトルのすべての実績の現在の状態の取得を完了したときに発生します。

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

**Achievement Progress Updated**: 現在のタイトルの実績に対するユーザーの進行状況が更新されたときに発生します。

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

**Achievement Unlocked**: ユーザーが現在のタイトルの実績のすべての要件を完了したときに発生します。

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

#### 追加の詳細

ゲーム ループ中にサービスから頻繁に実績の状態を取得する代わりに、Achievements Manager は Achievements Manager にユーザーが登録された時点でそのユーザーのすべての実績の状態を取得します。
その後、Achievements Manager はサービスからユーザーの実績の更新に関する詳細イベントを受信し、それらは [XblAchievementsManagerDoWork](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerdowork) 関数から返される **events** としてタイトルに転送されます。

**events** は [XblAchievementsManagerEvent](/reference/live/xsapi-c/achievements_manager_c/structs/xblachievementsmanagerevent) のリストであり、各 [XblAchievementsManagerEvent](/reference/live/xsapi-c/achievements_manager_c/structs/xblachievementsmanagerevent) には直前のフレーム中に発生した実績への変更が含まれています。

詳細は [XblAchievementsManagerEvent](/reference/live/xsapi-c/achievements_manager_c/structs/xblachievementsmanagerevent) API ドキュメントを参照してください。

### 実績を追跡するユーザーの登録

このシナリオでは、Achievements Manager にユーザーを登録して、そのユーザーの実績への更新の追跡を開始し、そのユーザーのすべての実績の状態をローカルにキャッシュします。

**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](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanageraddlocaluser)
* [XblAchievementsManagerDoWork](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerdowork)
* [XblAchievementsManagerEvent](/reference/live/xsapi-c/achievements_manager_c/structs/xblachievementsmanagerevent)

#### 返されるイベント

**Local User Initial State Synced**: Achievements Manager が、ユーザーの現在のタイトルのすべての実績の現在の状態の取得を完了したときに発生します。

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

#### 追加の詳細

上記の例では、ユーザーに対して Achievements Manager を初期化し、最新に保つ方法を示しています。

ゲーム ループでは、[XblAchievementsManagerDoWork](/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](/reference/live/xsapi-c/achievements_c/structs/xblachievement)
* [XblAchievementsManagerAddLocalUser](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanageraddlocaluser)
* [XblAchievementsManagerIsUserInitialized](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerisuserinitialized)
* [XblAchievementsManagerGetAchievement](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagergetachievement)
* [XblAchievementsManagerResultGetAchievements](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerresultgetachievements)
* [XblAchievementsManagerResultCloseHandle](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerresultclosehandle)

#### 返されるイベント

**Local User Initial State Synced**: Achievements Manager が、ユーザーの現在のタイトルのすべての実績の現在の状態の取得を完了したときに発生します。

* C API: [XblAchievementsManagerEventType](/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](/reference/live/xsapi-c/achievements_c/structs/xblachievement)
* [XblAchievementOrderBy](/reference/live/xsapi-c/achievements_c/enums/xblachievementorderby)
* [XblAchievementsManagerSortOrder](/reference/live/xsapi-c/achievements_manager_c/enums/xblachievementsmanagersortorder)
* [XblAchievementsManagerAddLocalUser](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanageraddlocaluser)
* [XblAchievementsManagerIsUserInitialized](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerisuserinitialized)
* [XblAchievementsManagerGetAchievements](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagergetachievements)
* [XblAchievementsManagerResultGetAchievements](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerresultgetachievements)
* [XblAchievementsManagerResultCloseHandle](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerresultclosehandle)

#### 返されるイベント

**Local User Initial State Synced**: Achievements Manager が、ユーザーの現在のタイトルのすべての実績の現在の状態の取得を完了したときに発生します。

* C API: [XblAchievementsManagerEventType](/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](/reference/live/xsapi-c/achievements_c/structs/xblachievement)
* [XblAchievementOrderBy](/reference/live/xsapi-c/achievements_c/enums/xblachievementorderby)
* [XblAchievementsManagerSortOrder](/reference/live/xsapi-c/achievements_manager_c/enums/xblachievementsmanagersortorder)
* [XblAchievementsManagerAddLocalUser](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanageraddlocaluser)
* [XblAchievementsManagerIsUserInitialized](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerisuserinitialized)
* [XblAchievementsManagerGetAchievements](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagergetachievements)
* [XblAchievementsManagerResultGetAchievements](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerresultgetachievements)
* [XblAchievementsManagerResultCloseHandle](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerresultclosehandle)

#### 返されるイベント

**Local User Initial State Synced**: Achievements Manager が、ユーザーの現在のタイトルのすべての実績の現在の状態の取得を完了したときに発生します。

* C API: [XblAchievementsManagerEventType](/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](/reference/live/xsapi-c/achievements_c/structs/xblachievement)
* [XblAchievementOrderBy](/reference/live/xsapi-c/achievements_c/enums/xblachievementorderby)
* [XblAchievementProgressState](/reference/live/xsapi-c/achievements_c/enums/xblachievementprogressstate)
* [XblAchievementsManagerSortOrder](/reference/live/xsapi-c/achievements_manager_c/enums/xblachievementsmanagersortorder)
* [XblAchievementsManagerAddLocalUser](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanageraddlocaluser)
* [XblAchievementsManagerIsUserInitialized](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerisuserinitialized)
* [XblAchievementsManagerGetAchievementsByState](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagergetachievementsbystate)
* [XblAchievementsManagerResultGetAchievements](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerresultgetachievements)
* [XblAchievementsManagerResultCloseHandle](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerresultclosehandle)

#### 返されるイベント

**Local User Initial State Synced**: Achievements Manager が、ユーザーの現在のタイトルのすべての実績の現在の状態の取得を完了したときに発生します。

* C API: [XblAchievementsManagerEventType](/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](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanageraddlocaluser)
* [XblAchievementsManagerIsUserInitialized](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerisuserinitialized)
* [XblAchievementsManagerUpdateAchievement](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerupdateachievement)

#### 返されるイベント

**Local User Initial State Synced**: Achievements Manager が、ユーザーの現在のタイトルのすべての実績の現在の状態の取得を完了したときに発生します。

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

#### 追加の詳細

[XblAchievementsManagerUpdateAchievement](/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerupdateachievement) を使用して更新できるのは、タイトル マネージド実績のみです。
イベント ベースの実績の更新については、[イベント ベースの実績を有効にするためのイベントの書き込み](/services/xbox-services/player-data/achievements/event-based/how-to/live-writing-event-based-achievement) を参照してください。

### Achievements Manager のクリーンアップ

Achievements Manager からユーザーを削除すると、Achievements Manager からそのユーザーのキャッシュされた実績が削除されます。
削除されたユーザーについて、それ以降イベントは受信されないはずです。

**C API**

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

**リファレンス**

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