開發者文件

用幾行程式，記下你在意的動作

瀏覽、點擊和表單送出會自動記錄。想記更多，可以在前台用 JavaScript、在伺服器端用 PHP 送出自訂事件，都會接到同一位訪客的動線上。

快速開始

外掛啟用後，前台每一頁都會自動載入記錄腳本，不用貼任何追蹤碼。下面這些不用寫程式就會記：

瀏覽的頁面、停留時間和捲動深度
點 LINE、電話、Email 連結
點外部連結、下載檔案
按下表單送出（只記按下送出，不記輸入的內容）
WooCommerce 訂單與營收，退款、取消會自動扣回

管理員、編輯、作者這些站內角色預設不記，測試時請用無痕視窗。

前台 JavaScript

用 moa() 送出自訂事件：

複製程式碼

// 記一個自訂事件
moa('event', '下載型錄');

// 記成轉換，並帶上目標價值
moa('event', '預約成功', {
  conversion: true,
  value: 1200,
  detail: '台北店'
});

參數說明

名稱第二個參數，報表上顯示的事件名稱

conversion 設成 true 就算一次轉換

value 目標價值。前台送的金額不算營收，上限 1,000,000

detail 補充說明，例如分店、方案名稱

記錄腳本是延遲載入的。如果頁面一開始就要呼叫，先放下面兩行，呼叫會先排隊，等腳本載入後一起送出：

複製程式碼

window.moa = window.moa || function () { moa.q.push(arguments); };
moa.q = moa.q || [];

設定裡開了「需要訪客同意才記錄」的話，在 Cookie 橫幅按下同意後呼叫 moa('consent')，之後才會開始記。同意會記住一年。

自己的手機或電腦不想被記，在網址後面加 ?moa_ignore=1；要恢復就加 ?moa_ignore=0。

HTML 屬性

不想寫 JavaScript，也可以直接在按鈕或連結加屬性：

複製程式碼

<a href="/pricing/" data-moa-event="看方案">看方案</a>

<button data-moa-event="索取報價" data-moa-conversion data-moa-value="500">索取報價</button>

<form data-moa-form="預約表單"> … </form>

屬性說明

data-moa-event 點下去就記一筆事件，值是事件名稱

data-moa-conversion 加上就算轉換，不用填值

data-moa-value 目標價值

data-moa-form 表單在報表上的名稱。沒填就用表單的 aria-label、name 或 id

伺服器端 PHP

表單寫進資料庫、會員註冊、訂單成立這類在伺服器上發生的事，用 moa_track() 記錄。在訪客自己的請求裡呼叫時，會從 Cookie 認出是誰，事件直接接到他的動線上。

複製程式碼

// 會員註冊完成
add_action('user_register', function ($user_id) {
  moa_track('signup', [
    'name'       => '會員註冊',
    'conversion' => true,
    'user_id'    => $user_id,
  ]);
});

記成功會回傳事件編號，沒記到回傳 0，例如訪客沒同意 Cookie，或同一個 unique 已經記過。

外掛停用時不想讓網站出錯，改用 action 呼叫，外掛不在就什麼都不做：

複製程式碼

do_action('moa_track', 'signup', ['name' => '會員註冊', 'conversion' => true]);

事件參數

moa_track($type, $args) 的第一個參數是事件類型，只留英文小寫、數字和底線，最多 24 個字元。第二個參數可以帶：

參數說明

name 報表上顯示的名稱，最多 120 字

detail 補充說明，最多 191 字

value 金額或目標價值

revenue 設成 true 時，value 算進營收（要同時是轉換）

currency 三碼幣別，例如 TWD

conversion 設成 true 就算一次轉換

ref_id 你系統裡的編號（整數），例如訂單編號

unique 不重複鍵，最多 64 字。同一個值只記一次

path 事件發生的頁面路徑，沒給就用目前的網址

props 自訂欄位（陣列），存成 JSON

user_id 會員編號，沒給就用登入中的會員

vid / sid 指定訪客與造訪編號，一般用不到

