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

# XGameEventWrite

> XGameEventWrite

# XGameEventWrite

寫入遊戲內事件，可選擇性地包含「維度」和「測量」資料欄位。

## 語法

```cpp theme={null}
HRESULT XGameEventWrite(  
         XUserHandle user,  
         const char *serviceConfigId,  
         const char *playSessionId,  
         const char* eventName,  
         const char* dimensionsJson,  
         const char* measurementsJson  
)  
```

### 參數

*user*   \_In\_\
類型：XUserHandle

代表其傳送事件的使用者控制代碼。

\**serviceConfigId*   \_In\_z\_\
類型：char

此遊戲的 XBOX Live 服務設定識別碼 (SCID)。

\**playSessionId*   \_In\_z\_\
類型：char

遊玩工作階段識別碼。這是遊戲在每個遊戲工作階段開始時建立的唯一 GUID，用來追蹤在單一遊玩工作階段中傳送的一組事件。

*eventName*   \_In\_z\_\
類型：char\*

事件名稱。

*dimensionsJson*   \_In\_opt\_z\_\
類型：char\*

JSON 格式的維度資料欄位。

*measurementsJson*   \_In\_opt\_z\_\
類型：char\*

JSON 格式的測量資料欄位。

### 傳回值

類型：HRESULT

如果成功，則傳回 S\_OK；否則傳回錯誤碼。如需錯誤碼清單，請參閱[錯誤碼](/zh-TW/reference/errorcodes)。

## 備註

<Note>在時間敏感的執行緒上呼叫此函式並不安全。如需詳細資訊，請參閱[時間敏感的執行緒](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)。</Note>

維度包含具有有限數量已定義數值或字串值的事件欄位。維度範例：地圖識別碼、難度等級、角色或武器類別、遊戲模式、布林值設定等。測量包含代表純量數值計量的事件欄位。測量範例：分數、時間、計數器、位置等。例如：對於追蹤某難度等級最高對戰分數的遊戲內事件，難度等級應包含在維度中，而分數應包含在測量中。事件名稱以及維度和測量中事件欄位的名稱，必須與遊戲服務設定中宣告的名稱相符。名稱不區分大小寫。如果 API 寫入的事件名稱與服務設定中的名稱不符，服務會捨棄該事件，且不會發出通知。

<Note>測量只能有數值，而維度可以有更多種類型。如有需要，可以只使用 *dimensionsJson* 欄位來寫入事件。</Note>

## 需求

**標頭：** XGameEvent.h

**程式庫：** xgameruntime.lib

**支援的平台：** Windows、XBOX One 系列主機和 XBOX Series 主機

## 概念文件

* [時間敏感的執行緒](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)

## 另請參閱

[XGameEvent](/zh-TW/reference/system/xgameevent/xgameevent_members)


## Related topics

- [XGameEventWrite](/reference/system/xgameevent/functions/xgameeventwrite.md)
- [XGameEvent](/reference/system/xgameevent/xgameevent_members.md)