Purple Portal API：您可以實現的應用

針對 IT 經理和網路架構師利用 Purple Portal API 的技術參考指南。本指南詳細介紹了可用的端點、驗證方式，以及將顧客 WiFi 數據與企業系統整合以提升商業智慧和營運效率的實際應用案例。內容涵蓋 REST API 和 Webhook 整合模式，並提供來自餐旅業、零售業和活動產業的具體案例研究。

📖 9 分鐘閱讀📝 2,212 字數🔧 2 範例❓ 3 練習題📚 9 關鍵定義

收聽此指南

查看播客逐字稿

歡迎收看 Purple 技術簡報。我是 Purple 的資深內容策略師，在接下來的十分鐘內，我將為您簡明、實用地概述我們的 Portal API — 它是什麼、您可以用它做什麼，以及如何利用它來發揮最大的業務影響力。本簡報專為 IT 經理、架構師和營運總監所設計，幫助您了解如何將訪客 WiFi 從單純的公用工具轉變為強大的數據資產。

首先讓我們來談談背景。您的場域中設有訪客 WiFi。每天都有成百上千的人進行連線。他們提供電子郵件、或許還有姓名，並同意您的條款。這就是極具價值的首方數據。Purple Portal 提供了出色的儀表板來檢視這些數據，但真正的威力在於將這些數據與您其餘的企業生態系統相連結。這正是 Portal API 發揮作用的地方。它是允許您的系統與我們平台進行程式化溝通的橋樑。

現在，讓我們深入探討技術細節。Portal API 是一個標準的 RESTful 介面。驗證方式簡單且安全，使用直觀的 API Key。您無需擔心伺服器對伺服器通訊中複雜的 OAuth 握手協定。至關重要的是，這裡沒有速率限制。我們是專為企業級規模而建構的，因此無論您是經營單一飯店，還是擁有五百個零售據點的連鎖品牌，此 API 都能輕鬆處理您的數據量。

您有兩種主要方式來獲取數據。第一種是拉取（Pull）方法：標準的 REST 端點。例如 visitors 和 venues 等端點。您可以編寫腳本定期呼叫這些端點，拉取過去二十四小時內的所有訪客數據，並將其載入到您的數據倉庫中進行分析。這是您進行商業智慧分析、在 Power BI 或 Tableau 中建立大局觀儀表板的首選方案。

但真正令人興奮的是推送（Push）方法：Webhooks。這是為了即時處理而設計的。您在自己的一端設定一個監聽端點，當訪客在您的 WiFi 上完成驗證的瞬間，我們就會向您發送一個包含其所有詳細資訊的 JSON 負載 — 姓名、電子郵件、所在的場域、造訪次數，甚至是他們使用的驗證方法（無論是註冊表單、社群登入還是其他方式）。這幾乎是即時完成的。這正是開啟即時、個人化互動的關鍵。這決定了您是在明天才發送行銷郵件，還是在忠實顧客踏入店門的瞬間，立即向其發送包含專屬優惠的歡迎回來通知。讓我來介紹一下您會獲得的資料欄位。Webhook 載荷（payload）主要結構化為四個物件。client 物件提供 MAC 位址和使用者代理（user agent）。company 和 venue 物件提供特定位置的識別碼和地理座標。session 物件提供驗證時間戳記。而 user 物件則是精華所在：包含名字、姓氏、電子郵件、性別、出生日期、手機號碼、郵遞區號，以及每個場地的造訪次數（顯示首次與最後一次造訪日期）。您還可以從 Captive Portal 註冊表單中擷取自訂欄位，因此如果您詢問顧客的會員計劃卡號或飯店房號，這些資訊也會一併傳送過來。

現在，在 API 的 1.7 版本中，有一項值得注意的重要改進。unsubscribed 欄位現在能清楚區分「先前已訂閱但後來主動取消訂閱行銷資訊」的使用者，與「單純從未勾選同意訂閱」的使用者。這對於符合 GDPR 規範以及進行精確的客群細分至關重要。您絕對不會希望將已流失的訂閱者與從未進入行銷漏斗的人混為一談。

