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 地基。資料開始累積之後怎麼讀出意義，見模組六：收到資料之後。

準備一張 Sheet 當儲存體

先在 Google Sheets 建一張新試算表，命名例如 blog-analytics。第一列放欄位標題，對應接收端要寫的欄位：時間、路徑、來源、語言、裝置。這一列標題只是給人看的，接收端從第二列開始 append 資料。

Apps Script 有兩種綁定方式，這裡用容器綁定：直接在這張試算表的選單開 擴充功能 → Apps Script，開出來的 script 專案天生就跟這張試算表綁在一起，程式裡用 SpreadsheetApp.getActiveSpreadsheet() 就能拿到它，不必記試算表 ID。兩種綁定方式的差異、以及什麼時候該用獨立專案，見模組一：Apps Script 地基。

寫 doPost 接住 beacon

前端用 sendBeacon 送 POST，所以接收端要實作 doPost。sendBeacon 送來的內容放在 e.postData.contents，是一個 JSON 字串（前端刻意用 text/plain 傳輸、內容仍是 JSON），接收端 JSON.parse 把它還原：

 1function doPost(e) {
 2  try {
 3    var data = JSON.parse(e.postData.contents);
 4
 5    var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName("工作表1");
 6    sheet.appendRow([
 7      new Date(),          // 時間：用伺服器時間，不信任前端傳的時間
 8      data.path || "",     // 路徑
 9      data.ref || "",      // 來源
10      data.lang || "",     // 語言
11      data.dev || "",      // 裝置：mobile / tablet / desktop
12    ]);
13
14    return ContentService
15      .createTextOutput(JSON.stringify({ ok: true }))
16      .setMimeType(ContentService.MimeType.JSON);
17  } catch (err) {
18    return ContentService
19      .createTextOutput(JSON.stringify({ ok: false, error: String(err) }))
20      .setMimeType(ContentService.MimeType.JSON);
21  }
22}

三個實作決定值得說明：

時間用伺服器的 new Date()，不用前端傳的時間。 前端時間來自使用者的裝置，時區、時鐘準不準都不可控，還多一個可被偽造的欄位。接收端執行的當下時間就是最接近真實的瀏覽時間，用它最乾淨。這也是前端 payload 不需要送時間戳的原因。

每個欄位都用 || "" 給預設值。 beacon 有可能因為前端狀況送來缺欄位的資料，data.path 若是 undefined，直接寫進 Sheet 會是空格但不會報錯；用 || "" 明確寫成空字串，讓資料形狀一致，之後彙總不會踩到 undefined。

整段包在 try/catch 裡。 接收端可能收到格式壞掉的請求（爬蟲亂打、payload 不是合法 JSON）。JSON.parse 遇到壞資料會丟例外，沒接住的話這次執行算失敗、也可能讓錯誤累積。包起來後，壞請求就回一個 ok: false、不影響服務。真正在意這些壞請求要不要防、怎麼防，見模組五。

回應用 ContentService.createTextOutput 回一小段 JSON。sendBeacon 是 fire-and-forget、前端根本不會讀這個回應，所以回什麼不重要——但 doPost 必須回一個 ContentService 的輸出，這是 Apps Script web app 的硬性要求，不回會被當成執行沒有正常結束。

部署成 web app

程式寫好還打不通，因為它還沒有對外網址。在 Apps Script 編輯器右上角 部署 → 新增部署作業，類型選 網頁應用程式，兩個設定要對：

• 執行身分（Execute as）：選「我」。beacon 是匿名訪客送來的，他們沒有你試算表的權限；選「我」讓這段程式用你的身分執行，才寫得進你的 Sheet。
• 誰可存取（Who has access）：選「所有人」。訪客是沒登入 Google 的匿名瀏覽器，只有「所有人」這個選項能讓匿名 beacon 打得進來。

部署後會拿到一個網址，形如 https://script.google.com/macros/s/AKfyc.../exec。把這個網址填回前端 beacon 的 ENDPOINT（見前端那半）。這兩個設定的安全含義——「所有人可存取」會不會被濫用、要不要加保護——在模組五完整討論；先讓它通，才有東西可以保護。

確認收到第一筆

部署完、前端網址也填好後，打開你的 blog 任一頁（正式網域，不是本機預覽），beacon 就會送出。回到 Google Sheet，第二列應該出現一筆：伺服器時間、你剛看的路徑、來源、語言。看到這一列，整條 client beacon 管線就打通了——前端偵測、跨網域送達、接收端解析、寫進儲存體，每一環都在運作。

如果沒出現，最常見的兩個原因：一是前端 ENDPOINT 填成舊的部署網址（每次「新增部署作業」網址會變，改程式後要用「管理部署作業」更新同一個部署、網址才不變），二是部署的存取權限沒設成「所有人」導致匿名 beacon 被擋。這兩個都是設定問題，不是程式問題。

下一步

第一筆進來了，往下有兩條路。

想知道這些資料怎麼讀出意義——來源網址為什麼大量空白、怎麼判斷兩列是不是同一個人、哪些是機器抓取——走模組六：收到資料之後。那一章會在 payload 上增加欄位，屆時這裡的 appendRow 與試算表的表頭要跟著改，改法在該章的欄位變更清單。

想先把儲存層打穩——多個瀏覽在同一瞬間打進來時 appendRow 會不會互相覆蓋、資料列累積到幾萬列時 Sheets 還撐不撐得住——走模組三：Sheets 當資料庫。