事件儲存結構¶

大綱¶

您可以查看傳輸的事件日誌如何儲存在 BigQuery 中、attributes JSON 欄位的詳細結構，以及違反傳輸規則的日誌如何被隔離。

表格結構¶

發送的事件日誌儲存在公司專屬 BigQuery 資料集的 t_raw_event_log 表中。

表格欄位結構¶

儲存位置¶

項目	格式
表格	`t_raw_event_log`
分區	依 `dateTime` 的每日分區

欄位定義¶

欄位名稱	資料類型	必填	說明	範例
`userId`	STRING	Y	以帳號為基準的使用者識別碼	`100001`
`identifierProvider`	STRING	Y	發行使用者識別碼的系統。固定為 `hive`	`hive`
`deviceId`	STRING	Y	以裝置為基準的使用者識別碼	`100000`
`appId`	STRING	Y	在 Hive 控制台 > 應用程式中心註冊的 Project ID	`"com.com2us.game.ios"`
`appIdGroup`	STRING	Y	由 Hive 控制台 > 應用程式中心發行的 Game ID。依 `appId` 轉換的值	`com.com2us.game`
`dateTime`	TIMESTAMP	Y	事件發生時間。將 `eventTime` 轉換為 UTC 的值	`2026-07-20T05:01:01Z`
`eventName`	STRING	Y	用於分類事件的事件名稱	`asset_drop`
`checksum`	STRING	N	排除管道注入或系統產生的所有欄位（`hiveAttributes` 等），僅以客戶傳送的原始資料產生的雜湊值	`HW2FTEB56TEEWER`
`bigqueryRegistTimestamp`	TIMESTAMP	N	事件儲存至 BigQuery 的 UTC 時間	`2026-07-20T05:02:01Z`
`attributes`	JSON	N	儲存自訂屬性與自動收集屬性的 JSON 欄位	見下文

表格結構注意事項 & Tips¶

同一事件可能因重新傳送等原因而被重複儲存，因此建議查詢時一併使用以 checksum 為基準的去除重複查詢。
```
QUALIFY ROW_NUMBER() OVER (PARTITION BY checksum ORDER BY bigqueryRegistTimestamp DESC) = 1
```
違反傳輸規則的事件日誌會儲存在 rescue 表中，而不是此表中。詳細資訊請參閱資料隔離。

attributes 詳細屬性¶

Note

attributes 欄位為 JSON 類型，分為 hiveAttributes 與 eventAttributes 兩個區域。

attributes 範例¶

{
  "hiveAttributes": {
    "_clientIp": "220.70.82.0",
    "_dataSource": "custom_server",
    "_fluentd_appid": "com.com2us.game.ios",
    "_fluentd_sender_ip": "43.101.101.33",
    "_fluentd_hostaname": "9104813d31ab",
    "_fluentd_tag": "ha2union.game.stage",
    "_geoIpCountry": "KR",
    "_market": "google",
    "_os": "android"
  },
  "eventAttributes": {
    "eventTime": "2026-07-20T14:01:01+09:00",
    "level": 10,
    "character_name": "AA",
    "stage_id": "stage_101"
  }
}

hiveAttributes¶

這是管道自動處理並儲存的區域。

屬性名稱	資料類型	說明	範例
`_clientIp`	STRING	傳送日誌時一併傳送 `client_ip` 或 `clientIp` 的情況下，將所傳送 IP 的最後一個八位元組變更為 0 的值。未傳送 `client_ip` 或 `clientIp` 時不會產生	`220.70.82.0`
`_geoIpCountry`	STRING	管道依 `client_ip` 或 `clientIp` 判定的國家/地區代碼 (ISO 3166 alpha-2)。未傳送 `client_ip` 或 `clientIp` 時不會產生	`KR`
`_dataSource`	STRING	管道判定的事件日誌實際流入路徑。請參閱下方 `_dataSource` 詳細資訊	`custom_server`
`_fluentd_appid`	STRING	管道判定的日誌收集器 (Fluentd) 的 appId	`com.com2us.game.ios`
`_fluentd_sender_ip`	STRING	管道判定的日誌收集器 (Fluentd) 的 IP	`43.101.101.33`
`_fluentd_hostaname`	STRING	管道判定的日誌收集器 (Fluentd) 的 hostname	`9104813d31ab`
`_fluentd_tag`	STRING	管道判定的傳送至日誌收集器 (Fluentd) 的 tag 名稱	`ha2union.game.stage`
`_market`	STRING	Analytics 依 appId 資訊判定的市場資訊	`google`
`_os`	STRING	Analytics 依 appId 資訊判定的 OS 資訊	`android`

_dataSource 詳細資訊¶

_dataSource 表示事件日誌實際流入的路徑，會自動設定為下列其中一個值。