讓我們更詳細地討論整合模式。對於 REST API 拉取（pull）模式，您的典型工作流程是一個排程指令碼（例如使用 Python 或 Node.js），在每晚執行。它會使用您的 API 金鑰進行驗證，查詢每個場地的訪客端點，將資料轉換為您需要的格式，然後載入到中央資料庫中。這是一個經典的 ETL 流程。對於多據點營運商，您會遍歷您的場地 ID 並在中央彙整資料。

對於 Webhook 推送（push）模式，架構則略有不同。您需要一個可公開存取且受 SSL 保護的端點。無伺服器函數（Serverless function）在此處是理想的選擇，例如 AWS Lambda、Azure Functions 或 Google Cloud Functions。它具備成本效益、能自動擴充，並可處理繁忙場地中常見的並行請求。當該函數收到來自 Purple 的 POST 請求時，它應該解析 JSON，執行其商業邏輯（例如 CRM 查詢或會員資格檢查），並儘快回傳 200 OK 回應。

這帶出了最重要的實作要求：您的接聽程式（listener）必須在 10 秒內做出回應。如果沒有，Purple 將會重新將該請求排入佇列，並在 3 小時後重試。持續的失敗將會基於安全原因導致 Webhook 被自動停用。因此，請保持您的接聽程式輕量化。僅進行傳回快速回應所需的最少處理，如果您需要進行繁重的處理，請將事件推送到內部佇列並進行非同步處理。

現在，讓我們來看一些實際應用場景，讓這些概念更加具體。

以一家擁有兩百間客房的飯店為例。他們希望在行銷平台中，自動將新的 WiFi 房客加入歡迎電子郵件旅程。解決方案非常簡單：設定一個 Webhook，建立一個簡單的無伺服器接聽程式（listener），當新使用者的資料送達時，檢查他們是否已存在於行銷平台中。如果不存在，則將其新增並觸發歡迎旅程。飯店還可以使用造訪次數欄位來區分初次訪客與回訪房客，並據此量身打造溝通內容。回訪房客可能會收到忠誠度獎勵優惠，而不是通用的歡迎訊息。

現在再考慮一家擁有五十家分店的全國零售連鎖店。他們需要一個中央儀表板，顯示所有位置的人流量趨勢。在這種情況下，REST API 拉取模式是正確的選擇。每晚執行的指令碼會查詢這五十個場地中每個場地的訪客端點，彙整資料並將其載入資料倉儲。接著，分析團隊在此基礎上建立他們的儀表板。他們可以查看哪些分店的新訪客率最高、哪些分店的回訪客比例最好，以及停留時間與銷售業績的關聯性。

接下來，讓我介紹一些常見的陷阱以及如何避免它們。

第一個陷阱是重複事件處理。單次房客造訪可能會觸發多個驗證事件——例如，如果他們的手機螢幕鎖定後重新連線，或者他們在存取點之間漫遊。您的接聽程式必須具備等冪性（idempotent）。在執行傳送電子郵件等操作之前，請先檢查您今天是否已經處理過該使用者的事件。

第二個陷阱是在上線前未驗證您的接聽程式 URL。Purple 要求您在傳送資料之前，先在入口網站中驗證端點。在將接聽程式附加到 LogicFlow 之前，請確保您的接聽程式已上線並傳回正確的 wifiWebhookListener 標頭。

第三個陷阱是忽略訂閱狀態。在將使用者新增至行銷名單之前，請務必檢查 unsubscribed 欄位。向已選擇退出的使用者傳送行銷資訊違反 GDPR，會帶來嚴重的後果。

現在進行快速問答環節。

我可以將此資料與我自訂的 CRM 同步嗎？可以。如果您的 CRM 擁有 API，您可以使用 Webhook 接聽程式作為中介軟體來格式化 Purple 資料並將其推送到您的系統中。Webhook 承載資料（payload）中傳回的 ID 與 REST API 中的 ID 相符，因此如果需要，您也可以進行後續呼叫以取得更多詳細資訊。

