智解家（All-Pass AI）GA4 埋點規格書

版本：v4.8 日期：2026-04-01 GA4 Property：G-YNYMSRYLP3（已部署） Google Ads ID：18007549282（已部署） GTM Container：GTM-MS9F9PVG（已部署） API Base：api.all-pass.ai/api/v1/ Frontend Repo：allstars-rocks/lawsome-frontend

1. 命名規範

2. User Identity 策略

user_id（唯一的 User Property）

設計決策：User Properties 只保留 user_id，不追蹤 subscription_status。

• GA4 User Properties 不是 state machine，沒有 ordered updates 或 conflict resolution。訂閱狀態以 server DB 為 authoritative source。
• 需要按訂閱狀態分析？透過 BigQuery export join server DB，比 User Property 更可靠。
• 需要 Google Ads remarketing Audience？用 event-based Audience（例如「30 天內觸發 purchase 且未觸發 subscription_cancel 的用戶」），比 property-based 更準確。

user_id 設定時機

SPA 注意：gtag('set') 在 SPA page lifecycle 內持續有效（包含 route navigation），但 hard refresh 或新分頁會重置，必須在 App mount 時重新設定。

GA4 Identity 擷取（供 Measurement Protocol 使用）

Server-side 事件需要以下欄位才能正確 stitch 到 client session。前端在註冊/登入時擷取，透過 API 送到 backend 存入 user table。

client_id vs user_id：

• client_id = GA4 自動產生，每個瀏覽器/裝置一個，匿名訪客就有。是 GA4 的主要身份軸。
• user_id = 應用程式的用戶 ID，註冊/登入後才有。是在 client_id 之上的 overlay，讓 GA4 能 stitch 不同裝置的 session。
• 兩者不可互相取代。MP 必須提供 client_id，user_id 用於跨裝置合併。

Ad blocker fallback：若 gtag 被擋導致無法取得 client_id，server 可生成 synthetic UUID（格式：<random>.<timestamp>）。GA4 接受任意字串，但會失去與匿名瀏覽 session 的 stitch。

GA4 Property 設定：Admin → Identity → Reporting Identity 必須設為 Blended（推薦）或 Observed，否則 user_id 會被收集但在報表中被忽略。

3. 埋點架構：Client-side vs Server-side

Client-side（dataLayer.push）

UI 互動事件與即時回饋事件，透過 GTM dataLayer 實作。

Server-side（GA4 Measurement Protocol v2）

Subscription lifecycle 與部分練習事件由 server 觸發，確保資料正確性：

前端配合

Frontend 在呼叫 registration / login / subscription API 時，一併傳送 GA Identity 欄位（client_id, session_id, session_number），讓 server 的 MP 呼叫能正確歸因到 client session。

Measurement Protocol 注意事項

DB Schema 擴充

User table 需新增以下欄位以支援 Measurement Protocol：

4. 事件總覽

核心漏斗（P1）— 21 個事件

flowchart TD
    CTA["cta_click"] --> SS["sign_up_start"]
    SS --> SU["sign_up"]:::server
    SU --> EV["email_verify_complete"]
    LI["login"] -.->|回訪| EV

    EV -->|做題| PS["practice_session_start"]
    EV -->|購買| PW["paywall_impression"]
    EV -->|試用| TI["trial_impression"]

    PS --> SC["subtopic_complete ×N"]:::server
    SC --> TI

    PW --> AP["add_payment_info"]
    TI --> AP

    AP -->|直接購買| BC["begin_checkout"]
    BC --> PU["purchase"]:::server

    AP -->|免費試用| TS["trial_start"]:::server
    TS --> TC["trial_cancel"]:::server
    TS --> TCONV["trial_converted"]:::server
    TCONV --> PU

    PU -->|續訂| PU
    PU --> SKC["subscription_cancel"]:::server
    SKC --> SKE["subscription_expire"]:::server

    classDef server fill:#e8f5e9,stroke:#2e7d32

綠色 = Server-side（Measurement Protocol），紫色 = Client-side

Client-side 事件（13 個）

Server-side 事件（8 個，Measurement Protocol）

低優先（P2）— 13 個事件

5. 事件詳細規格

A. Landing Page（all-pass.ai）

A-1. page_view（GA4 自動）

SPA 注意：需確認 GA4 Enhanced Measurement 的 History Change 偵測已開啟。若 SPA 內頁面切換不觸發 page_view，需補 manual firing。

A-2. landing_scroll（Client-side）

