自訂 Captive Portal：HTML 與 CSS 指南

執行摘要

對於企業場地 — 從奢華酒店 Hospitality 和連鎖零售商 Retail 到交通樞紐 Transport 和現代醫療園區 Healthcare — 訪客 WiFi 登入頁面是數位門面。然而，超過 90% 的訪客 WiFi 登入發生在行動裝置上，其渲染並非由 Safari 或 Chrome 等標準瀏覽器控制，而是由高度受限的 Captive Network Assistant (CNA) webview 控制 [1]。這些「微型瀏覽器」執行嚴格的沙箱限制：它們封鎖外部 CDN、停用持久性 Cookie、忽略外部網路字型，並嚴格限制 JavaScript 執行，以降低安全風險並防止工作階段綁架 [2]。

當開發人員使用傳統網頁標準設計登入頁面時，這些限制會導致版面配置破裂、品牌資產遺失以及登入按鈕失效，直接影響客戶滿意度和數位互動。本指南提供了這些挑戰的解決方案，介紹了防禦性編碼實踐 — 例如內聯 CSS、Base64 資產編碼、系統字型堆疊以及明確的導覽驅動驗證交握 — 以確保無縫的跨平台渲染。此外，我們還探討了利用像 Purple 的 portal 產生器這樣的託管解決方案，如何讓開發人員在保持完整的 HTML/CSS 創意控制的同時，卸載 RADIUS 驗證、資料庫擴充、GDPR/PCI 合規性以及多廠商 AP 整合 [3]。

技術深挖

要建置具有彈性的自訂 Captive Portal，開發人員必須了解當訪客與開放式服務設定識別碼 (SSID) 建立關聯時發生的網路層級攔截和瀏覽器虛擬化。

Captive Portal 生命週期

當用戶端裝置與 captive SSID 建立關聯時，會觸發以下順序：

1. IP 關聯：裝置完成 3 向交握並透過 DHCP 請求 IP 位址。
2. 主動連線能力探測：作業系統的背景網路管理員立即向專用的廠商中立 canary URL（例如 Apple 的 http://captive.apple.com/hotspot-detect.html 或 Google 的 http://connectivitycheck.gstatic.com/generate_204）傳送 HTTP GET 請求 [1]。
3. DNS/HTTP 攔截：本地無線區域網路控制器 (WLC) 或存取點 (AP) 攔截此 port 80 HTTP 請求。閘道器不會回傳預期的 HTTP 200 或 204 狀態，而是透過 HTTP 302 重新導向將用戶端的流量重新導向到 Captive Portal 的登入頁面 URL [2]。
4. Webview 產生：偵測到重新導向後，作業系統會產生其原生的 Captive Network Assistant (CNA) 微型瀏覽器以顯示重新導向的登入頁面，從而無需使用者手動開啟完整瀏覽器。
5. 驗證與狀態轉換：使用者完成登入表單，將憑證提交回 portal 伺服器，該伺服器指示閘道器（通常透過 RADIUS Access-Accept 或外部 API 呼叫）授權 MAC 位址。
6. CNA 退出交握：CNA 微型瀏覽器向其 canary URL 執行另一個 HTTP GET。如果收到預期的 200/204 回應，它會將右上角的按鈕從「取消」變更為「完成」，並將 WiFi 連線確立為主要網路介面。

平台專屬的微型瀏覽器限制

每個作業系統在不同的 webview 環境中處理此生命週期，導致高度碎片化的行為。下表詳細說明了這些關鍵限制：

避開 Apple CNA「完成」按鈕陷阱的編碼方法

自訂 portal 開發中最常見的失敗模式之一是 iOS 裝置上的 「完成」按鈕陷阱。當使用者進行驗證時，iOS Websheet webview 必須偵測到網路不再處於 captive 狀態。它透過監控其背景 canary 請求的成功與否來做到這一點。

至關重要的是，iOS CNA 僅在全頁 HTTP 導覽（位置重新導向）時才會觸發此檢查。如果開發人員建置了一個現代單頁應用程式 (SPA)，該程式透過非同步 AJAX 呼叫（例如 fetch() 或 Axios）提交表單資料並動態更新 DOM 而不變更 URL，則 CNA 將 永遠不會 重新執行其連線能力檢查。使用者將在閘道器層級完成驗證，但右上角的 CNA 按鈕仍將保持為「取消」。如果感到沮喪的使用者按一下「取消」，iOS 裝置將立即中斷連線與 SSID 中斷連線，並終止 WiFi 工作階段 [1]。