如何處理造訪我旗下多個場地的使用者？API 提供了每個場地 ID 的造訪次數，因此您可以輕鬆追蹤顧客在您整個物業中的足跡，並建立全面的跨場地個人檔案。

我可以設定的 Webhook URL 數量有限制嗎？沒有。您可以根據需要驗證並使用任意數量的接聽程式 URL，這在不同團隊或系統需要接收相同事件資料時非常有用。

如果我的接聽程式（listener）因維護而中斷，會發生什麼事？Purple 會重新嘗試傳送失敗的資料，因此當您的接聽程式重新上線時，您可能會收到積壓的事件。您的接聽程式需要妥善處理此情況，並處理可能未按時間順序送達的事件。

總結我們今天涵蓋的所有內容，Purple Portal API 是您釋放顧客 WiFi 資料巨大價值的關鍵。使用 REST API 提取資料以進行報表和分析。使用 Webhooks 即時推送資料，以進行即時、個人化的客戶互動。請記住關鍵原則：即時用推送，報表用提取。

您的下一步是查看我們支援入口網站中的 API 文件。如果您擁有 Engage 授權，請產生 API 金鑰並開始使用 Postman 進行探索。建立一個簡單的 Webhook 接聽程式。看著資料源源不絕地流入。那一刻，這款工具的潛力就會變得一目了然。

感謝您收聽 Purple 技術簡報。如果您想與我們的解決方案架構師討論您的特定整合需求，請造訪 purple dot ai 並預約示範。我們下次見。

重點摘要

✓Purple Portal API 使用簡單的 API Key 驗證提供對訪客 WiFi 資料的程式化存取，且無速率限制。
✓它需要 Engage 授權，目前在 v1.7 版本上運作，該版本透過更清晰的已取消訂閱狀態處理改善了 GDPR 合規性。
✓使用 REST API（拉取）進行批次資料匯出、ETL 程序和分析儀表板。
✓使用 Webhooks（推送）進行即時、事件驅動的動作，例如 CRM 同步、個人化訊息傳遞和會員忠誠度觸發器。
✓Webhook 接收器必須經過 SSL 安全保護、在 10 秒內回應，並設計為能以等冪方式處理重複事件。
✓主要應用場景涵蓋餐旅業（即時 CRM 豐富化）、零售業（跨通路分析）和活動（為贊助商提供經驗證的客流量資料）。
✓該 API 使企業能夠將其 WiFi 基礎架構從成本中心轉變為具有清晰、可衡量 ROI 的策略性資料資產。

執行摘要

對於多據點場域（如飯店、連鎖零售、體育場館和會議中心）的 IT 主管而言，訪客 WiFi 網路不僅僅是一項簡單的便利設施。它是一個豐富且持續補充的第一方數據源，能為行銷、營運和客戶體驗帶來可衡量的業務影響。Purple Portal API 提供了所需的程式化介面，以實現大規模釋放此價值。它允許技術團隊超越內建的分析儀表板，建立強大、自動化的整合，將符合 GDPR 規範的訪客數據直接導入核心業務系統，從 CRM 平台、行銷自動化工具到會員計劃和商業智慧數據倉庫。

本指南為解決方案架構師、IT 經理和資深開發人員提供了實用且具操作性的參考。它詳細介紹了身分驗證模型、可用端點、整合模式以及實際部署情境，展示了 Purple WiFi API 如何將 WiFi 部署從成本中心轉變為策略性數據資產。無論您是首次評估該 API，還是計劃進行生產級的整合，本文檔都將提供您充滿信心推進所需的技術基礎和決策框架。

技術深度剖析

身分驗證與 API 版本控制

