登入位置紀錄
登入位置紀錄
此功能記錄登入當下的位置，與 App 背景定位分開。它不新增計費、不產生 App 失聯警報、不要求每次拍臉，也不阻擋會員登入或遊戲。位置及精度來自瀏覽器，只作風險參考，不能單憑座標認定本人。
網站責任
原始碼交付的 examples/hosted-js/login-location.mjs 提供可重用的明示同意後拍點與同源提交 helper；搭配的 README 示範手動重試與本站 CSRF。請將範例納入網站自己的資產建置，不把後端 secret 或會員識別交給 helper。
每次成功建立新的登入 session，由網站後端產生 login_event_id，頁面載入後非同步顯示用途並請求定位。刷新、既有 session 恢復、狀態輪詢與驗證回呼都不是新登入。
瀏覽器建議參數為 maximumAge: 0、timeout: 10000、enableHighAccuracy: true。拒絕權限時不反覆彈窗，提供手動重試指引。每次明確嘗試產生新的 attempt_id；相同嘗試重送保留 ID。
瀏覽器只傳到網站同源後端。後端從目前 session 取得會員，不相信 JS 傳入的 Merchant、環境、user ID 或 Client secret，再以 Server API 傳送。
傳送範例
{
"external_user_ref": "example-member-123",
"login_event_id": "server-generated-login-id",
"attempt_id": "attempt-id",
"location_status": "success",
"consent_version": "login-location-v1",
"observed_at": "2026-10-04T02:00:00+08:00",
"coordinates": {
"latitude": 25.033,
"longitude": 121.5654,
"accuracy_meters": 50
}
}
後端以 Basic 認證與 Idempotency-Key 呼叫 POST /api/partner/v1/login-locations。success 必須有座標及精度，其餘結果禁止夾帶座標。
location_status | 意義 |
|---|---|
success | 瀏覽器取得位置，含精度 |
denied | 未同意或瀏覽器拒絕授權 |
timeout | 取得位置逾時 |
unavailable | 裝置或定位服務暫時無法提供 |
unsupported | 瀏覽器不支援介面 |
not_received | 未執行 JS、關頁或尚未回報；不能假造已取得位置 |
除 not_received 以外，consent_version 與 observed_at 必填。伺服器另外保存 received_at。未完成 KYC 也可記錄，無須建立假的平台帳號。
留存與重送
eKYC 以伺服器接收時間保存新座標 31 天，之後清除座標，保留不含座標的事件摘要。網址、一般日誌及 webhook 都不得包含座標。
網站可使用短期 outbox 非同步補送；成功後清除暫存座標，失敗最多保留 24 小時。重送沿用相同嘗試 ID、Idempotency-Key 與內容；新位置或手動重試是新嘗試，不覆寫原觀測。定位傳輸失敗不影響原登入成功。