概念位置

Beacon 跟一般 API 請求的差別在「不等回應」。發起者送出後就繼續做自己的事，不阻塞、不讀回應、不重試——這種模式叫 fire-and-forget。對流量統計這類「送到就好、漏一兩筆無所謂」的場景，fire-and-forget 讓回報完全不影響使用者體驗。beacon 送出的請求由接收端的 doPost 進入點接住處理。

可觀察訊號與例子

瀏覽器的 navigator.sendBeacon 是專為此設計的 API：它保證即使頁面正在關閉，請求也會在背景送完，而且預設用 text/plain 送出，這一點在打跨網域端點時關鍵——text/plain 屬於 simple request、不觸發 CORS preflight。

判讀方式

跨網域打 Apps Script 這類端點時，text/plain 是否夠用決定要不要處理 CORS preflight。實作細節見前端 beacon 與 CORS 障礙。

CORS preflight 為什麼會擋住 beacon

瀏覽器對跨網域的請求有一套安全機制。當網頁（你的 blog，網域 A）要送一個請求到另一個網域（Apps Script，網域 B），而這個請求「不夠單純」時，瀏覽器會先偷偷送一個 OPTIONS 請求去問網域 B：「我等一下要送這種請求，你允許嗎？」這個預先詢問叫 preflight。要等網域 B 回答允許，真正的請求才會送出。

Apps Script 在這裡有一個結構性的問題：它的 web app 無法回應 OPTIONS 請求。原因是 Apps Script 只有 doGet 和 doPost 兩個進入點，沒有 doOptions；preflight 送來的 OPTIONS 打不到你的程式，Apps Script 平台直接用預設方式回應，而那個回應不帶「我允許」的 CORS 標頭。於是 preflight 失敗、真正的請求根本沒送出。這就是「我照 API 教學寫了 fetch 打 Apps Script，瀏覽器 console 一片 CORS 紅字」的根本原因——問題不在你的程式，在於 preflight 發生在你的程式被執行之前，你沒有機會處理它。

避開的方法是讓請求「夠單純」，單純到瀏覽器判定不需要 preflight。這種請求叫 simple request，條件之一是 Content-Type 必須是 text/plain、application/x-www-form-urlencoded 或 multipart/form-data 其中之一。關鍵就在這：只要用 text/plain 送，就不會有 preflight，請求直接送達，Apps Script 的 doPost 正常收到。用 application/json 送則會觸發 preflight、然後失敗。

用 sendBeacon 送 text/plain

navigator.sendBeacon 是瀏覽器為「送出後就不管」這種場景設計的 API，正好適合流量 beacon。它有三個特性剛好對上需求：送出後不阻塞頁面、即使使用者馬上關頁面也保證在背景送完、而且它送出的 Content-Type 預設就是 text/plain（當你傳字串或 text 型別的 Blob 時）——自動滿足 simple request 條件，不觸發 preflight。

最小可用的 beacon 長這樣：

 1(function () {
 2  var ENDPOINT = "https://script.google.com/macros/s/你的部署ID/exec";
 3
 4  var payload = JSON.stringify({
 5    path: location.pathname,        // 哪一頁
 6    ref: document.referrer || "",   // 從哪裡連來的
 7    lang: navigator.language || "", // 瀏覽器語言
 8  });
 9
10  // 用 Blob 明確指定 text/plain，確保是 simple request
11  var blob = new Blob([payload], { type: "text/plain;charset=UTF-8" });
12  navigator.sendBeacon(ENDPOINT, blob);
13})();

送出的是一個 JSON 字串，但外層 Content-Type 是 text/plain——接收端再自己 JSON.parse 把字串還原成物件（模組二的接收端那半會做）。這是「內容是 JSON、但傳輸標成純文字」的常見手法，專門用來繞過 preflight。

payload 刻意只放不涉及個人身分的欄位：看了哪一頁、從哪連來、瀏覽器語言。不送任何能識別個人的資訊。附帶一提，Apps Script 的 web app 收不到訪客的 IP 位址，記不到也就無從外洩——這反而讓這套統計在隱私上乾淨很多，時間戳記交給接收端用伺服器時間補（模組二接收端那半處理）。