Purple Portal API 使用 API Key 身分驗證，這是一種簡單且安全的模型，非常適合伺服器對伺服器（server-to-server）的整合。與需要權杖交換和重新整理週期的 OAuth 2.0 流程不同，API Key 身分驗證只需在請求標頭中包含一個靜態金鑰。這種簡單性減少了整合開銷，且只要將金鑰安全儲存並作為標準憑證管理原則的一部分定期輪換，就不會損及安全性。

目前的生產版本為 v1.7，此版本相較於 v1.6.2 引入了幾項重要改進。最重要的是，使用者數據物件中的 unsubscribed 屬性現在能清楚區分「先前已訂閱但主動取消訂閱行銷資訊的使用者」與「從未訂閱過的使用者」。這種區分對於符合 GDPR 規範以及精確的受眾細分至關重要。此外，當找不到數據時，Visitors 和 Venues 端點現在會傳回 HTTP 200 OK 回應，而不是 404 Not Found，這在以前常導致監控和錯誤處理邏輯上的混淆。

可用的端點

Portal Company API 公開了三個 IT 團隊會經常互動的主要端點類別。

端點	方法	用途
`/visitors`	GET	檢索訪客設定檔，包括聯絡數據、人口統計資料和造訪歷史記錄
`/venues`	GET	檢索場域層級的數據和設定中介數據
`/unsubscribes`	GET	檢索已選擇退出行銷通訊的使用者清單

所有端點均以 JSON 格式傳回資料。visitors 端點是最常用的端點，因為它能完整呈現 Captive Portal 驗證流程中所收集到的訪客個人資料。這包括名字、姓氏、電子郵件地址、性別、出生日期、行動電話號碼、郵遞區號、驗證提供者（例如：註冊表單、社群登入）、每個場域的造訪次數，以及在 Splash 頁面上設定的任何自訂欄位。

速率限制

Purple Portal API 的一個關鍵架構優勢在於沒有速率限制。該平台旨在支援任何數量的請求或交易，非常適合需要處理數千個場域記錄或數百萬個訪客個人資料的大型部署。這消除了與其他平台整合時常見的限制，並且在您的用戶端程式碼中無需進行請求節流或退避邏輯。

整合模式：拉取 (Pull) 與推送 (Push)

Purple WiFi API 支援兩種截然不同的整合模式，各自適用於不同的使用場景。了解在特定情境下應套用哪種模式是您需要做出的最重要架構決策。

REST API 拉取模式涉及您的系統向 API 端點發送隨選或排程的請求以檢索資料。這是批次處理、報表和商業智慧的正確方法。例如，每晚執行一次的 ETL 指令碼，用於拉取前一天的所有訪客資料並將其載入到資料倉儲中。拉取模式讓您能完全控制檢索資料的時間和數量。

Webhook 推送模式則是在特定事件發生時（具體而言，當訪客在 WiFi 網路上進行驗證時），由 Purple 立即將資料傳送到您的系統。您的系統必須提供一個公開可存取、受 SSL 保護的 HTTP 端點（「監聽器」），以接收並處理這些 JSON POST 承載資料。對於任何需要近乎即時資料的使用場景，Webhook 模式是正確的選擇，例如觸發個人化的歡迎訊息、在 CRM 中更新客戶的「最後上線」狀態，或通知餐旅經理 VIP 訪客已到達。

Webhook 承載資料結構

Purple Webhook 傳遞的 JSON 承載資料結構分為四個主要物件，每個物件都為驗證事件提供不同維度的背景資訊。

物件	關鍵欄位	說明
`client`	`mac`, `userAgent`	裝置層級的識別碼
`company`	`id`, `name`, `uniqId`	您的公司帳戶詳細資料
`venue`	`id`, `name`, `latitude`, `longitude`	發生驗證的具體位置
`session`	`authenticationTime`	驗證事件的 ISO 8601 時間戳記
`user`	`email`, `firstName`, `lastName`, `gender`, `provider`, `visitCountForVenues`, `customFields`	完整的訪客個人檔案資料