force 設成 true 時，認不出訪客或沒同意 Cookie 也照樣記，但不會接到動線上

掛勾與篩選器

每記一筆事件之後會觸發 twa_event_recorded，參數是事件編號、類型和原本傳入的參數。下面這些篩選器可以調整外掛的行為：

篩選器用途

moa_session_event_limit 每次造訪最多記幾筆事件，預設 300

moa_max_event_value 前台送來的目標價值上限，預設 1,000,000

moa_rate_limit 同一個 IP 每 10 分鐘最多送幾次

moa_allowed_hosts 允許送資料進來的網域，多網域或子網域時加上

moa_trusted_proxies 信任的反向代理 IP，可以寫 CIDR

moa_client_ip 改寫判斷出來的訪客 IP

moa_paid_statuses 算進營收的訂單狀態，預設 processing、completed

moa_void_statuses 要扣回營收的訂單狀態，預設 cancelled、refunded、failed、trash

moa_order_base_amount 多幣別訂單換算回主幣別的金額

moa_currency_format 報表上金額的顯示格式，預設 NT$

moa_report_cache_ttl 報表快取的秒數

複製程式碼

// 每次造訪最多記 500 筆事件
add_filter('moa_session_event_limit', function () {
  return 500;
});

整合範例

WooCommerce 和常見的表單外掛已經內建串接，不用寫程式，清單在整合頁。自己寫的預約或報名系統，可以這樣接：

複製程式碼

// 預約成立時（my_booking_created 換成你系統的 hook）
add_action('my_booking_created', function ($booking_id, $booking) {
  moa_track('booking', [
    'name'       => '線上預約',
    'conversion' => true,
    'value'      => $booking['price'],
    'revenue'    => true,
    'ref_id'     => $booking_id,
    'unique'     => 'booking-' . $booking_id,
  ]);
}, 10, 2);

金流的付款通知是金流主機發過來的，不是訪客的瀏覽器，認不出訪客。這時加上 force，營收照樣算進報表：

複製程式碼

moa_track('payment', [
  'name'       => '付款完成',
  'conversion' => true,
  'value'      => $amount,
  'revenue'    => true,
  'ref_id'     => $order_id,
  'unique'     => 'pay-' . $order_id,
  'force'      => true,
]);

安全與驗證

只收自己網域送來的資料，別的網站送不進來。
排除爬蟲、自動化工具和預覽抓取，訪客真的有動作或停留 8 秒才算一次瀏覽。
擋下資料中心 IP，同一個 IP 短時間送太多也會擋。
前台送的金額有上限，每次造訪的事件數也有上限，假資料灌不爆報表。
表單只記按下送出，不記任何輸入內容。IP 預設遮掉最後一段再存。
記錄出錯只會回傳 0，不會讓結帳或表單送出跟著壞掉。

建議做法

1
重要的動作放伺服器端記。表單寫進資料庫、訂單成立、付款完成用 PHP，不受訪客的廣告阻擋外掛影響。
2
一定要記準的事件給 unique，例如用訂單編號當值。重新整理或通知重送，都只算一次。
3
事件類型用固定的英文代號，顯示的中文名稱放 name，報表才分得清楚。
4
營收只在伺服器端記。前台送的 value 只算目標價值。
5
寫在佈景或其他外掛裡的呼叫，用 do_action，外掛停用時網站不會出錯。

疑難排解

1
確認自己沒被排除：用無痕視窗、不登入，網址加 ?moa_ignore=0 再試一次。
2
記下發生的時間、網址，並截圖。同樣步驟再做一次，確認每次都會發生。
3
打開 WordPress 的除錯紀錄，在 wp-config.php 加上下面三行，再到 /wp-content/debug.log 找「Mo Analytics:」開頭的訊息。

複製程式碼

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);

4
有快取外掛或 CDN 的話先清一次快取。LiteSpeed Cache 和 WP Rocket 已經自動把記錄腳本排除在合併之外。
5
還是找不到原因，寫信給我們，附上時間（含時區）、網址、截圖和 debug.log 裡相關的幾行。