這幾個欄位描述的都是單次瀏覽的屬性，任兩列之間沒有關聯，因此算得出「某頁被打開幾次」、算不出「幾個人來過」。要補上那個能力需要額外的識別欄位，而「收不到 IP」這個事實在辨識自動化流量時會再次成為關鍵限制——兩者都在模組六處理。

加上閱讀裝置

閱讀裝置（讀者用手機、平板還是桌機看）是一個對排版決策有用的欄位：某篇長表格文章若行動裝置佔比高，就值得回頭檢查它在窄螢幕的可讀性。要在 payload 加這個欄位，關鍵是只送粗粒度的分類標籤、不送完整 userAgent——mobile / tablet / desktop 這種三選一的標籤足以回答「讀者用什麼裝置」，而完整 userAgent 帶著版本、系統等可組成指紋的細節，送它就破壞了前面刻意維持的不記 PII 立場。

分類邏輯在前端從 navigator.userAgent 判斷：

1function deviceType() {
2  var ua = navigator.userAgent;
3  // iPadOS 的 Safari 會把 userAgent 偽裝成 Mac，靠觸控點數補抓
4  var iPadAsMac = /Macintosh/.test(ua) && navigator.maxTouchPoints > 1;
5  if (/iPad|Tablet|PlayBook|Silk/.test(ua) || iPadAsMac || (/Android/.test(ua) && !/Mobile/.test(ua))) return "tablet";
6  if (/Mobi|iPhone|iPod|Android|BlackBerry|IEMobile|Opera Mini/.test(ua)) return "mobile";
7  return "desktop";
8}

有兩個判斷值得說明，因為它們是「照一般 userAgent 教學寫會分錯」的地方。Android 手機與平板的區分靠 Mobile 這個 token：Android 手機的 userAgent 含 Mobile、Android 平板不含，所以「有 Android 但沒有 Mobile」判為平板。iPad 會偽裝成 Mac：新版 iPadOS 的 Safari 為了要到桌面版網頁，把 userAgent 報成 Macintosh，單看字串會把 iPad 誤判成 desktop；靠 navigator.maxTouchPoints > 1（Mac 桌機沒有觸控）搭配 Macintosh 字樣才抓得回來。這類分類規則會隨瀏覽器演進而過時，所以只做粗分類、不追求精確到型號——粗分類容錯高，型號級的判斷維護成本高又容易錯。

把 dev 加進 payload：

1var payload = JSON.stringify({
2  path: location.pathname,
3  ref: document.referrer || "",
4  lang: navigator.language || "",
5  dev: deviceType(),   // mobile / tablet / desktop
6});

接收端多寫一欄就好（模組二接收端那半會補上 裝置 欄）。

放進 Hugo 的哪裡

這段 JS 要在每一頁都執行，所以放進網站的共用版型、而不是單篇文章。Hugo 的慣例是做一個 partial，在關閉 </body> 前引入：

 1<!-- layouts/partials/beacon.html -->
 2<script>
 3  (function () {
 4    var ENDPOINT = "https://script.google.com/macros/s/你的部署ID/exec";
 5    function deviceType() {
 6      var ua = navigator.userAgent;
 7      var iPadAsMac = /Macintosh/.test(ua) && navigator.maxTouchPoints > 1;
 8      if (/iPad|Tablet|PlayBook|Silk/.test(ua) || iPadAsMac || (/Android/.test(ua) && !/Mobile/.test(ua))) return "tablet";
 9      if (/Mobi|iPhone|iPod|Android|BlackBerry|IEMobile|Opera Mini/.test(ua)) return "mobile";
10      return "desktop";
11    }
12    var payload = JSON.stringify({
13      path: location.pathname,
14      ref: document.referrer || "",
15      lang: navigator.language || "",
16      dev: deviceType(),
17    });
18    var blob = new Blob([payload], { type: "text/plain;charset=UTF-8" });
19    navigator.sendBeacon(ENDPOINT, blob);
20  })();
21</script>