對於多據點營運商而言，user.visitCountForVenues 物件特別具有價值。它提供了每個場域的造訪次數以及 firstVisit 和 lastVisit 時間戳記，讓您能夠在驗證當下識別出首次造訪者與忠實的回頭客，而無需進行任何額外的 API 呼叫。

實作指南

前提條件與設定

存取 Portal API 需要 Engage 授權。取得授權後，請在 Purple 傳送門的設定中產生您的 API 金鑰。對於初始開發與測試，建議使用 Postman；Purple 提供了專用的設定指南，用以配置正確的環境變數與請求標頭。對於偏好伺服器端指令碼起步的團隊，也提供了一個 PHP 範例檔案。

設定 Webhook 整合

部署 Webhook 整合包含五個步驟。第一，建立您的接聽程式端點並將其部署到可公開存取且受 SSL 保護的 URL。無伺服器函數（AWS Lambda、Azure Functions 或 Google Cloud Functions）是架構上健全的選擇：它能自動擴充、在低流量時成本極低，且無需配置即可處理並行請求。第二，在 Purple 傳送門中導覽至「管理」>「場域」>「Webhooks」以驗證接聽程式 URL。Purple 將傳送一個測試請求，以確認該端點可供存取並傳回所需的 wifiWebhookListener: 1 標頭。第三，在傳送門中建立或編輯 LogicFlow，並新增一個 Webhook 動作節點，選擇您已驗證的 URL。第四，確保 LogicFlow 已設定為「上線」狀態。第五，將 LogicFlow 附加至相關的 Access Journey。從此時起，該歷程上的每次訪客驗證都將觸發您的 Webhook。

處理重試與等冪性

您的接聽程式必須設計為能夠處理分散式系統的實際情況。如果您的接聽程式無回應（逾時超過 10 秒）或傳回錯誤狀態，Purple 將在三小時後重試失敗的 Webhook 傳送。這意味著您的接聽程式可能會多次收到相同的事件。此外，單次訪客造訪可能會觸發多次驗證事件 — 例如，當裝置在螢幕鎖定後重新連線時，或者當使用者在存取點之間漫遊時。因此，您的處理邏輯必須具備等冪性：套用同一個事件兩次應產生與套用一次相同的結果。常見的實作模式是在執行動作（例如傳送歡迎電子郵件）之前，先檢查在定義的時間範圍內是否已針對特定的使用者 ID 執行過該動作。

最佳實踐

在任何生產環境中部署 Purple Portal API 時，都應遵循幾項原則。請務必針對最新的 API 版本 (v1.7) 進行部署，並在新版本發布時更新您的 URL 路徑與回應解析邏輯。請將您的 API Key 視為敏感憑證：將其儲存在金鑰管理工具（例如 AWS Secrets Manager 或 Azure Key Vault）中，而非儲存在原始碼或共享系統的環境變數中。對於 Webhook 監聽器，請針對每個傳入的承載資料 (payload) 與回應實作結構化記錄，以利於偵錯與稽核追蹤。請尊重使用者物件中的 unsubscribed 和 unsubscribedDate 欄位；針對已選擇退出的使用者執行行銷活動將違反 GDPR。最後，請針對所有邊緣情況測試您的整合：沒有電子郵件地址的使用者、自訂欄位為 null 的使用者，以及未按時間順序送達的驗證事件。

疑難排解與風險緩釋

Webhook 整合中最常見的失敗模式是監聽器回應緩慢或無法使用。如果端點持續在 10 秒內未做出回應，Purple 將在長時間無回應後自動停用該 Webhook，此時需要在入口網站中進行手動重新驗證。為了降低此風險，請在與監聽器相同的伺服器上實作健康檢查端點，並將其納入您的基礎架構監控中。確保您的監聽器在傳回 200 OK 回應之前僅執行最少量的同步處理；將任何繁重的運算或下游 API 呼叫轉移到非同步佇列中。