為了防止這種情況，驗證成功處理常式 必須 執行整頁重新導向至實際的到達網頁（例如 window.location.href = '/success'），或透過標準 HTTP POST 動作原生提交登入表單。

實作指南

為了確保在所有平台上呈現一致，開發人員必須從現代、高度依賴外部資源的網頁設計，轉變為高度獨立、防禦性的編碼風格。

黃金法則：針對零網路連線進行設計

在 captive 狀態下，用戶端裝置無法存取外部網際網路。它只能解析並存取無線控制器 Walled Garden（圍牆花園）中明確列入白名單的 IP 位址和網域（例如 Captive Portal 伺服器本身的 IP）。因此，HTML 中參照的任何外部資源都將無法載入，從而導致版面配置損壞。

為了進行防禦性設計，請實作以下行動優先 Captive Portal 設計檢查清單：

1. 檢視區（Viewport）設定

為了防止行動裝置將檢視區縮小到桌上型電腦的寬度（通常為 980px），HTML `` 必須包含回應式檢視區 meta 標記。如果沒有此標記，文字和輸入欄位在行動裝置上會顯得極其微小：

2. 內聯 CSS 並移除外部依賴項

切勿連結到外部 CSS 檔案或 CDN（例如 Bootstrap、Tailwind 或 Google Fonts）。所有 CSS 必須內嵌在 HTML `` 的 `

<div class="portal-card">
    <div class="logo-container">
        
        
            
            您的品牌
        
    </div>
    
    <h1>歡迎使用訪客 WiFi</h1>
    <p>請在下方輸入您的資訊，以取得安全、高速的網路連線。</p>
    
    
    
        <div class="form-group">
            姓名
            
        </div>
        
        <div class="form-group">
            電子郵件地址
            
        </div>
        
        <div class="consent-group">
            
            
                我同意 <a href="#">服務條款</a> ，並同意依據 GDPR 規範進行資料處理。
            
        </div>
        
        <div id="terms_box" class="terms-scrollbox">
            <strong>WiFi 服務條款：</strong><br />
            1. 本服務依現狀提供，不提供任何明示或默示之保證。<br />
            2. 使用者不得從事非法或佔用大量頻寬的活動。<br />
            3. 個人資料之收集僅用於身分驗證與行銷訂閱，並符合我們的隱私權政策。
        </div>
        
        連線至 WiFi
    
    
    <div class="footer">
        由 Purple 提供技術支援 | 安全訪客 WiFi
    </div>
</div>

## 疑難排解與風險緩釋

部署自訂編碼的 HTML/CSS Captive Portal 時，IT 營運團隊經常會遇到幾項嚴重的營運風險：

### 1. SSL/TLS 憑證警告迴圈

由於 Captive Portal 的運作原理是攔截流量，因此它們與現代 HTTPS 網路安全存在根本性的衝突。當使用者嘗試造訪 HTTPS 網站（例如 `https://www.google.com`），而閘道器嘗試將該流量重新導向至 HTTP Captive Portal 時，瀏覽器會偵測到 SSL 憑證不符，並顯示嚴重的「您的連線不是安全連線」安全警告。

* **緩釋措施**：切勿嘗試直接攔截 HTTPS 流量。完全依賴作業系統原生的 CNA 輔助程式（它會發送未加密的 HTTP 請求以觸發重新導向）。確保您的 Captive Portal 網域擁有有效且受公開信任的 SSL 憑證（例如 Let's Encrypt 或 DigiCert），並且*僅在*初始 HTTP 重新導向成功將使用者引導至您的 Portal 網域後，才透過 HTTPS 提供服務 [2]。

### 2. DNS 解析失敗（圍牆花園陷阱）

如果您的自訂 HTML 頁面引用了外部資源（例如 Facebook、Google 等社群登入 OAuth 端點或付款閘道），除非已在無線控制器的 Walled Garden 中明確將這些網域列入白名單，否則這些網域的 DNS 請求將會失敗。如果白名單中遺漏了某個網域，登入流程將會停滯，並顯示空白畫面。

