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

# 更新遊戲管理型成就

> XSAPI 範例程式碼，示範如何使用 XblAchievementsUpdateAchievementAsync 解鎖遊戲管理型 XBOX Live 成就或回報完成進度。

<a id="top" />

本主題涵蓋下列內容：

* [解鎖成就](#unlocking-an-achievement)
* [更新成就的完成進度](#updating-an-achievement)

<a id="unlocking-an-achievement" />

## 解鎖成就

透過 Partner Center 設定成就並發佈至您的開發沙箱之後，您的遊戲就可以呼叫 [XblAchievementsUpdateAchievementAsync](/zh-TW/reference/live/xsapi-c/achievements_c/functions/xblachievementsupdateachievementasync) API 來解鎖成就。
如需詳細資訊，請參閱下一節中的範例程式碼。

若要解鎖成就，請將 `percentComplete` 設為 100。
如果使用者在線上，要求會立即傳送至 XBOX 服務成就服務，並觸發下列使用者體驗。

* 使用者會收到「成就已解鎖」通知。
* 指定的成就會在使用者該遊戲的成就清單中顯示為已解鎖。
* 已解鎖的成就會新增至使用者的活動摘要。

<Note>無論成就使用事件型成就或遊戲管理型成就，使用者體驗在視覺上都相同。</Note>

如果使用者離線，解鎖要求會在使用者的裝置上本機排入佇列。
裝置重新建立網路連線後，要求就會自動傳送至成就服務 (遊戲不需要採取任何動作來觸發此作業)，並如前所述發生先前的使用者體驗。

<a id="updating-an-achievement" />

## 更新成就的完成進度

若要更新使用者解鎖成就的進度，請呼叫 [XblAchievementsUpdateAchievementAsync](/zh-TW/reference/live/xsapi-c/achievements_c/functions/xblachievementsupdateachievementasync)。將 `percentComplete` 引數設為 1 到 100 之間的整數。
如需詳細資訊，請參閱下列範例程式碼。

成就的進度只能增加。
如果 `percentComplete` 設定的數字小於成就上一次的 `percentComplete` 值，則會忽略此更新。
例如，如果成就的 `percentComplete` 先前已設為 75，則傳送值為 25 的更新會被忽略。該成就仍會顯示為完成 75%。

如果 `percentComplete` 設為 100，成就就會解鎖。

如果 `percentComplete` 設定的數字大於 100，API 的行為會如同您將數字設為剛好 100。

### 更新目前遊戲的成就

您可以呼叫 [XblAchievementsUpdateAchievementAsync](/zh-TW/reference/live/xsapi-c/achievements_c/functions/xblachievementsupdateachievementasync) 來更新目前遊戲的成就，如下所示。

**Flat C API**

```cpp theme={null}
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();
}
```

如需詳細資訊，請參閱下列內容：

* [XAsyncBlock](/zh-TW/reference/system/xasync/structs/xasyncblock)
* [XAsyncGetStatus](/zh-TW/reference/system/xasync/functions/xasyncgetstatus)
* [XblAchievementsUpdateAchievementAsync](/zh-TW/reference/live/xsapi-c/achievements_c/functions/xblachievementsupdateachievementasync)

### 更新其他遊戲的成就

您可以使用 [XblAchievementsUpdateAchievementForTitleIdAsync](/zh-TW/reference/live/xsapi-c/achievements_c/functions/xblachievementsupdateachievementfortitleidasync) 來更新另一個 `titleId` 的成就，如下所示。

**Flat C API**

```cpp theme={null}
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();
}
```

如需詳細資訊，請參閱下列內容：

* [XAsyncBlock](/zh-TW/reference/system/xasync/structs/xasyncblock)
* [XAsyncGetStatus](/zh-TW/reference/system/xasync/functions/xasyncgetstatus)
* [XblAchievementsUpdateAchievementForTitleIdAsync](/zh-TW/reference/live/xsapi-c/achievements_c/functions/xblachievementsupdateachievementfortitleidasync)

[返回本主題頂端。](#top)


## Related topics

- [遊戲管理型成就範例程式碼](/zh-TW/services/xbox-services/player-data/achievements/title-managed/how-to/live-achievements-howto-nav.md)
- [操作說明](/zh-TW/services/xbox-services/player-data/achievements/title-managed/how-to/index.md)
- [事件型成就與遊戲管理型成就](/zh-TW/services/xbox-services/player-data/achievements/live-achievements-eb-vs-tm.md)
- [遊戲管理型成就](/zh-TW/services/xbox-services/player-data/achievements/title-managed/live-achievements-tm-nav.md)
- [在 Partner Center 中設定遊戲管理型成就](/zh-TW/services/xbox-services/player-data/achievements/title-managed/config/live-achievements-tm-config.md)