對於 REST API 整合，主要風險在於如果排程的提取工作在背景無聲失敗，會導致下游系統中的資料過期。請在您的 ETL 指令碼上實作警報機制，以便在執行失敗或意外未產生任何輸出時通知維運團隊。從 API v1.6.2 遷移到 v1.7 時，請稽核所有引用 unsubscribed 欄位和 Unsubscribes 端點的程式碼，因為屬性名稱已在 v1.7 中從 unsubcribers 修正為 unsubscribers。

投資報酬率與商業影響

將系統與 Purple Portal API 整合的商業效益已在多個垂直產業中得到證實。在旅宿業中，使用 Webhook 觸發 CRM 整合的飯店報告指出，與一般群發活動相比，個人化溝通的電子郵件開啟率有顯著提升，因為訊息是在關聯性最高的時刻（即房客親自到店時）送達。在零售業中，將顧客 WiFi 數據連接到會員計劃，使營運商能夠識別並獎勵高頻率訪客，進而提高平均消費額和重複造訪率。對於大型公共場所和會議中心，API 驅動的分析提供了證明贊助價值和優化特許經營攤位佈局所需的細粒度人流量數據。

Purple WiFi API 沒有速率限制，這意味著整合成本是隨著您的基礎設施規模而擴展，而不是隨著您處理的數據量而增加。對於每天處理數十萬次驗證的國家零售連鎖店而言，與按 API 呼叫次數收費或施加吞吐量限制的平台相比，這是一個實質性的優勢。因此，架構良好的 Purple API 整合的總擁有成本主要是一次性的開發成本和監聽器（listener）的持續基礎設施成本，這兩者通常在第一季內僅透過提高行銷轉換率就能回收。

案例研究

案例研究 1：旅宿業 — Whitbread Group

Whitbread 是英國最大的飯店和餐飲公司，在其 Premier Inn 和餐飲物業中營運著數千個顧客 WiFi 存取點。藉由將 Purple Portal API 與其 CRM 平台整合，該集團能夠建立一個統一的顧客輪廓，將線上預訂數據與在 WiFi Captive Portal 擷取的實體造訪行為相結合。Webhook 整合在每次顧客驗證時觸發，以最新的造訪時間戳記、場地位置和裝置資訊豐富 CRM 記錄。這使行銷團隊能夠按近期性、頻率和位置對受眾進行細分，並觸發高度個人化的重新互動活動。關鍵的技術成果是將顧客抵達與進入主動行銷旅程之間的時間，從 24 小時（在先前的批次輪詢模式下）縮短到 60 秒以內。

案例研究 2：零售業 — 多據點時尚零售商

一家擁有 80 多家門市的國家級時尚零售商部署了 Purple Portal API，以解決其客戶數據策略中的關鍵缺口：他們擁有強大的電子商務數據，但對店內訪客行為幾乎一無所知。藉由透過每晚的 ETL 程序將 Purple 訪客 WiFi API 連接到他們現有的數據倉庫，他們首次構建了跨管道的客戶視圖。每晚針對每家門市查詢 /visitors 端點，並使用電子郵件地址作為共同金鑰，將數據與電子商務交易記錄進行合併。在三個月內，分析團隊發現連接到店內 WiFi 的客戶在下一次線上購買時的平均訂單價值高出 34%，這為進一步投資店內數位體驗提供了令人信服的商業案例。該整合不需要對現有的電子商務基礎設施進行任何更改，證明了 REST API 拉取模式的低摩擦特性。

案例研究 3：活動 — 會議中心

英國一家大型會議中心使用 Purple Portal API，首次向贊助商提供經過驗證的人流量數據。以前，贊助商報告依賴人工計數和徽章掃描，這既耗費人力又不準確。藉由透過 API 公開每個區域（對應到 Purple 平台中的場地 ID）的聚合、匿名訪客計數，活動團隊可以向贊助商提供即時儀表板，顯示贊助區域的停留時間和訪客量。在活動期間，每 15 分鐘透過 REST API 拉取一次數據，並顯示在自訂的贊助商入口網站上。這項功能直接使第一年的贊助續約率提高了 22%，因為贊助商現在可以使用經過驗證的第一方數據來量化其活動的觸及率。