以 Section 為追蹤單位，可透過 GTM Scroll Depth trigger 實作。

A-3. cta_click（Client-side）

button_text 較 button_id 適合：Landing Page CTA 無固定 ID 屬性，且文字在報表中可讀性更高。可透過 GTM Click trigger 實作。

B. 帳號流程（app.all-pass.ai/login）

B-1. sign_up_start（Client-side）

用途：搭配 sign_up 計算註冊轉換率（start → complete），識別表單 UX 摩擦點。

B-2. sign_up（Server-side MP）

Google OAuth：與登入走同一 API，需後端回傳 is_new_user flag 區分。

B-3. signup_error（Client-side）

B-4. login（Client-side）

（無額外參數）

登入成功後需同時設定 user_id 並擷取 GA Identity 存入 backend（見 Section 2）。

B-5. login_error（Client-side）

B-6. email_verify_complete（Client-side）

（無額外參數，僅在驗證成功時 fire，不含 error 情境）

C. Dashboard（/dashboard）

C-1. dashboard_cta_click（Client-side）

（無額外參數）

D. 題庫（/question-bank）

D-0. question_bank_page_view（Client-side）

（無額外參數）

用途：追蹤題庫頁面造訪量，搭配 filter_apply 和 practice_session_start 可計算「瀏覽 → 篩選 → 開始做題」的轉換率。

D-1. filter_apply（Client-side）

E. 課程與老師專區

E-0. teacher_page_view（Client-side）

（無額外參數）

用途：追蹤老師專區造訪量。搭配 course_view 和 paywall_impression（source: teacher_view_plan）可分析老師專區的付費轉換路徑。

E-1. course_view（Client-side）

E-2. course_button_click（Client-side）

用途：追蹤「未購買但對這門課有興趣」的用戶行為。button_type 區分不同意圖：view_questions（查看題目）、view_plan（查看訂閱方案）、enter_course（嘗試進入課程）。

E-3. paywall_impression（Client-side）

Paywall 觸發來源（source 參數值）：

• locked_content — 課程內的鎖定內容覆蓋層（未購買用戶看到的鎖定內容）
• course_practice_button — 題目頁的「開始練習」按鈕
• course_view_plan — 課程頁面「查看訂閱方案」按鈕
• teacher_view_plan — 老師專區「查看訂閱方案」按鈕

E-4. trial_impression（Client-side）

與 paywall_impression 的區別：paywall_impression 是訂閱方案的曝光（直接購買路徑），trial_impression 是免費試用邀請的曝光（試用路徑）。兩者在漏斗中處於同一層級，由用戶的試用資格決定顯示哪一個。

用途：搭配 trial_start 計算試用轉換率（impression → start）。與 paywall_impression 分開追蹤，可比較兩條路徑的轉換效率。

F. 練習做題（/practice-session/{id}/chat-session/{id}）

架構說明：每個 practice session 對應一題，包含 N 個 sub-questions，每個 sub-question 對應一個 chat session。用戶在「講解」(explanation) 和「作答」(qa) 模式間切換。

F-1. practice_session_start（Client-side）

注意：需防止頁面 re-render 重複觸發。question_title, category, teacher 等 metadata 不帶在事件上，可透過 question_id join 後端資料庫取得。

F-2. subtopic_complete（Server-side MP）

每小題只 fire 一次。這是練習漏斗的最小追蹤單位，可看到「做了幾題就放棄」的分佈。

F-4. chat_message_send（Server-side MP）

F-5. hint_request（Server-side MP）

AI 生成的提示（非靜態內容），由 Server 端 hint API 觸發。

G. 模考（/exam/{examSessionId}）

架構說明：模考與練習是獨立流程。從 PracticeSession 的「開始模考批改」進入，建立 exam session 後跳轉到模考頁面。提交後 AI 批改耗時 20-40 秒。

G-0. exam_page_view（Client-side）

用途：追蹤有多少用戶從練習進入模考。搭配 exam_answer_submit 可計算模考完成率。

G-1. exam_answer_submit（Client-side）

exam_mode 和 duration_seconds 為前端 UI 狀態。

H. 訂閱/付款流程

架構說明：

• 付款模式：選方案 + coupon → 選卡/綁卡 → 填寫帳單 → 送出付款
• 試用模式：試用邀請 → 選卡/綁卡 → 填寫帳單 → 送出
• 付款整合：TapPay（台灣），支援 3D Secure（全頁重定向）
• 發票：台灣電子發票（手機條碼/自然人憑證/愛心碼）