* **緩釋措施**：維持嚴格且最小化的 Walled Garden 清單。如果使用社群登入，請將身分驗證提供商建議的特定萬用字元網域（例如 `*.google.com`、`*.gstatic.com`）列入白名單。

### 3. 工作階段逾時與 MAC 詐騙漏洞

標準的 Captive Portal 是根據裝置的 MAC 位址進行驗證。然而，現代行動作業系統（iOS 14+ 和 Android 10+）預設使用隨機 MAC 位址（專用 WiFi 位址），並定期輪替。這可能會導致訪客被反覆要求重新驗證，從而破壞使用者體驗 [1]。

* **緩釋措施**：在 RADIUS 伺服器上設定合理的工作階段逾時（例如 24 小時）以防止過期工作階段，並利用 **Passpoint (Hotspot 2.0)** 或 **WPA3-Enterprise** 等現代驗證標準，實現無縫、安全的上網體驗，完全繞過基於 MAC 的 Captive Portal。

## Purple 產品關聯性：自建還是購買

雖然編寫單個 HTML 頁面非常簡單，但託管、保護和擴充自訂 Captive Portal 基礎架構卻面臨著巨大的技術和合規障礙。下表比較了自行託管自訂 Portal 與使用 Purple 的託管企業平台在工程和營運方面的實際情況：

| 功能 / 營運需求 | 自行託管的自訂 Portal | Purple 企業級 WiFi 平台 |
| :--- | :--- | :--- |
| **HTML/CSS 自訂** | 完全手動編碼，將檔案上傳到個別 AP 或本機網頁伺服器。 | **像素級精準的開發人員編輯器**，支援自訂 HTML/CSS 嵌入，並結合拖放式視覺化建構工具。
| **RADIUS 基礎架構** | 必須部署、設定和維護高可用性的 FreeRADIUS 或 Cloud RADIUS 伺服器 [4]。 | **內建、全球分佈的雲端原生 RADIUS**，具備雙活（Active-Active）備援和 99.99% 的可用性 SLA。
| **多廠商 AP 支援** | 每個硬體廠商（Cisco、Aruba、Meraki、Ruckus）都需要自訂整合指令碼 [5]。 | **原生、開箱即用的整合**，支援超過 200 種硬體型號；在混合硬體資產中實現統一的 Portal 部署。
| **資料隱私與合規性** | 場所需承擔 GDPR、CCPA 和 PCI DSS 合規性的 100% 法律責任，包括安全的資料庫加密和資料刪除工作流程。 | **設計上完全合規**。內建同意管理、自動化資料主體刪除請求，以及安全的 ISO 27001 認證託管。
| **分析與行銷** | 需要建構自訂資料擷取管道並整合第三方行銷工具。 | **企業級分析儀表板**，具備即時人流量追蹤、回訪率指標和自動化行銷活動觸發器 [6]。
| **身分驗證提供商整合** | 與 Google、Facebook、Apple 和本機 SMS 閘道進行手動 OAuth2 整合。 | 與主要社群平台、SMS 閘道以及適用於企業訪客的 Azure AD / Okta 進行**一鍵整合**。

Purple 的平台解決了「自建還是購買」的兩難困境。它為開發人員提供了自訂 HTML/CSS 工作區的完整創作自由，同時消除了大規模支援安全 RADIUS 驗證所需之複雜、高風險的後端基礎架構工程。

## 投資報酬率與商業影響

投資於專業設計、響應式的自訂 Captive Portal，可在 IT 營運、行銷和法律合規性方面帶來可量化的回報。

### 1. 降低營運成本（IT 服務台工單）

在大規模部署中（例如體育場或多站點零售連鎖店），故障的 Captive Portal 是導致 IT 服務台呈報案件增加的主要原因。當訪客遇到「白畫面」或無回應的登入按鈕時，他們會讓現場工作人員應接不暇，或提交支援工單。

$$\text{年度支援節省費用} = (\text{年度訪客總造訪次數} \times \text{Portal 故障率} \times \text{服務台聯絡率}) \times \text{每張支援工單的成本}$$

