> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 寫入事件以驅動事件型成就

> XblEventsWriteInGameEvent 範例程式碼，可觸發遊戲事件，讓 XBOX 服務統計資料規則更新統計資料並解鎖事件型成就。

本主題顯示如何寫入遊戲內事件的範例程式碼。

觸發事件時，服務上的事件型統計資料會根據您在 Partner Center 中定義的統計資料規則進行更新。
這些統計資料接著會驅動事件型成就。

## 開始之前

* 您的產品使用完整的 XBOX 服務功能集。新產品一開始只有有限的 XBOX 服務，在您的產品完成加入之前，無法使用成就和玩家分數。如需詳細資訊，請參閱[要求產品加入以啟用完整 XBOX 服務](https://docs.xbox.com/zh-TW/home/onboarding.md#request-product-onboarding-to-enable-full-xbox-services)。
* 您已在 Partner Center 中設定事件、統計資料規則和成就，並已將 XBOX 服務設定發佈至您的開發沙箱。
* 您的開發套件或 Windows PC 使用相同的開發沙箱，且您使用可存取該沙箱的測試帳戶登入。如需詳細資訊，請參閱 [XBOX 服務沙箱概觀](https://docs.xbox.com/zh-TW/services/xbox-services/fundamentals/sandboxes/live-setup-sandbox.md)。
* 您的遊戲已初始化 Gaming Runtime，然後使用 [XblInitArgs](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/xbox_live_global_c/structs/xblinitargs.md) 結構呼叫 [XblInitialize](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/xbox_live_global_c/functions/xblinitialize.md)，且該結構的 `scid` 成員包含您的服務設定識別碼 (SCID)。SCID 區分大小寫。如需詳細資訊，請參閱[如何使用 XBOX 服務 API](https://docs.xbox.com/zh-TW/services/xbox-services/fundamentals/xbox-services-api/live-gs-xbl-apis.md)。
* 您已讓使用者登入，並呼叫 [XblContextCreateHandle](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/xbox_live_context_c/functions/xblcontextcreatehandle.md) 為該使用者建立 `XblContextHandle`。

若要在測試回合之間重設測試帳戶的成就和統計資料，請使用[玩家資料重設工具 (XblPlayerDataReset.exe)](https://docs.xbox.com/zh-TW/tools/tools-services/live-player-data-reset.md)。若要依 XUID 重設玩家，您使用 XblDevAccount.exe 登入的開發人員帳戶需要產品層級的 Tools Access 權限。

## 寫入事件

下列範例使用平面 C API。`LogToScreen` 代表您應用程式的記錄函式。

```cpp theme={null}
HRESULT hr = XblEventsWriteInGameEvent(
    xboxLiveContext,
    "PuzzleSolved",
    R"({"DifficultyLevelId":100, "GameplayModeId":"Adventure"})",
    R"({"LocationX":1,"LocationY":1})"
);
if (FAILED(hr))
{
    // Log the failure. Don't retry the call in a loop.
    LogToScreen("XblEventsWriteInGameEvent failed: 0x%08X", static_cast<unsigned int>(hr));
}
```

如需詳細資訊，請參閱 [XblEventsWriteInGameEvent](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/events_c/functions/xbleventswriteingameevent.md)。

## 疑難排解

* **呼叫傳回 `E_INVALIDARG`。** *xboxLiveContext* 或事件名稱為 null。
* **呼叫傳回 `E_XBL_NOT_INITIALIZED`。** 請在寫入事件之前呼叫 `XblInitialize`。
* **呼叫傳回 `E_NOTIMPL`。** Gaming Runtime 的 XGameEvent 功能無法使用。在 Windows PC 上，已安裝的 Gaming Runtime Services 必須包含 XGameEvent 功能。
* **呼叫成功，但統計資料或成就沒有變更。** 事件名稱和事件欄位的名稱必須與您遊戲之服務設定中的名稱相符。名稱不區分大小寫。如果事件名稱與服務設定中的事件不相符，服務會捨棄該事件，而不會通知您的遊戲。
* **欄位值放錯位置。** 請將具有有限數值或字串值集合的欄位 (例如難度等級或遊戲模式) 放在維度中。請將純量數值計量 (例如分數、時間或位置) 放在測量中。
* **更新需要時間。** 事件會在裝置上本機寫入 (即使裝置離線也一樣)，並在裝置連線時上傳。如果裝置已連線，事件型統計資料通常會在寫入事件後 5 到 20 秒內更新。


## Related topics

- [事件型成就範例程式碼](https://docs.xbox.com/zh-TW/services/xbox-services/player-data/achievements/event-based/how-to/live-achievements-eb-howto-nav.md)
- [事件型成就範例](https://docs.xbox.com/zh-TW/services/xbox-services/player-data/achievements/event-based/how-to/index.md)
- [XBOX 成就管理員 API 概觀](https://docs.xbox.com/zh-TW/services/xbox-services/player-data/achievements/achievements-manager/live-achievements-manager-overview.md)
- [寫入事件以驅動事件型統計資料](https://docs.xbox.com/zh-TW/services/xbox-services/player-data/stats-leaderboards/event-based/how-to/live-sending-eb-stat.md)
- [事件型統計資料與排行榜範例程式碼 (內容)](https://docs.xbox.com/zh-TW/services/xbox-services/player-data/stats-leaderboards/event-based/how-to/live-statslb-eb-howto-nav.md)