關鍵定義

Webhook

一種自動化機制，當特定事件發生時，伺服器會透過 HTTP POST 請求，向另一個應用程式發送即時資料通知（推播）。

在 Purple 的應用場景中，當訪客在 WiFi 網路進行驗證時，Webhook 會立即向您的系統發送包含訪客資料的 JSON 負載。這對於即時行銷和 CRM 更新至關重要。

REST API

一種用於建置 Web 服務的標準化架構風格，允許一個系統使用標準的 HTTP 方法（例如 GET 和 POST）向另一個系統請求（或拉取）資料。

IT 團隊使用 Purple REST API 撰寫腳本來拉取批次訪客和場域資料，以便在 Power BI 或 Tableau 等商業智慧工具中進行分析。

API Key Authentication

一種安全性模型，透過在每次請求中（通常在 HTTP Authorization 標頭中）提供唯一的安全權杖（金鑰）來授予對 API 的存取權限。

這比 OAuth 更簡單，非常適合伺服器對伺服器的整合。您的腳本必須在請求標頭中包含有效的 API 金鑰，才能存取 Purple 的資料。

Idempotency

一種操作屬性，意即該操作可以重複執行多次，而不會改變初始執行以外的結果。

您的 Webhook 監聽程式應具備冪等性（Idempotency）。如果它收到兩次相同的驗證事件（這可能因重試或裝置重新連線而發生），它不應該（例如）發送兩封歡迎電子郵件。

JSON (JavaScript Object Notation)

一種輕量級、基於文字的資料交換格式，易於人類閱讀，也易於機器解析和產生。

Purple API 和 Webhooks 以 JSON 格式傳遞所有資料。您的應用程式需要解析此 JSON，以擷取電子郵件、姓名和造訪次數等欄位。

LogicFlow

Purple 的視覺化、拖放式工具，用於建立自動化行銷和互動工作流程，可根據訪客行為和人口統計資料觸發對應的操作。

您可以使用 LogicFlow 來定義訪客旅程。您可以在此處附加您的 Webhook，指示系統在使用者達到其存取旅程的「上網」狀態時觸發該 Webhook。

Captive Portal

使用者在獲准存取公共 WiFi 網路之前，必須看到並與之互動的網頁，通常需要進行驗證或資料收集。

Purple 平台為 Captive Portal 提供支援，使用者在此頁面輸入的資料（例如姓名、電子郵件、自訂欄位）將可透過 Portal API 取得。

GDPR (General Data Protection Regulation)

歐盟一項全面的資料隱私法規，旨在規範歐盟居民個人資料的收集、處理和儲存。

Purple API 提供了建置符合 GDPR 規範之整合的工具，例如尊重使用者的取消訂閱狀態，以及為當事人存取請求啟用資料匯出功能。v1.7 API 更新特別提高了取消訂閱欄位的清晰度，以支援合規性。

ETL (Extract, Transform, Load)

一種資料整合程序，涉及從來源系統擷取資料、將其轉換為所需格式，然後將其載入到目的地系統（例如資料倉儲）中。

REST API 拉取模式通常實作為 ETL 程序，其中資料是從 Purple 的 /visitors 端點擷取，進行轉換以符合目的地結構，然後載入到 CRM 或資料倉儲中。

範例

一家擁有 200 間客房的飯店希望自動將新的顧客 WiFi 使用者加入其 Salesforce Marketing Cloud 旅程中，並發送歡迎電子郵件。

在 Purple Portal 中，驗證指向安全端點（例如 AWS Lambda 上的無伺服器函數）的新 Webhook URL。2. 建立一個包含 Webhook 節點的「線上」LogicFlow，並設定為使用已驗證的 URL。3. 將此 LogicFlow 指派給該飯店的顧客 WiFi 存取旅程。4. 無伺服器函數在顧客驗證時接收 JSON 承載資料，擷取使用者的電子郵件和姓名，並向 Salesforce Marketing Cloud 發送 API 呼叫，將使用者加入「新房客」旅程中。5. 該函數在 10 秒逾時限制內向 Purple 回傳 200 OK 回應。