然後在 baseof 版型的結尾引入它：

1<!-- layouts/_default/baseof.html，在 </body> 前 -->
2{{ partial "beacon.html" . }}

放在 </body> 前、而不是 <head> 裡，是為了讓 beacon 在頁面主要內容都載入後才送，不跟關鍵資源搶頻寬。sendBeacon 本身就不阻塞，這個位置只是讓它更晚一點、更不影響體驗。

一個上線前要注意的邊界：本機 hugo server 預覽時 beacon 也會照送，會把開發時的瀏覽混進統計。實務上會加一個判斷，只在正式網域才送——例如檢查 location.hostname 是不是正式網域，是才執行。這個 hostname guard 擋掉本機預覽；「在正式站上自己重整」則需要另一套機制，見訪客識別與 opt-out。防濫用與資料乾淨度的整體討論在模組五。

下一步

前端會送了，但現在 beacon 送出去還沒有人接。接收端要怎麼解析這個 text/plain 的 JSON、怎麼安全寫進 Sheet、部署後怎麼確認收到第一筆——見接收端 handler：寫進第一筆。想先補齊 doPost 跟部署模型的背景，回模組一：Apps Script 地基。資料開始累積之後怎麼讀出意義，見模組六：收到資料之後。

補上這個能力需要第二則事件，而第二則事件的設計比第一則複雜：載入的時機明確且必定發生，離開的時機則有多種可能，且不保證每次都能送出。

進入與離開拆成兩則事件

模型是每次瀏覽產生兩列：進入事件在頁面載入時送出，離開事件在頁面不再可見時送出，兩列靠 session 識別碼與路徑配對起來。

 1// send()：把物件轉成 JSON 字串、用 navigator.sendBeacon 送出（模組二建立）
 2// deviceType()：回傳 mobile / tablet / desktop（模組二建立）
 3// visitorId / sessionId：兩層隨機識別碼（見〈訪客識別與 opt-out〉）
 4var base = { path: location.pathname, lang: navigator.language, dev: deviceType(),
 5             vid: visitorId, sid: sessionId };
 6
 7// 進入：載入時立刻送，帶來源網址
 8send(Object.assign({ t: "view", ref: document.referrer || "" }, base));
 9
10// 離開：帶停留秒數與是否互動過
11var arrivedAt = Date.now();
12var interacted = false;
13var leaveSent = false;
14
15["scroll", "pointerdown", "keydown"].forEach(function (evt) {
16  addEventListener(evt, function () { interacted = true; }, { once: true, passive: true });
17});
18
19function sendLeave() {
20  if (leaveSent) return;
21  leaveSent = true;
22  send(Object.assign({
23    t: "leave",
24    dur: Math.round((Date.now() - arrivedAt) / 1000),
25    act: interacted ? 1 : 0
26  }, base));
27}

拆成兩列而不是合併成一列，是為了讓兩件事各自失敗。 合併的設計會是「等到離開時才送一列，裡面同時放路徑與停留時間」——它看起來省一半的列數，代價是離開事件送不出去時，這次瀏覽在資料裡完全不存在。而離開事件送不出去是會實際發生的，至少有這些途徑：行動裝置被系統回收記憶體、瀏覽器被強制關閉、裝置斷電、網路在切換基地台時中斷、廣告或隱私擴充功能攔截這個請求、以及接收端在流量尖峰撞到併發上限而拒絕。拆開之後，最壞的結果只損失品質欄位，計數的基準線不受影響。

這份丟失清單在後面還有一個用途。辨識自動化流量會用「沒有離開事件」當作機器的候選訊號，而上面每一條途徑都會讓真人產生同樣的形態——行動流量佔比高的站尤其明顯。判讀那個訊號時要一併想起這一段。

這個取捨的另一面是列數翻倍。試算表容量的影響見模組三的資料模型與容量邊界，執行配額（併發上限與觸發器時間）的影響見模組五的配額碰撞。個人網站的量體下這個代價可以接受；量體大到需要壓縮時，正確的方向是在接收端合併而不是在前端少送——前端少送會讓資料從一開始就不存在。