Trial vs Purchase 分離設計：Trial 開始為獨立的 trial_start 事件，不進 GA4 電商漏斗。purchase 事件只在真實付費時觸發（value > 0），避免 $0 trial 拉低 AOV。

Trial 生命週期：trial_start → trial_converted（轉為付費）或 trial_cancel（取消/未轉換）。不再有獨立的 expire 事件。

H-1. trial_start（Server-side MP）

H-2. trial_cancel（Server-side MP）

分析用途：days_remaining = 0 表示被動流失（試用到期未轉換），days_remaining > 0 表示主動取消。搭配 trial_converted 可計算 Trial-to-Paid 轉換率。

H-3. trial_converted（Server-side MP）

Trial 完整生命週期：

• trial_start → trial_converted + purchase — 試用轉付費
• trial_start → trial_cancel (days_remaining > 0) — 主動取消
• trial_start → trial_cancel (days_remaining = 0) — 到期未轉換

H-4. add_payment_info（Client-side）

GA4 items 陣列：GA4 電商報表需要 items 參數。由於本產品每次只購買一門課程，items 固定為 [{item_id: course_id, item_name: "課程名稱", quantity: 1}]，實作時自動帶入即可，不列為獨立參數。

H-5. begin_checkout（Client-side）

注意：begin_checkout 不帶 value 參數。GA4 會將帶 value + currency 的事件自動計入 Revenue，造成雙重計算。Revenue 只在 purchase 事件計算。

GA4 items 陣列：同 H-4，自動帶入 [{item_id: course_id, ...}]。

H-6. purchase（Server-side MP）

Trial 不觸發 purchase：Trial 走 trial_start（自訂事件），避免 $0 transaction 拉低 Average Order Value。

GA4 items 陣列：同 H-4，自動帶入 [{item_id: course_id, item_name: "課程名稱", price, quantity: 1}]。GA4 Monetization 報表需要此欄位才能顯示 Item-level 數據。

H-7. checkout_error（Client-side）

H-8. subscription_cancel（Server-side MP）

分析用途：days_remaining 可建構「取消時機分佈」。Day 1 取消 = 產品問題，接近續訂日取消 = 價格敏感。

H-9. subscription_expire（Server-side MP）

注意：此事件只在訂閱真正結束時觸發（未續訂）。成功續訂 = 再一次 purchase（帶 purchase_type: "renewal"），不觸發 subscription_expire。

付費訂閱完整生命週期：

• purchase → purchase (purchase_type: "renewal") → ... → 持續付費
• purchase → subscription_cancel → subscription_expire（churn）

I. 個人檔案（/user-profile）

I-0. profile_page_view（Client-side）

（無額外參數）

用途：追蹤個人檔案頁造訪量。搭配 profile_edit 可計算「查看 → 編輯」的比例，了解用戶對 profile 功能的使用程度。

I-1. profile_edit（Client-side）

I-2. logout（Client-side）

登出後清除 user_id（見 Section 2）。

6. 漏斗設計

設計原則

• 事件是原子化的、path-agnostic 的。不在事件名稱中編碼路徑資訊（例如不建 trial_then_purchase），只 fire purchase。路徑從事件序列重建。
• GA4 Funnel Exploration 支援 Open Funnel（用戶可從任意步驟進入），足以處理分支路徑。
• 複雜路徑分析走 BigQuery SQL（GA4 Explore 上限 10 步、segment 能力有限）。

典型用戶路徑

flowchart TD
    SS["sign_up_start"] --> SU["sign_up"]:::server
    SU --> EV["email_verify_complete"]

    EV -->|直接購買| PW["paywall_impression"]
    EV -->|先做題| PS["practice_session_start"]
    EV -->|試用| TI["trial_impression"]

    PS --> SC["subtopic_complete ×N"]:::server
    SC --> TI

    PW --> AP["add_payment_info（綁卡）"]
    TI --> AP

    AP -->|直接購買| BC["begin_checkout"]
    AP -->|免費試用| TS["trial_start"]:::server

    BC --> PU["purchase"]:::server

    TS --> TCONV["trial_converted"]:::server
    TS --> TC["trial_cancel"]:::server
    TCONV --> PU

    classDef server fill:#e8f5e9,stroke:#2e7d32

建議 GA4 Funnel 配置

7. 前置設定

GA4 Custom Dimensions 註冊清單

GA4 Free 上限：50 event-scoped custom dimensions + 50 custom metrics。

8. 截圖索引

9. 修訂記錄