技術規格｜SDK 事件資料格式與驗證指南 – 漸強實驗室幫助中心

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

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

本文內容

事件總覽
page_view — 頁面瀏覽
add_to_cart / remove_from_cart — 購物車事件
purchase — 完成購買
WebSDK Identify — 會員身分識別
驗證事件是否正確送出
常見錯誤對照

目前 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,
      },
    ],
  },
});

進階｜使用 GA4／GTM dataLayer 物件格式時的轉換設定（parse）

若您的網站不是呼叫上方的 clWidget.clSdk.clRe.record()，而是透過 GTM／GA4 的標準物件格式推送事件（例如 dataLayer.push({ event: "add_to_cart", ecommerce: { value, items } })），因為結構與 SDK 預期的格式不同，事件會在進入外掛時因格式驗證未通過而被略過、不送出，且不會出現任何錯誤訊息（這也是為什麼後台常常只收得到 page_view）。

漸強的 DataLayer Plugin（clPluginDataLayer）提供 parse 自訂轉換函式，可在事件送出前，把既有的 dataLayer 物件格式轉成 SDK 可辨識的結構，不需改動網站既有的 GTM 事件埋設。

運作方式

clPluginDataLayer 接受一個 parse 函式，在每次事件發生時處理事件資料。
若未提供 parse，系統會以預設的 dataLayer 格式處理事件。
parse 的輸入是原始事件 payload，輸出必須符合系統預期的結構："0" 固定為 "event"、"1" 為事件名稱、"2" 為送往後端的 payload。

程式碼範例

以下範例示範如何把 GA4 ecommerce 物件格式，轉換成系統預期的格式後再送出：

clPluginDataLayer({
  parse: (data) => {
    // 若推入的是陣列（gtag 參數格式），取第一個元素；否則直接使用該物件
    const item = Array.isArray(data) && data.length > 0 ? data[0] : data;
    if (
      item &&
      typeof item === "object" &&
      !Array.isArray(item) &&
      "event" in item &&
      "ecommerce" in item
    ) {
      // 轉換成系統預期的結構
      // "0" 固定為 "event"
      // "1" 為事件名稱（例如 add_to_cart）
      // "2" 為送往後端的 payload（value、items 等）
      return [
        {
          "0": "event",
          "1": item.event,
          "2": item.ecommerce,
        },
      ];
    }
    return item;
  },
});

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｜會員身分識別（2026.06 更新）

當訪客在您的網站完成登入或註冊後，可透過 WebSDK Identify 把會員身分傳給漸強，將該訪客先前以匿名身分累積的瀏覽足跡歸戶到既有會員，後續才能精準觸發自動化推播與分眾。

它採用與 GA4 相同的 dataLayer 機制：在登入／註冊成功後，往 window.dataLayer push 一個 clIdentity 事件即可，不需要呼叫額外的 API。

用戶登入　→　dataLayer.push(clIdentity)　→　SDK 偵測事件　→　同步到 MAAC　→　精準行銷

⚠️ 前置條件：請先開啟該 Web Channel 的「網站追蹤功能」。若未開啟，即使正確 push clIdentity，系統也不會儲存會員資料，且不會出現任何錯誤訊息。設定路徑：管理中心 → 渠道設定 → 網站 → 一般設定。

① 要做什麼：在登入／註冊成功後 push 事件

請在前端「已確認身分」的流程中（例如登入成功的 callback）push 以下事件。customerId 為必填，其餘欄位皆為選填；若未帶入 customerId，系統不會建立或更新會員資料。

window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
  event: "clIdentity",
  params: {
    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）
    address: "台北市信義區..."         // 選填
  }
});

② 欄位規格

欄位	必填	格式 / 注意事項	對應欄位
`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`

📌 選填欄位格式不符時的行為：若某個選填欄位格式不正確（例如 gender 非上述值、phone 未含國碼、birthday 非 YYYY-MM-DD），系統會略過該欄位但仍會建立／更新會員，不會整筆失敗，也不會回傳錯誤。請於上線前自行確認各欄位格式正確。

③ 呼叫時機

時機	是否 push clIdentity	說明
會員登入成功	✅ 要 push	有穩定的會員編號，是最主要的識別時機
會員註冊完成	✅ 要 push	新會員第一次識別
用戶登出	❌ 不需呼叫	SDK 會自動維持當前身份；切換用戶時，待新用戶登入再 push 即可
訪客瀏覽（未登入）	❌ 不要 push	沒有穩定的 `customerId`，不應對匿名訪客 push

④ 如何確認識別成功（驗證方式）

會員身分識別不在「事件追蹤狀態檢查」工具的檢查範圍內，請依下列方式確認：

確認該 Web Channel 的「網站追蹤功能」已開啟（見上方前置條件）。
在登入／註冊頁面開啟瀏覽器開發者工具的 Console，輸入 dataLayer 檢視，確認其中有 clIdentity 事件、且 customerId 已正確帶入。
切到 Network 分頁，確認登入後出現一個 POST /api/v1/authenticate 請求，且 request payload 帶有您的 customer_id。
最後請聯繫漸強客戶成功團隊，協助確認後台是否已建立／更新對應的會員資料。

⑤ 注意事項與常見問題

我已 push clIdentity，但後台查不到會員資料，怎麼辦？

這通常不是「報錯」，而是其中一個條件沒滿足導致靜默略過（不會出現錯誤訊息）。請依序確認：

該 Web Channel 的「網站追蹤功能」是否已開啟——未開啟時，整筆 identify 會被略過且不報錯（最常見原因）。
push 的 params 是否有帶 customerId（必填）——缺 customerId 時不會建立或更新會員。
選填欄位格式是否正確——phone 需含國碼、gender 需為 male/female/other/unknown、birthday 需為 YYYY-MM-DD；格式錯誤的欄位會被略過，但其餘欄位仍會寫入。
依上方「④ 如何確認識別成功」用 Console / Network 檢查 clIdentity 事件與 POST /api/v1/authenticate 請求。

提醒：會員身分識別不會出現在「事件追蹤狀態檢查」工具，請改向漸強客戶成功團隊確認後台會員資料。

重複 push 相同的 customerId 會發生什麼？

SDK 會自動合併相同 customerId 的事件，採「新蓋舊、忽略空值」原則更新，只有在資料有變化時才會重新驗證，不會產生重複的會員紀錄。

用戶登出或切換帳號時要做什麼？

登出不需要呼叫任何方法，SDK 會自動維持當前身份。當有新用戶登入時，再 push 新的 customerId 即可，SDK 會自動建立對應。（避免在頁面重整時遺失對應，與業界建議一致。）

customerId 可以事後修改嗎？

不建議修改。customerId 是會員身分的主要識別碼，修改會導致無法關聯歷史行為資料。請使用穩定不變的會員編號作為 customerId。

clIdentity 失敗會影響網站嗎？

不會。clIdentity 為非阻塞事件，即使後續 API 呼叫失敗，也不會影響網站本身的正常運作。建議開發者加上 try-catch 記錄 log 即可。

不同裝置使用相同 customerId 會發生什麼？

會共用同一筆會員紀錄並持續更新；該用戶在不同裝置的瀏覽行為，皆可透過 customerId 串連到同一位會員。

驗證事件是否正確送出

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

步驟一：開啟瀏覽器開發者工具
在 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｜會員身分識別 （2026.06 更新）

驗證事件是否正確送出

常見錯誤對照

相關文章

WebSDK Identify｜會員身分識別（2026.06 更新）