本文說明漸強 Web SDK 接收行為事件時所要求的資料格式。若資料結構不符合以下規範，事件將無法寫入系統，導致追蹤中斷、自動化觸發失效。

若您要檢查安裝與事件追蹤狀態，請參考：教學｜Web SDK 安裝與事件追蹤狀態檢查

本文內容

目前 SDK 支援以下三類事件。所有事件的呼叫方式均為：

clWidget.clSdk.clRe.record("事件名稱", { props: { ... } });

事件名稱	觸發時機	必填欄位
`page_view`	使用者進入任何頁面	`page_path`、`page_title`
`add_to_cart`	使用者將商品加入購物車	`items`（含 `item_id`、`item_name`、`price`、`quantity`）
`remove_from_cart`	使用者從購物車移除商品	同 `add_to_cart`
`purchase`	使用者完成結帳付款	`transaction_id`、`revenue`、`items`

⚠️ 請勿同時使用多種事件來源。例如同時啟用 GA4 dataLayer 與 Event Tracking API，會導致事件重複寫入。每個網站只能選擇一種傳送方式。

page_view｜頁面瀏覽

使用者進入任何頁面時觸發。page_view 也是安裝完成後最優先確認的驗證指標。

欄位規格

欄位	類型	必填	說明
`props.page_path`	String	必填	當前頁面的 URL 路徑，例如 `/products/shirt`
`props.page_title`	String	必填	當前頁面的 `<title>` 標題文字

程式碼範例

clWidget.clSdk.clRe.record("page_view", {
  props: {
    page_path: "/products/shirt",
    page_title: "夏季棉質短袖上衣｜品牌官網",
  },
});

add_to_cart / remove_from_cart｜購物車事件

加入或移除購物車時觸發，兩個事件使用完全相同的資料結構，僅事件名稱不同。

事件層級欄位

欄位	類型	必填	說明
`props.items`	Array	必填	商品陣列，至少需包含一個 item 物件
`props.currency`	String	選填	幣別代碼（ISO 4217），例如 `TWD`、`USD`

items 陣列 — 每個商品物件的欄位

欄位	類型	必填	說明
`item_id`	String	必填	商品唯一識別碼（SKU 或產品 ID）
`item_name`	String	必填	商品名稱
`price`	Number	必填	單件售價，需為數字型別（勿傳字串 "490"）。此欄位同時作為購物車再行銷動態圖卡的必要資料，請確認不為空值。
`quantity`	Number	必填	數量，需為數字型別
`description`	String	選填	商品描述文字
`affiliation`	String	選填	品牌或商店歸屬名稱
`coupon`	String	選填	商品層級的優惠券代碼
`discount`	Number	選填	商品折扣金額
`index`	Number	選填	商品在清單中的排列順序（從 1 開始）
`item_brand`	String	選填	商品品牌名稱
`item_category`	String	選填	商品分類（第一層）
`item_category2 ~ 5`	String	選填	商品分類（第二至五層）
`item_list_id`	String	選填	商品所在清單的 ID
`item_list_name`	String	選填	商品所在清單的名稱
`item_variant`	String	選填	商品規格（例如：顏色、尺寸）
`link`	String	選填	商品頁面 URL
`image_link`	String	選填	商品圖片 URL
`location_id`	String	選填	商品所在位置 ID（Google Places ID 格式）

程式碼範例

// 加入購物車
clWidget.clSdk.clRe.record("add_to_cart", {
  props: {
    currency: "TWD",
    items: [
      {
        item_id: "SKU_67890",        // 必填
        item_name: "夏季棉質短袖上衣",  // 必填
        price: 490,                  // 必填：Number，勿傳 "490"
        quantity: 1,                 // 必填：Number
        item_brand: "品牌名稱",
        item_category: "服飾",
        item_variant: "白色 / M",
        link: "https://example.com/products/shirt",
        image_link: "https://example.com/images/shirt.jpg",
      },
    ],
  },
});

// 移除購物車（結構相同，僅事件名稱不同）
clWidget.clSdk.clRe.record("remove_from_cart", {
  props: {
    currency: "TWD",
    items: [
      {
        item_id: "SKU_67890",
        item_name: "夏季棉質短袖上衣",
        price: 490,
        quantity: 1,
      },
    ],
  },
});

purchase｜完成購買

使用者完成結帳付款後觸發。此事件是購物車再行銷、轉換追蹤的核心依據，請確保必填欄位完整。

事件層級欄位

欄位	類型	必填	說明
`props.transaction_id`	String	必填	訂單唯一識別碼。系統以此欄位進行去重，相同 ID 重複送出不會重複計算
`props.revenue`	Number	必填	訂單總金額，需為數字型別
`props.items`	Array	必填	訂單商品陣列，欄位結構與 add_to_cart 相同
`props.currency`	String	選填	幣別代碼（ISO 4217），例如 `TWD`
`props.tax`	Number	選填	稅額
`props.shipping`	Number	選填	運費
`props.coupon`	String	選填	訂單層級的優惠券代碼

⚠️ transaction_id 請勿帶入流水號或時間戳記，建議直接使用訂單系統的原始訂單編號，確保全域唯一。