用 visibilitychange 觸發離開事件

離開事件的觸發時機有三個候選，可靠度差距很大。

beforeunload 不適用。 行動版 Safari 不支援它，所以 iOS 上的所有瀏覽器都不會觸發；而在 Firefox，註冊這個監聽器會讓頁面失去進入 bfcache 的資格——那是瀏覽器把整個頁面狀態留在記憶體裡、讓上一頁 / 下一頁能瞬間還原的機制，失去資格代表讀者按返回時要重新載入——為了統計而拖慢讀者的返回操作，取捨方向是錯的。各家瀏覽器一致排除出 bfcache 的其實是 unload，現代瀏覽器的 beforeunload 本身已不影響 bfcache，但 Firefox 這個例外加上行動端完全不支援，已經足以讓它出局。

pagehide 涵蓋頁面卸載與進入快取兩種時機（event.persisted 可區分兩者），比 beforeunload 可靠，但漏掉「切換到別的分頁或別的 app」這個最常見的離開方式。

visibilitychange 進入 hidden 狀態涵蓋範圍最廣：切換分頁、導覽到新頁、切換 app、行動裝置鎖定螢幕、最小化或關閉瀏覽器都會走到。規格把「轉為 hidden」描述成頁面最後一個能可靠觀察到的事件。兩者都註冊、靠旗標防止重複送出：

1addEventListener("visibilitychange", function () {
2  if (document.visibilityState === "hidden") sendLeave();
3});
4addEventListener("pagehide", sendLeave);

sendLeave 開頭那個 leaveSent 旗標在這裡是必要的而非防禦性的——一次真實的離開通常會同時觸發這兩個事件。

它帶來一個容易漏掉的交互作用：頁面進入 bfcache 時 JS 狀態整個保留下來，讀者按返回還原頁面之後，leaveSent 仍然是 true、arrivedAt 仍然停在上一次載入的時刻。不處理的話，這次閱讀不會產生任何記錄，而在快取裡待的那段時間會被算進上一筆的停留秒數。修法是監聽 pageshow，在 event.persisted 為真時把三個狀態變數重置並補送一則進入事件：

1addEventListener("pageshow", function (evt) {
2  if (!evt.persisted) return;          // 一般載入不需要處理
3  leaveSent = false;
4  interacted = false;
5  arrivedAt = Date.now();
6  send(Object.assign({ t: "view", ref: document.referrer || "" }, base));
7});

送出方式是 navigator.sendBeacon（見beacon 知識卡），它的設計目標正是這個場景：頁面正在關閉時，一般的請求會隨著頁面銷毀而被取消，而 sendBeacon 把資料排進瀏覽器的傳送佇列、不阻擋頁面卸載。

它保證的是「不延遲卸載」而非「一定送達」——排進佇列之後的傳送結果不會回報，行動裝置被切走或強制關閉時仍可能沒送出去。同步能得知的只有排隊本身成不成功：佇列有 64 KiB 的上限，超過或排隊失敗時回傳 false。流量事件的 payload 遠小於這個上限，但要監控收集鏈健康度時，這個回傳值是唯一在瀏覽器端可見的失敗訊號。

停留秒數對應的是可見時長

這個欄位的語意需要精確界定，否則會被當成閱讀時長使用而得出錯誤結論。它量的是「頁面從載入到不再可見之間經過的時間」，這與讀者實際花在這篇文章上的時間有系統性的差距。

差距來自兩個方向。切換到別的分頁去查資料再切回來，會被切成多段——第一段在切走時就結束了，切回來不會產生新的進入事件（頁面沒有重新載入），所以回來之後的閱讀時間完全沒有被記錄。反過來，開著分頁去做別的事，如果沒有切換到其他分頁（例如直接離開電腦），這段時間會全部算進停留秒數。

站內導覽時還有一個可以驗證的現象：離開事件與下一頁進入事件的時間戳落在同一兩秒內，因為舊頁進入 hidden 與新頁開始載入是同一個動作的兩面。時間戳由接收端在寫入時補上，所以這個間隔還包含網路傳輸與接收端排隊，不是純粹的瀏覽器事件間隔。用它重建連續的閱讀路徑時，配對條件要留這個寬容範圍。