值	說明
`airbridge`	透過 Airbridge 收集的事件
`appsflyer`	透過 Appsflyer 收集的事件
`adjust`	透過 Adjust 收集的事件
`singular`	透過 Singular 收集的事件
`hive_server`	透過 Hive 身分驗證、計費等自動收集的事件
`hive_sdk`	Hive SDK 自動收集的漏斗等事件
`custom_server`	客戶從伺服器傳送的自訂事件
`custom_sdk`	客戶透過 Hive SDK 的事件日誌傳送功能傳送的自訂事件
`custom_sdk_mig`	客戶透過 Hive SDK 的事件日誌傳送功能傳送至舊版 Analytics 的自訂事件
`custom_server_mig`	客戶從伺服器傳送至舊版 Analytics 的自訂事件
`custom_except`	在事件轉換過程中作為例外情況產生並傳送 `eventAttribute`、`hiveAttribute` 的事件

eventAttributes¶

這是儲存使用者傳送的屬性與 SDK 自動收集之屬性的區域。

屬性名稱	資料類型	說明
`eventTime`	STRING	作為必要屬性傳送的 `eventTime` 原始值
（使用者定義的屬性）	數字/字元	使用者直接傳送的自訂屬性
（自動收集的屬性）	因屬性而異	SDK 自動收集的用戶端資訊（用戶端傳輸時）

attributes 注意事項 & Tips¶

hiveAttributes 不是開發者直接設定值的區域，而是由管道自動填入的區域。不會儲存 _clientIp、_dataSource、_fluentd_appid、_fluentd_sender_ip、_fluentd_hostaname、_fluentd_tag、_geoIpCountry、_market、_os 以外的值。
自訂屬性與 SDK 自動收集的屬性會一起儲存在 eventAttributes 中。查詢時必須依屬性名稱加以區分。
可使用 _dataSource 值區分事件日誌的傳輸路徑（SDK/伺服器/MMP 等）進行查詢。

資料隔離¶

Warning

不符合傳輸規則的事件日誌不會儲存在一般表 (t_raw_event_log) 中，而是另外儲存在隔離表 (t_raw_event_log_rescue) 中。隔離表會一併保留原始 JSON，因此您可以確認隔離原因、修正後重新傳送。

隔離原因¶

錯誤原因	說明	處理方式
缺少必要屬性	7 個必要屬性（`userId`、`identifierProvider`、`deviceId`、`appId`、`appIdGroup`、`eventTime`、`eventName`）中任一屬性不存在或值為空	包含缺少的必要屬性後重新傳送
使用保留字	使用 `attributes`、`eventAttributes`、`hiveAttributes` 作為屬性名稱時（不區分大小寫）	將該屬性名稱變更為其他名稱
不允許的屬性值	屬性值為 JSON 物件 (`{}`) 或 JSON 陣列 (`[]`) 形式時	將屬性值變更為字串或數字
eventTime 格式錯誤	`eventTime` 不是 RFC 3339 格式或無法解析時	修改為 RFC 3339 格式（含時區）
eventTime 超出範圍	`eventTime` 超出以當前時間為基準的過去 10 年至未來 5 年範圍時	確認 eventTime 值後修改至正常範圍
JSON 解析失敗	傳送的訊息不是有效的 JSON 格式時	驗證 JSON 格式後重新傳送

隔離表結構¶

隔離的事件日誌會以下列結構儲存在 t_raw_event_log_rescue 表中。僅在可解析原始 JSON 時才會在各欄位中儲存值，無法解析時則儲存為空值。原始資料可在 rawData 中確認。

欄位名稱	資料類型	說明
`userId`	STRING	傳送的 userId
`identifierProvider`	STRING	傳送的 identifierProvider
`deviceId`	STRING	傳送的 deviceId
`appIdGroup`	STRING	傳送的 appIdGroup
`dateTime`	STRING	傳送的 eventTime 原始值（以字串原樣儲存，而非 TIMESTAMP）
`eventName`	STRING	傳送的 eventName
`bigqueryRegistTimestamp`	TIMESTAMP	日誌儲存至 BigQuery 的時間
`checksum`	STRING	排除管道注入或系統產生的所有欄位（`hiveAttributes` 等），僅以客戶傳送的原始資料產生的雜湊值
`rawData`	STRING	傳送的完整原始 JSON
`errorReason`	STRING	隔離原因代碼。請參閱隔離原因代碼
`errorStackTrace`	STRING	隔離詳細資訊（缺少的欄位名稱等）

隔離原因代碼¶

error_code	error_key	發生條件
100	`JSON_PARSE_ERROR`	JSON 解析失敗
200	`DATETIME_MISSING`	沒有 `dateTime` 欄位或為空值
201	`DATETIME_INVALID`	無法解析 `dateTime`
—	`DATASOURCE_MISSING`	`_dataSource` 為 null 或未定義的值

隔離日誌查詢範例¶

隔離的日誌可直接在 BigQuery 中查詢。若要使用 BigQuery 查詢，必須先申請 BigQuery 權限。

SELECT
  errorReason,
  errorStackTrace,
  eventName,
  dateTime,
  rawData,
  bigqueryRegistTimestamp
FROM `habq-storage.analytics_N_live.t_raw_event_log_rescue`
WHERE appIdGroup = 'com.sample.test'  -- 實際使用的 appIdGroup
LIMIT 100;