* **S**情境**：一家每年有 1,000,000 名訪客的會議中心。編寫不良的 portal 在較舊的 iOS 裝置上有 5% 的失敗率，導致 10% 的客服中心聯絡率。以業界標準每張支援工單 15 美元計算，營運成本為：
  $$(1,000,000 \times 0.05 \times 0.10) \times \$15 = \$75,000 \text{ 每年可避免的支援開銷}$$
* **結果**：轉換為經過 CNA 優化、行動優先的範本可將 portal 失敗率降低至 <0.1%，幾乎消除了這項營運消耗。

### 2. 行銷數據獲取與訂閱優化

對於零售和餐旅場所而言，顧客 WiFi portal 是獲取乾淨、第一方客戶數據的主要機制。設計不良的使用者介面（帶有微小的文字或笨重的表單版面配置）會導致高**跳出率**——使用者完全放棄登入流程，從而失去行銷機會。

* **案例研究（零售）**：一家全國零售連鎖店採用了利用 Purple 平台且經過行動優先優化的 captive portal。透過將多步驟登入表單替換為單一欄位的電子郵件輸入（字型大小：16px）和優化的 48px 點擊目標按鈕，他們在第一季內實現了**完成註冊量增加 42%** 以及**行銷電子報訂閱量增加 28%** [6]。

### 3. 法律與合規風險緩解

在 GDPR 和 CCPA 的規範下，不合規的數據收集會帶來嚴厲的財務處罰（在 GDPR 下最高可達全球年營業額的 4%）。依賴預先勾選的核取方塊，或未能於 splash 頁面上提供清晰且易於存取的隱私權政策，會使企業面臨巨大的法律責任。

* **緩解投資報酬率 (ROI)**：實施明確、未預先勾選的同意核取方塊，並將條款託管在優化的滾動框中，可確保 100% 的法規合規性，從而降低數百萬美元監管罰款的風險並保護品牌聲譽。

## 重點摘要

* **CNA 沙箱具有限制性**：Apple 的 iOS Websheet 和 macOS CNA 是高度沙箱化的環境，會封鎖外部資產、Cookie 和網頁字型。所有樣式和資產必須是自包含的（行內 CSS、Base64 圖片、系統字型）[1]。
* **AJAX 會破壞 iOS 結束握手**：若要成功將 iOS 裝置從「captive」狀態轉換為「已連線」狀態（將右上角的按鈕從「取消」變更為「完成」），您必須觸發全頁面 HTTP 重新導向。非同步 DOM 更新會使裝置陷入 captive 迴圈。
* **行動優先是強制性的**：超過 90% 的登入發生在行動裝置上。設計單欄版面配置（最大寬度：480px）、利用適合觸控的點擊目標（最小 44px x 44px），並在所有文字輸入框上強制執行至少 16px 的字型大小，以防止 iOS 瀏覽器自動縮放。
* **圍牆花園（Walled Gardens）控制 DNS**：登入期間引用的任何外部網域（例如社群登入 API）都必須明確列入無線控制器的圍牆花園白名單中，否則頁面將無法載入。
* **Purple 消除後端複雜性**：利用 Purple 的 portal 產生器，開發人員可以透過自訂編輯器獲得完整的 HTML/CSS 控制權，同時減輕 RADIUS、多廠商 AP 整合以及符合 GDPR 規範的資料庫管理所帶來的巨大安全性、擴充性和合規性負擔 [3]。

## 參考資料

* [1] [無線寬頻聯盟：Captive Network Portal 行為](https://captivebehavior.wballiance.com/)
* [2] [Android 開源專案：Captive Portal 登入 Webview 整合](https://source.android.com/docs/core/connect/android-custom-tabs-captive-portal)
* [3] [歐洲資料保護委員會：關於第 2016/679 號條例下同意的指南](https://edpb.europa.eu/our-work-tools/our-documents/guidelines/guidelines-052020-consent-under-regulation-2016679_en)
* [4] [如何使用 Cloud RADIUS 實施 802.1X 驗證](/guides/implementing-8021x-with-cloud-radius)
* [5] [Cisco 無線 AP：2026 年產品與部署指南](/blog/cisco-wireless-ap)
* [6] [Purple WiFi 行銷與分析平台](/guest-wifi-marketing-analytics-platform)

---

## 收聽技術簡報

收聽資深解決方案架構師討論自訂 captive portal 的技術限制和實施策略：