這個欄位因此適合分辨量級、不適合精確比較，而分界由誤差來源決定：中途切換到別的分頁會讓後半段完全不計，所以量測誤差可以達到一次分頁切換的完整時長——查一個名詞、回一則訊息都是數十秒的量級。比較的粒度要大於這個誤差，否則差異可能全部來自切換行為而非閱讀。分桶而不是比大小，是這個限制下唯一穩健的用法。

互動旗標

act 記錄的是「這次瀏覽期間有沒有發生過捲動、點擊或按鍵」。它用 { once: true } 註冊，第一次觸發後就移除監聽器——需要的資訊只是「有沒有發生過」，不是次數，持續監聽只會增加沒有用途的執行成本。

passive: true 這個選項對捲動事件是必要的：它向瀏覽器宣告這個監聽器不會取消預設行為，讓捲動不必等待 JS 執行完成。統計程式碼不該是頁面捲動卡頓的來源。

這個旗標的判讀價值在於它與停留秒數的組合。停留六秒且沒有任何互動，與停留六秒且捲動過，是兩種完全不同的閱讀行為——前者是頁面被打開然後放著，後者是有人真的在看。單獨看秒數分不出這兩者。

資料模型變更會讓既有的報表公式換語意

這個變更有一個容易被漏掉的下游影響：在單事件模型下寫的統計公式，在雙事件模型下仍然合法執行，但回答的已經不是同一個問題。

具體的例子是判斷「這次 session 只看了一頁」。單事件模型下，這等價於「同一個 session 識別碼只出現一次」：

1COUNTIFS(session欄, 當列session) = 1

改成雙事件之後，每次瀏覽至少產生兩列，這個條件從此永遠不成立。公式沒有報錯、沒有回傳錯誤值，只是那個分類的計數變成恆為零——而零看起來就像「沒有這種流量」。正確的寫法要把事件型別納入條件：

1COUNTIFS(session欄, 當列session, 事件欄, "view") = 1

同一個影響也及於模組四的每日彙總：那段 group by 對每一列加一，在單事件模型下等於數瀏覽次數，改成雙事件之後多數瀏覽會被數兩次。倍率不是固定的二——離開事件本來就會丟失一部分，實際倍率落在一與二之間、且隨行動裝置佔比浮動。這正是這類失效難察覺的原因：固定倍數還有機會被看出來，浮動的比例只會讓數字「看起來變多了」。修法是在迴圈裡先篩掉非進入事件，模組四的程式碼旁已標明這個前提。

因此資料模型的變更範圍必須包含下游的分析邏輯，把公式與彙總程式的重算當成同一次變更的一部分，而不是之後再說。延後處理會失去對照：之後回頭看時，看到的數字已經是新邏輯算出來的，沒有東西可以比對。這類失效的完整判讀方法見假故障與靜默失效的診斷，抽象層的原則見 #250 資料多出一種形狀時，既有分析邏輯靜默換語意。

下一步

事件模型完成後，資料裡有了停留時間與互動訊號。這兩個欄位除了描述閱讀行為，也比環境屬性難偽裝，因此是分辨真人與機器的主要依據——前提是先知道它們在真人身上也會缺席。怎麼組合它們與其他訊號、以及怎麼量出自己站上的真人基線，見辨識自動化流量。

實作拆成兩半，剛好對應架構的兩端。前端這半的重點是用對送出方式，避開靜態站打 Apps Script 最常見的 CORS 障礙。接收端這半的重點是把請求解析出來、安全地 append 進試算表。

章節文章

跨分類引用

• → 模組一：Apps Script 地基：doGet/doPost 與部署模型的完整說明
• → 模組三：Sheets 當資料庫：資料進來後的並發、資料模型與容量
• → 模組六：收到資料之後：這裡的 payload 只描述單次瀏覽，補上訪客識別、停留時間與自動化訊號之後才讀得出「幾個人來過、有沒有真的在讀」