程式碼範例

clWidget.clSdk.clRe.record("purchase", {
  props: {
    transaction_id: "ORDER_20240101_001",  // 必填：訂單編號
    revenue: 980,                          // 必填：Number
    currency: "TWD",
    tax: 0,
    shipping: 0,
    coupon: "SUMMER_SALE",
    items: [
      {
        item_id: "SKU_67890",        // 必填
        item_name: "夏季棉質短袖上衣",  // 必填
        price: 490,                  // 必填：Number
        quantity: 2,                 // 必填：Number
        item_variant: "白色 / M",
      },
    ],
  },
});

WebSDK Identify｜會員身分識別

若您要在會員登入、註冊或其他已確認身分的流程後，將網站上的匿名瀏覽行為歸戶到既有會員，可使用 clSdk.identify。

請留意：WebSDK Identify 需在 SDK 初始化完成後，由前端主動呼叫；若未帶入任何可識別資訊，系統不會建立或更新會員資料。

技術規格摘要（Technical Summary）

await clSdk.identify({
  customerId: "REQUIRED_UNIQUE_ID", // 必填：平台用戶 ID
  email: "user@example.com",        // 選填
  name: "王小明",                   // 選填
  phone: "+886912345678",           // 選填（E.164 格式）
  gender: "male",                   // 選填（male/female/other/unknown）
  birthday: "1995-01-01"            // 選填（YYYY-MM-DD）
});

欄位規格

欄位	必填	格式 / 注意事項	對應欄位
`customerId`	必填	String，建議使用穩定不變的會員 ID	`customer_id`
`email`	選填	需符合 Email 格式	`display_email`
`name`	選填	String	`display_name`
`phone`	選填	建議使用 E.164 格式，例如 `+886912345678`	`display_mobile`
`gender`	選填	可使用 `male`、`female`、`other`、`unknown`	`gender`
`birthday`	選填	格式為 `YYYY-MM-DD`	`birth`
`address`	選填	String	`address`
`tags`	選填	Array of Strings	`Tag`
`custom_attributes`	選填	Key-Value 物件	自訂欄位

欄位映射說明 (Field Mapping)

SDK 參數	C360 欄位	說明
`customerId`	`customer_id`	主要識別 Key (Primary)
`email`	`display_email`	次要識別 Key
`phone`	`display_mobile`	支援國碼
`tags`	`Tag`	支援以 Array 形式傳入標籤

⚠️ 注意事項與常見問題 (Note & FAQ)
1. 重複呼叫：資料會採「新蓋舊」原則更新，且「忽略空值」，不會產生重複紀錄。
2. customerId 修改：不建議事後修改，這會導致歷史行為無法關聯。
3. 非阻塞調用：identify() 失敗不會影響網站主體功能，建議開發者加上 try-catch 記錄 Log 即可。

# 驗證事件是否正確送出

完成埋碼後，請依照以下步驟自行驗證，不需要等待客服確認。

步驟一：開啟瀏覽器開發者工具
在 Chrome 按 F12（Mac 為 Cmd + Option + I），切換到 Console 分頁，輸入 datalayer 進行篩選。

步驟二：聯繫漸強客戶成功團隊做最終確認
自行驗證通過後，請聯繫漸強實驗室客戶成功團隊，確認後端是否有正確收到以下事件：

page_view — 進入任意頁面
add_to_cart — 將商品加入購物車
purchase — 完成結帳，並確認 transaction_id 與 items 資料正確

# 常見錯誤對照

錯誤狀況	原因	正確做法
事件送出但後端未收到資料	`items` 傳入空陣列 `[]`	`items` 至少需包含一個商品物件
商品資料遺失	`item_id`、`item_name`、`price`、`quantity` 任一缺漏	每個 item 物件必須包含這四個必填欄位
purchase 事件無法對應訂單	未傳入 `transaction_id` 或 `revenue`	purchase 必填這兩個欄位
金額或數量資料異常	`price`、`quantity`、`revenue` 傳入字串，例如 `"490"`	數字欄位需傳入 Number 型別，例如 `490`
事件重複計算	同時啟用多種事件來源	每個網站只能選擇一種傳送方式
SDK 未載入，`clWidget` 為 undefined	GTM 代碼未正確發布，或觸發條件設定有誤	確認 GTM 觸發條件是否設為「DOM 就緒」，且容器已發布

💬 需要進一步協助？
請聯繫漸強實驗室客戶成功團隊，並提供以下資訊可加快排查速度：

📌 若您正在排查 WebSDK Identify，請一併提供：登入或註冊完成後的前端呼叫流程、Console / Network 截圖，以及是否已開啟 Web Channel 的網站身份識別功能。

安裝模式（自建電商 / SHOPLINE / CYBERBIZ / Shopify / 91APP）
瀏覽器 Console 截圖（是否有錯誤訊息）
Console 分頁中 record request 的 Payload 截圖

page_view｜頁面瀏覽

add_to_cart / remove_from_cart｜購物車事件

purchase｜完成購買

WebSDK Identify｜會員身分識別

# 驗證事件是否正確送出

# 常見錯誤對照

相關文章