考官評語： 此解決方案正確使用了即時 Webhook 模式，這對於發送歡迎電子郵件等即時操作非常理想。使用無伺服器函數是託管接聽程式端點的一種具成本效益且具擴充性的方式。另一種替代方案是輪詢 /visitors API 端點，但這會引入長達 24 小時的延遲，且對於即時需求而言效率顯著降低。

一家擁有 50 家分店的連鎖零售商希望在 Power BI 中建立一個中央儀表板，以分析所有據點的訪客趨勢。

建立一個在每晚排程執行的指令碼（例如使用 Python）。2. 該指令碼使用公司的 API 金鑰向 Purple Portal API 進行驗證。3. 它會遍歷 50 個場地 ID 中的每一個，向 /visitors 端點發送呼叫，以檢索前一天的所有訪客數據。4. 指令碼將這些數據轉換並載入到中央資料倉儲（例如 Azure SQL 或 BigQuery）中。5. 將 Power BI 連接到該資料倉儲，以建立跨場地的分析儀表板。

考官評語： 這是一個經典的 ETL（擷取、轉換、載入）程序，也是 REST API 輪詢模式的正確應用。它適用於非即時、大規模的商業智慧數據彙整。在處理來自多個來源的數據時，使用中央資料倉儲是確保效能和擴充性的最佳實踐。由於 Purple API 沒有速率限制，因此該指令碼可以處理所有 50 個場地，而無需擔心流量調節問題。

練習題

Q1. 某體育場希望在 VIP 季票持有者連線至 WiFi 時識別其身分，並傳送通知至最近的接待經理儀表板。他們應該使用哪種整合模式？為什麼？

提示：請考量通知所需的速度，以及該動作是否由事件觸發。

查看標準答案

他們應該使用 Webhook（推送）模式。這是一個即時性需求：當 VIP 連線時，Webhook 會立即觸發並傳送至某個服務，該服務會對照季票持有者資料庫查詢使用者的電子郵件或 MAC 位址。如果找到相符項，它會將通知推送至相關的接待儀表板。REST API（拉取）模式會太慢，因為它依賴定期輪詢，可能會引入數分鐘或數小時的延遲。

Q2. 您的任務是為您的全國連鎖咖啡店建立一份每日報告，列出造訪次數前 10 名的場地。您將如何從 Purple 檢索所需的資料？

提示：這是即時報告還是批次報告需求？您會查詢哪個端點？

查看標準答案

這是一個批次報告任務，因此使用 REST API（拉取）模式是合適的。排程指令碼會每日執行，查詢每個場地的 /visitors 端點，彙總前一天的造訪次數，然後計算出前 10 名。不需要 Webhooks 提供的近乎即時的通知。由於沒有速率限制，因此可以在單次指令碼執行中查詢所有場地，而無需擔心節流問題。

Q3. 您的 Webhook 接收器端點發生故障。您檢查記錄並看到逾時錯誤。根據 Purple 的文件，最可能的原因是什麼？其兩個直接後果是什麼？

提示：請思考接收器的效能需求，以及當 Purple 無法傳遞承載資料時會怎麼做。

查看標準答案

最可能的原因是接收器花費超過 10 秒的時間來處理傳入的 JSON 承載資料並傳回 200 OK 回應。兩個直接後果是：(1) Purple 將停止嘗試傳送目前的請求，並將其重新排入佇列以在 3 小時後重試，這意味著資料傳遞會延遲；(2) 如果這種情況持續很長時間，Purple 將自動完全停用該 Webhook，需要先在入口網站中進行手動重新驗證才能重新啟用。

Purple Portal API：您可以實現的應用

收聽此指南

執行摘要