品牌可以要求會員簽署條款。App 要做兩件事:(1) 會員還有未完成的強制條款時,進入頁面就開全螢幕 WebView 讓會員在 17FIT 條款服務完成,條款服務導向 back_url 後 App 關閉 WebView;(2) 在「我的帳戶」顯示提示條款的紅點。條款畫面全部由條款服務提供,App 不做任何條款 UI。開工前唯一缺的是 member_token API(C06),可先用 mock 開發。
三支 17FIT API 加一個條款服務網址。三支 API 的共通約定見 C03,開啟條款服務見 C07。
| 用途 | 呼叫 | 狀態 |
|---|---|---|
| 查紅點數字 | GET /appapi/v1.0.0/approval-term/prompt/status/warn | 已上線 |
| 查中斷表 | GET /appapi/v1.0.0/approval-term/prompt/break-points | 已上線 |
| 取 token | GET /appapi/v1.0.0/approval-term/member-token(暫定) | 尚未提供 |
| 開啟條款服務 | WebView POST https://approve.17fit.com/auth | 已上線 |
品牌設定的條款分兩種:強制條款(break)在會員進頁面時攔下來,完成才能繼續;提示條款(warn)只在「我的帳戶」顯示紅點。
品牌在後台把每份條款設成強制或提示。強制條款:會員登入後進入任何頁面(目前設定是所有頁面),App 就開全螢幕 WebView,會員不能略過。提示條款:只在「我的帳戶」顯示紅點與數字,會員點了才開 WebView,可以按返回離開。條款的列表、填寫、送出畫面全部由 17FIT 條款服務提供,App 不做任何條款 UI。
| 條款種類 | 何時影響會員 | App 行為 | 會員能否略過 |
|---|---|---|---|
| 強制條款(break) | 登入後進入被中斷點命中的頁面 | 開全螢幕條款 WebView,關閉前不能操作底下頁面 | 不能 |
| 提示條款(warn) | 打開「我的帳戶」 | 「合約或問卷」顯示紅點與數字;點擊開條款 WebView | 能 |
| 角色 | 負責 |
|---|---|
| 品牌 App | 查中斷表、比對頁面、取 member_token、開關條款 WebView、顯示紅點 |
| 17FIT API | 回傳未完成數量、中斷表、member_token |
| 條款服務 | 條款列表、填寫、送出、記錄完成;完成後導向 back_url |
| 品牌後台 | 決定哪份條款是強制或提示(App 不參與) |
不在本文件範圍:條款 UI、品牌後台設定、電子簽名、其他 17FIT App。
一次攔截依序是:抓中斷表 → 比對頁面 → 取 member_token → WebView POST /auth → 會員完成 → 導向 back_url → App 關閉並重抓。
App 登入後先抓一次中斷表放在記憶體。每次頁面顯示時用頁面類別名稱比對,命中就取一次性 member_token,用 WebView 把表單 POST 到條款服務。會員在條款服務內完成後,條款服務導向 App 給的 back_url;App 攔下這個導向、關閉 WebView,先把剛才那個 flow 從本機中斷表移除,再重抓一次確認。
| 序 | 執行者 | 動作 | 成功結果 | 失敗處置 |
|---|---|---|---|---|
| 1 | App | 登入後呼叫中斷表 API(C05) | 中斷表存在記憶體 | 視為空,放行(C09) |
| 2 | App | 頁面顯示時以類別名稱比對(C10) | 命中某列,記下 id | 未命中:不動作 |
| 3 | App | 呼叫 member_token API(C06) | 取得 member_token | 提示錯誤,回待命(C11) |
| 4 | App | 開全螢幕 WebView,POST 表單到 /auth(C07) | 顯示該 flow 的未完成條款清單 | 導向 error_url(C08) |
| 5 | 會員 | 在條款服務內逐份填寫送出 | 全部完成後導向 back_url | 頁內錯誤以 toast 顯示,WebView 不關 |
| 6 | App | 攔下 back_url/error_url:取消載入、關閉 WebView | WebView 關閉 | — |
| 7 | App | 移除該 id 的所有列後重抓中斷表,再比對目前頁面 | 不會再攔已完成的條款 | 重抓失敗:視為空,放行 |
三支 17FIT API 沿用 App 既有的 appapi 主機與認證參數;成功回 HTTP 200+code 0,失敗回 HTTP 400+字串錯誤碼。
三支 API 都是唯讀的 GET,可以安全重試。認證沿用 App 目前呼叫 appapi 的方式,把 agent_token(App 識別)與 token(會員登入)放在 query;會員身分一律取自 token,API 不接受外部傳入 member id。要特別注意 code 的型別:成功時是數字 0,失敗時是字串,解析時一律轉成字串再比較。伺服器端沒有快取,每次呼叫都是最新狀態。
| 項目 | 規則 |
|---|---|
| 主機 | 與 App 目前呼叫的 17FIT appapi 相同 |
| 路徑前綴 | /appapi/v1.0.0/ |
| 認證 | query agent_token、token(沿用既有) |
| 成功 | HTTP 200,{"code": 0, "msg": "success", "message": "", "data": <內容>} |
| 失敗 | HTTP 400,{"code": "<錯誤碼>", "msg": "<錯誤名>", "message": "<中文訊息>", "data": <不固定>} |
| code 型別 | 成功是數字 0;失敗是字串(例 "A2009"、"00027") |
| data | 只在成功時有固定形狀;失敗時不讀 |
| 快取 | 伺服器端無快取 |
GET …/approval-term/prompt/status/warn?studio_id= 回 data.count,App 用它顯示紅點數字。
level 可以是 warn 或 break,但 App 只需要 warn;強制條款改用中斷表 API 處理。data.count 是會員在這個品牌尚未完成的提示條款數,直接顯示即可。
GET /appapi/v1.0.0/approval-term/prompt/status/{level}
?studio_id={studio_id}
&agent_token=...
&token=...| 參數 | 位置 | 型別 | 必填 | 規則 |
|---|---|---|---|---|
| level | path | string | 是 | warn 或 break;其他值回 A2008 |
| studio_id | query | int | 是 | 數字;缺少或非數字回 A2006;會員不屬於此品牌回 A2009 |
| agent_token | query | string | 是 | C03 |
| token | query | string | 是 | C03 |
{ "code": 0, "msg": "success", "message": "", "data": { "count": 2 } }| 欄位 | 型別 | 說明 |
|---|---|---|
| data.count | int,≥ 0 | 未完成的該等級條款數 |
GET …/approval-term/prompt/break-points?studio_id=&platform= 回陣列;一列=一份未完成強制條款 × 一個本平台中斷點,所以同一個 id 會重複。
R01:一個 User Flow 在回應中出現時至少一列、可能多列;一列恰屬一個 User Flow(欄位 id)。會員完成該 flow 的全部強制條款後,這個 id 的列全部消失。R02:一份未完成的強制條款至少一列(該 flow 在本平台有幾個中斷點就幾列,目前都是 1 個);一列恰對應一份條款(欄位 approval_term_id)。會員完成該條款後,它的列消失。
所以品牌有 3 份未完成強制條款時,會收到 3 列 id 都是 any-pages 的資料。App 必須以 id 去重,同一個 id 只開一次 WebView——條款服務會在同一個畫面列出該 flow 的全部未完成條款。
| ID | 來源 | 目標 | 來源端基數 | 目標端基數 | 承載欄位 | 何時消失 |
|---|---|---|---|---|---|---|
| R01 | User Flow | 中斷表列 | 1 | 1..* | id | 完成該 flow 全部強制條款後 |
| R02 | 未完成的強制條款 | 中斷表列 | 1 | 1..* | approval_term_id | 完成該條款後 |
GET /appapi/v1.0.0/approval-term/prompt/break-points
?studio_id={studio_id}
&platform={platform}
&agent_token=...
&token=...| 參數 | 位置 | 型別 | 必填 | 規則 |
|---|---|---|---|---|
| studio_id | query | int | 是 | 同 C04 |
| platform | query | string | 是 | Android studio-android;iOS studio-ios;其他值回 A2007 |
| agent_token | query | string | 是 | C03 |
| token | query | string | 是 | C03 |
成功回應範例(Android,品牌有 2 份未完成強制條款)。沒有未完成強制條款時回 "data": []。
{
"code": 0, "msg": "success", "message": "",
"data": [
{
"id": "any-pages",
"user_flow_display_name": "登入後",
"approval_policy_type": "once",
"break_point_id": 4,
"break_point_pattern_type": "android-fragment",
"break_point_pattern_value": { "name_regexp": ".*" },
"setting_owner_type": "studio",
"setting_owner_id": 1834,
"approval_prompt_level": "break",
"signature_prompt_level": "none",
"approval_term_id": 101
},
{
"id": "any-pages",
"user_flow_display_name": "登入後",
"approval_policy_type": "once",
"break_point_id": 4,
"break_point_pattern_type": "android-fragment",
"break_point_pattern_value": { "name_regexp": ".*" },
"setting_owner_type": "studio",
"setting_owner_id": 1834,
"approval_prompt_level": "break",
"signature_prompt_level": "none",
"approval_term_id": 102
}
]
}| 欄位 | 型別 | App 是否使用 | 說明 |
|---|---|---|---|
| id | string | 使用 | User Flow id,例 any-pages;開 WebView 時當 user_flow_id 送出。欄位名是 id,不是 user_flow_id |
| approval_prompt_level | string | 使用 | 恆為 "break",比對時仍要檢查 |
| break_point_pattern_type | string | 使用 | Android "android-fragment";iOS "ios-view-controller" |
| break_point_pattern_value | object | 使用 | {"name_regexp": "…"};若收到字串先當 JSON 解析一次 |
| user_flow_display_name | string | 選用 | 顯示名稱,例「登入後」,可用於 log |
| approval_term_id | int | 不使用 | 只用來理解為何同一 id 會重複 |
| break_point_id | int | 不使用 | — |
| approval_policy_type | string | 不使用 | — |
| setting_owner_type | string | 不使用 | 恆為 "studio" |
| setting_owner_id | int | 不使用 | 等於 studio_id |
| signature_prompt_level | string | 不使用 | — |
| 規則 | 說明 |
|---|---|
| 排序 | 不保證,不可依賴 |
| 重複 | 同一 id 可出現多列(R01) |
| 未知欄位 | 忽略;後端可能新增欄位 |
| 目前上線值 | Android、iOS 各一個中斷點:id = any-pages、name_regexp = ".*",即登入後任何頁面都攔 |
開 WebView 前要向 17FIT API 取一次性 member_token;這支 API 目前不存在,是唯一阻擋開工串接的項目。
App 可以先用 mock 開發,正式路徑與回應以 17FIT 後端通知為準。token 是一次性的:每次開 WebView 前都重新取,取到立刻送出;不儲存、不重用、不解析內容,當不透明字串原樣送出。取得失敗就不開 WebView,提示錯誤並回待命,下次頁面顯示時再試。
GET /appapi/v1.0.0/approval-term/member-token
?studio_id={studio_id}
&agent_token=...
&token=...| 參數 | 位置 | 型別 | 必填 | 規則 |
|---|---|---|---|---|
| studio_id | query | int | 是 | 同 C04;會員不屬於此品牌回 A2009 |
| agent_token | query | string | 是 | C03 |
| token | query | string | 是 | C03 |
{
"code": 0, "msg": "success", "message": "",
"data": { "member_token": "eyJ0eXAiOiJKV1Qi..." }
}| 欄位 | 型別 | 說明 |
|---|---|---|
| data.member_token | string | 一次性 token,簽發後 60 秒過期 |
條款 WebView 以表單 POST https://approve.17fit.com/auth;break 與 warn 送的欄位不同。
POST 必須由 WebView 本身送出(不是 App 的 HTTP client),因為條款服務要在 WebView 內建立登入狀態。Content-Type 是 application/x-www-form-urlencoded,每個值都要 URL encode。正式環境網址 https://approve.17fit.com/auth,測試環境網域待 17FIT 提供。
| 欄位 | 強制條款攔截(break) | 提示條款紅點(warn) | 規則 |
|---|---|---|---|
| auth_type | member_token | member_token | 必填固定值;其他值回 A2004 |
| member_token | C06 取得的值 | 同左 | 必填;過期回 A2002 |
| back_url | App 定義的完成網址 | 同左 | 必填;必須是合法 https 網址,否則 A2001 |
| error_url | App 定義的錯誤網址 | 同左 | 必填;空值回 A2003 且不會回到 App |
| success_entry | user-flow | terms | 決定進入哪個畫面 |
| user_flow_id | 命中列的 id(例 any-pages) | 不送 | user-flow 時必填,缺少回 A2001 |
| by_pass_single_item | 1 | 不送 | user-flow 時必填,缺少回 A2001 |
範例(break,URL encode 前):
auth_type=member_token
member_token=eyJ0eXAiOiJKV1Qi...
back_url=https://app-callback.example.com/approve-term/back
error_url=https://app-callback.example.com/approve-term/error
success_entry=user-flow
user_flow_id=any-pages
by_pass_single_item=1| success_entry | 會員看到 | 何時導向 back_url |
|---|---|---|
| user-flow | 流程攔截頁:列出該 flow 全部未完成條款,逐份點入填寫 | 全部完成時;或載入時已無未完成條款 |
| terms | 條款列表頁:列出品牌全部條款 | 會員按頁面上的「返回」 |
已知行為:by_pass_single_item=1 原本的用意是只有一份條款時直接進填寫頁,目前尚未生效,只有一份也會先顯示流程攔截頁。後端修正後自動生效,App 照送 1、不需改動。
條款服務用「導向 back_url」表示完成或返回、用「導向 error_url+錯誤參數」表示開啟失敗;App 攔下導向、取消載入、關閉 WebView。
App 不需要真的有這兩個網頁,它們只是「關閉 WebView 的訊號」。流程攔截頁在全部完成(或載入時已無未完成條款)時導向 back_url;條款列表頁在會員按「返回」時導向 back_url。兩者都由頁面 JavaScript 觸發,且不附加 user_flow_id——App 自己記住觸發的 id,或直接把它寫進 back_url。POST /auth 驗證失敗時以 HTTP 302 導向 error_url,並附加 error_message、error_code、status=fail(error_url 已有 ? 時改用 & 接)。條款頁內部錯誤只顯示 toast,不導向,App 不需處理。
| 事件 | WebView 收到的導向 | App 動作 |
|---|---|---|
| 流程攔截頁:全部完成/載入時已無未完成 | back_url 原字串(JavaScript 導向) | 取消載入、關閉、重抓(C09) |
| 條款列表頁:按「返回」 | back_url 原字串(JavaScript 導向) | 取消載入、關閉、重查紅點(C13) |
| POST /auth 驗證失敗 | error_url?error_message=…&error_code=…&status=fail(HTTP 302) | 取消載入、讀 error_code、關閉、提示(C14) |
| 驗證失敗且沒帶 error_url | 不導向 App | App 無從得知,所以 error_url 一定要帶 |
| 條款頁內部錯誤 | 不導向 | 不需處理 |
myapp://)不保證通過驗證。https://app-callback.example.com/approve-term/back?user_flow_id=any-pages登入後、冷啟動、關閉 WebView 後、切換品牌時抓中斷表;只存記憶體;抓取失敗就放行。
中斷表只放記憶體,因為條款完成狀態以伺服器為準,寫入磁碟會在離線或換帳號時用到過期資料。抓取失敗(逾時、HTTP 400、斷網)一律放行,不能讓 App 卡住。關閉條款 WebView 時要先在本機移除觸發的 id,再重抓、重抓完成才回到待命,這樣底層頁面重新出現時不會用舊資料再攔一次。
| 時機 | 動作 |
|---|---|
| 登入成功 | 抓中斷表;抓完立刻對目前頁面比對一次 |
| 冷啟動且已登入 | 同上 |
| 關閉條款 WebView | 先移除觸發的 id,再重抓;完成後才回待命並比對目前頁面 |
| 切換品牌 | 清空並重抓 |
| 從背景回到前景 | 重抓(建議;待確認) |
| 登出 | 清空 |
| 抓取失敗 | 視為空,放行;下一個重抓時機再試 |
| 未登入 | 不抓、不比對 |
以目前頁面的類別名稱對 name_regexp 做完整比對,且 level=break、pattern_type=本平台,三者都成立才攔。
比對前先以 id 去重。頁面名稱用類別的簡單名稱,正規表達式要對整個名稱做完整比對(不是部分包含)。例如 CancelSubscriptionFragment 只命中該頁,CancelSubscription.* 命中所有以 CancelSubscription 開頭的頁面,.* 命中所有頁面。正規表達式無法編譯就略過該列並記 log,不可閃退。
| 項目 | Android | iOS |
|---|---|---|
| 「頁面」指的是 | Fragment | UIViewController |
| 頁面名稱 | fragment.javaClass.simpleName | String(describing: type(of: viewController))(不要用 NSStringFromClass,會帶模組前綴) |
| 完整比對 | Regex(pattern).matches(name) | NSRegularExpression(pattern: "^(?:" + pattern + ")$") |
| release 版 | R8/ProGuard 加 -keepnames class * extends androidx.fragment.app.Fragment | 不需處理 |
| 規則 | 說明 |
|---|---|
| 排除頁面 | 條款 WebView 所在頁、登入頁、啟動頁、註冊頁;建議實作標記介面 SkipBreakCheck |
| 頁面名稱是對外契約 | 後端以類別名稱設定中斷點;重構改名前先通知 17FIT |
| 新增中斷點不需改版 | 後端新增 User Flow 或中斷點時,照本節通用規則比對就會自動生效 |
攔截守門員有四個狀態:未就緒、重抓中、待命、攔截中;只有「待命」會觸發攔截。
這是建議設計,用來避免兩個實際會發生的問題:(1) 條款 WebView 所在頁面本身也會被 .* 命中,若不擋就會開第二個 WebView;(2) 關閉 WebView 時底層頁面會再次 resume/appear,若中斷表還沒更新就會再攔一次。不變量:同一時間最多一個條款 WebView;只有待命會觸發攔截;重抓中回到待命後才重新比對目前頁面。
| 起始 | 事件 | 條件 | 目標 | 動作 |
|---|---|---|---|---|
| 未就緒 | 登入成功、冷啟動已登入 | — | 重抓中 | 呼叫中斷表 API |
| 重抓中 | API 成功 | — | 待命 | 存中斷表;對目前頁面執行一次頁面顯示 |
| 重抓中 | API 失敗 | — | 待命 | 中斷表設為空(放行) |
| 待命 | 頁面顯示 | SkipBreakCheck 或未命中 | 待命 | 無 |
| 待命 | 頁面顯示 | 命中某 id | 攔截中 | 記下 id;取 member_token;開 WebView 並 POST /auth |
| 攔截中 | 頁面顯示 | — | 攔截中 | 忽略 |
| 攔截中 | 取 member_token 失敗 | — | 待命 | 不開或關閉 WebView;提示錯誤 |
| 攔截中 | 導向 back_url | — | 重抓中 | 取消載入;移除該 id;關閉;呼叫中斷表 API |
| 攔截中 | 導向 error_url | — | 重抓中 | 取消載入;讀 error_code;關閉;提示;呼叫中斷表 API |
| 任何 | 登出 | — | 未就緒 | 清空中斷表;清除條款服務網域 cookie |
Android 掛 onFragmentResumed+WebView.postUrl+shouldOverrideUrlLoading;iOS 掛共用 base VC 的 viewDidAppear+WKWebView POST+decidePolicyFor。
選「頁面顯示後覆蓋」而不是「跳頁前攔截」:返回鍵、切 tab、推播、deep link 不一定經過共用跳頁函式,跳頁前攔截會漏;頁面顯示事件涵蓋所有進入方式,會員完成後 WebView 關閉,人已在原本要去的頁面。WebView 必須能攔截導向,所以不能用 Chrome Custom Tabs 或 SFSafariViewController。
| 項目 | Android | iOS |
|---|---|---|
| 頁面顯示事件 | registerFragmentLifecycleCallbacks(cb, true) 的 onFragmentResumed(true=含子 Fragment) | 共用 base VC 的 viewDidAppear;沒有 base class 時改掛 navigationController(_:didShow:animated:) 並另處理 tab、modal |
| WebView 元件 | android.webkit.WebView | WKWebView |
| 禁用 | Chrome Custom Tabs | SFSafariViewController |
| 送出 POST | webView.postUrl(authUrl, formBytes) | URLRequest:httpMethod POST、Content-Type form-urlencoded、httpBody 表單 |
| 攔截導向 | shouldOverrideUrlLoading;onPageStarted 再判斷一次作保險 | decidePolicyFor 回 .cancel |
| 設定 | javaScriptEnabled、domStorageEnabled、接受 cookie | 預設值 |
| 呈現 | 全螢幕 | .fullScreen+isModalInPresentation = true |
| 返回鍵/手勢 | canGoBack 時 goBack,否則不動作;不關閉 | 不可下滑關閉;不放關閉按鈕 |
// 頁面顯示事件:在主 Activity onCreate 註冊一次
val pageCallbacks = object : FragmentManager.FragmentLifecycleCallbacks() {
override fun onFragmentResumed(fm: FragmentManager, f: Fragment) {
ApprovalBreakGuard.onPageShown(f.javaClass.simpleName, skip = f is SkipBreakCheck)
}
}
supportFragmentManager.registerFragmentLifecycleCallbacks(pageCallbacks, true)
// 比對:去重 → 三個條件 → 回傳命中的 id
fun findHit(rows: List<BreakRow>, pageName: String): String? =
rows.distinctBy { it.id }.firstOrNull { r ->
r.level == "break" && r.patternType == "android-fragment" &&
runCatching { Regex(r.nameRegexp).matches(pageName) }.getOrDefault(false)
}?.id
// 表單
fun formBody(fields: List<Pair<String, String>>): ByteArray =
fields.joinToString("&") { (k, v) ->
URLEncoder.encode(k, "UTF-8") + "=" + URLEncoder.encode(v, "UTF-8")
}.toByteArray(Charsets.UTF_8)
// 開啟與攔截
webView.settings.javaScriptEnabled = true
webView.settings.domStorageEnabled = true
CookieManager.getInstance().setAcceptCookie(true)
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(
view: WebView, request: WebResourceRequest,
): Boolean = handleUrl(request.url.toString())
override fun onPageStarted(view: WebView, url: String, favicon: Bitmap?) {
if (handleUrl(url)) view.stopLoading()
}
}
fun handleUrl(url: String): Boolean {
when {
url.startsWith(BACK_URL) -> ApprovalBreakGuard.onWebViewClosed(errorCode = null)
url.startsWith(ERROR_URL) -> {
val code = Uri.parse(url).getQueryParameter("error_code")
ApprovalBreakGuard.onWebViewClosed(errorCode = code)
}
else -> return false
}
return true
}
webView.postUrl(AUTH_URL, formBody(listOf(
"auth_type" to "member_token",
"member_token" to token,
"back_url" to BACK_URL,
"error_url" to ERROR_URL,
"success_entry" to "user-flow",
"user_flow_id" to flowId,
"by_pass_single_item" to "1",
)))onWebViewClosed 要確保只執行一次,因為兩個 callback 都可能收到同一個網址。
// 頁面顯示事件:所有頁面共用的 base class
class BaseViewController: UIViewController {
override func viewDidAppear(_ animated: Bool) {
super.viewDidAppear(animated)
let name = String(describing: type(of: self))
ApprovalBreakGuard.shared.onPageShown(name, skip: self is SkipBreakCheck)
}
}
// 完整比對
func fullMatch(_ pattern: String, _ name: String) -> Bool {
guard let re = try? NSRegularExpression(pattern: "^(?:\(pattern))$") else {
return false
}
return re.firstMatch(in: name, range: NSRange(name.startIndex..., in: name)) != nil
}
// 表單
func formBody(_ fields: [(String, String)]) -> Data {
// 只保留 RFC 3986 unreserved 字元,其餘全部 percent-encode
let allowed = CharacterSet(charactersIn:
"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~")
func enc(_ s: String) -> String {
s.addingPercentEncoding(withAllowedCharacters: allowed)!
}
let s = fields.map { "\(enc($0.0))=\(enc($0.1))" }.joined(separator: "&")
return Data(s.utf8)
}
// 開啟
var req = URLRequest(url: URL(string: authURL)!)
req.httpMethod = "POST"
req.setValue("application/x-www-form-urlencoded", forHTTPHeaderField: "Content-Type")
req.httpBody = formBody([
("auth_type", "member_token"), ("member_token", token),
("back_url", backURL), ("error_url", errorURL),
("success_entry", "user-flow"), ("user_flow_id", flowId), ("by_pass_single_item", "1"),
])
webView.load(req)
vc.modalPresentationStyle = .fullScreen
vc.isModalInPresentation = true
topViewController.present(vc, animated: true)
// 攔截
func webView(_ webView: WKWebView, decidePolicyFor action: WKNavigationAction,
decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
let url = action.request.url?.absoluteString ?? ""
if url.hasPrefix(backURL) {
decisionHandler(.cancel)
ApprovalBreakGuard.shared.onWebViewClosed(errorCode: nil)
return
}
if url.hasPrefix(errorURL) {
let items = URLComponents(string: url)?.queryItems
let code = items?.first { $0.name == "error_code" }?.value
decisionHandler(.cancel)
ApprovalBreakGuard.shared.onWebViewClosed(errorCode: code)
return
}
decisionHandler(.allow)
}on pageShown(name, skip):
if state != Ready or !loggedIn or skip: return
flowId = findHit(breakPoints, name) # C10
if flowId == null: return
state = Presenting; triggeredId = flowId
token = GET member-token(studio_id) # C06;失敗 → state = Ready、提示、return
openWebView(POST AUTH_URL, form(token, BACK_URL, ERROR_URL,
success_entry = "user-flow", user_flow_id = flowId,
by_pass_single_item = "1"))
on webViewClosed(errorCode): # 只執行一次
closeWebView()
breakPoints = breakPoints.filter(r -> r.id != triggeredId)
state = Refreshing
breakPoints = GET break-points(studio_id, PLATFORM) or [] # 失敗 → []
state = Ready
pageShown(currentPageName, currentPageSkip)
if errorCode != null: showError(errorCode) # C14「我的帳戶」以 status/warn 的 count 顯示紅點;點擊以 success_entry=terms 開 WebView,關閉後重查。
提示條款不經過守門員的「攔截中」狀態,但條款 WebView 頁面屬於 SkipBreakCheck,開啟期間不會觸發強制條款攔截。
| 序 | 執行者 | 動作 | 成功結果 | 失敗處置 |
|---|---|---|---|---|
| 1 | App | 進入「我的帳戶」呼叫 status/warn | 取得 data.count | 不顯示紅點 |
| 2 | App | count > 0 時「合約或問卷」顯示紅點與數字 | — | — |
| 3 | 會員 | 點「合約或問卷」 | — | — |
| 4 | App | 取 member_token,開 WebView,POST /auth:success_entry=terms,不送 user_flow_id、by_pass_single_item | 顯示條款列表頁 | 導向 error_url(C14) |
| 5 | 會員 | 填寫,或按「返回」 | 導向 back_url | — |
| 6 | App | 攔下 back_url,關閉,重查 status/warn | 紅點更新 | 維持原數字 |
API 錯誤以 HTTP 400+code 回傳;開啟失敗以 error_url 的 error_code 帶回;每個碼都有固定處置。
提示文字為建議,App 可依自己的文案調整。error_url 帶回的 error_message 是給工程師看的中文訊息,不建議直接顯示給會員。
| code | msg | 觸發條件 | App 處置 |
|---|---|---|---|
| 00027 | UserNotFound | 會員 token 缺少或無效 | 依既有做法導回登入 |
| 00003 | Unauthorized | agent_token 無效 | 依既有做法重取 agent_token |
| A2006 | InvalidStudioId | studio_id 缺少或非數字 | 記 log;不攔截/不顯示紅點 |
| A2007 | InvalidPlatform | platform 不在允許值 | 記 log;不攔截 |
| A2008 | InvalidLevel | level 不是 warn/break | 記 log;不顯示紅點 |
| A2009 | MemberNotInStudio | 會員不屬於這個品牌 | 記 log;不攔截/不顯示紅點 |
| A2000 | UnknowError | 伺服器未預期錯誤 | 記 log;不攔截;下次重抓再試 |
| error_code | 觸發條件 | App 處置 |
|---|---|---|
| A2001 | 欄位缺漏或格式錯(網址不合法、缺 member_token、break 缺 user_flow_id 或 by_pass_single_item) | 關閉;提示「發生錯誤,請再試一次」;回待命 |
| A2002 | member_token 過期(超過 60 秒)或無效 | 關閉;提示「畫面逾時,請再試一次」;下次頁面顯示重取 token |
| A2003 | 沒帶 error_url | 不會回到 App;一律帶 error_url 即可避免 |
| A2004 | auth_type 不是 member_token | 同 A2001 |
member_token 60 秒內要用掉;同時最多 1 個條款 WebView;API 無快取,會員完成後下一次呼叫就反映。
| 項目 | 規則 | 驗證方式 |
|---|---|---|
| member_token 時效 | 60 秒;取得後立即送出 | 取得後等 61 秒才送,應得 A2002 |
| WebView 數量 | 同時最多 1 個 | 快速連續切頁只出現一個 |
| 資料即時性 | 伺服器無快取;完成後下一次呼叫即不含該條款 | 完成後立刻呼叫,回 [] 或少了該列 |
| 失敗策略 | 抓取失敗放行 | 斷網登入仍可使用 |
| 排序 | 不依賴 | — |
| Android release | 保留 Fragment 類別名稱 | release 版 log 頁面名稱為原始名稱 |
| 舊版 App | 不攔截;新版上線即生效 | — |
16 條 Given/When/Then,涵蓋攔截、去重、不重複觸發、逾時、錯誤、紅點、混淆、換帳號。
| # | Given | When | Then |
|---|---|---|---|
| (1) | 未登入 | 瀏覽任何頁面 | 不呼叫中斷表 API、不開 WebView |
| (2) | 已登入,品牌有 1 份未完成強制條款 | 登入完成 | 第一個顯示的頁面上開 WebView,顯示流程攔截頁 |
| (3) | 品牌有 4 份未完成強制條款 | 呼叫中斷表 API | 回 4 列、id 皆為 any-pages;只開 1 個 WebView |
| (4) | WebView 開啟中 | 會員完成全部條款 | 攔到 back_url、關閉、重抓後中斷表為空、停在原頁面 |
| (5) | 同 (4) | 底層頁面再次 resume/appear | 不再開 WebView |
| (6) | WebView 開啟中 | Android 返回鍵/iOS 下滑 | WebView 不關閉 |
| (7) | 取得 member_token 後 | 等 61 秒再 POST | 導向 error_url、error_code=A2002;關閉並提示 |
| (8) | 品牌沒有強制條款 | 呼叫中斷表 API | 回 data: [];不攔截 |
| (9) | 已登入 | 從推播或 deep link 開某頁 | 該頁顯示時被攔 |
| (10) | 斷網 | 登入 | 抓取失敗;App 放行可使用 |
| (11) | studio_id 是會員不屬於的品牌 | 呼叫中斷表 API | HTTP 400、code="A2009";不攔截 |
| (12) | 品牌有 M 份未完成提示條款 | 進入我的帳戶 | 紅點=data.count=M |
| (13) | 同 (12) | 填 1 份後返回 | 紅點變 M-1 |
| (14) | Android release(R8 開啟) | 進入任一頁面 | log 頁面名稱為原始 Fragment 類別名 |
| (15) | 會員 A 登出、B 在同裝置登入 | B 被攔截 | WebView 顯示 B 的條款 |
| (16) | iOS | 條款 WebView 的 VC 顯示 | 不會因 .* 再開第二個 WebView |
| 詞 | 定義 |
|---|---|
| 品牌 App | 17FIT 為單一品牌打包的原生 App |
| studio_id | 品牌的數字 id |
| 條款 | 品牌要求會員同意的合約或問卷 |
| 強制條款(break) | 未完成就不能繼續使用 App 的條款 |
| 提示條款(warn) | 只提醒、不阻擋的條款 |
| User Flow | 會被攔截的操作情境,以字串 id 識別;目前只有 any-pages(登入後任何頁面) |
| 中斷點 | 某個 User Flow 在某平台的攔截位置,以頁面類別名稱的正規表達式描述 |
| 中斷表 | 中斷表 API 回傳的陣列 |
| 條款服務(ApproveTerm) | 17FIT 提供條款頁面的 Web 服務,正式環境 approve.17fit.com |
| member_token | 開啟條款服務用的一次性 token,有效 60 秒 |
| 攔截守門員 | 建議 App 實作的單例(ApprovalBreakGuard):保存中斷表、比對、開關 WebView |
| back_url/error_url | App 指定的「完成」/「開啟失敗」網址,條款服務導向它們代表要關閉 WebView |
| 項目 | 目前假設 | 誰決定 | 影響 |
|---|---|---|---|
| member_token API 正式路徑與回應 | 暫定 GET /appapi/v1.0.0/approval-term/member-token?studio_id=,回 data.member_token | 17FIT 後端 | 阻擋串接;可先用 mock 開發 |
| 測試環境 appapi 主機、條款服務網域、測試品牌與帳號 | 由 17FIT 提供 | 17FIT | 阻擋測試 |
| 單一條款直接進填寫頁(by_pass_single_item) | 目前未生效,App 照送 1 | 17FIT 後端 | 不影響 App 實作 |
| 從背景回到前景是否重抓 | 重抓 | 17FIT PM | 影響 C09 一列 |
| 攔截中是否提供「登出」出口 | 不提供 | 17FIT PM | 影響 C12 返回鍵行為 |
| back_url/error_url 實際網址 | https://<App 團隊控制的網域>/approve-term/back、…/error | App 團隊 | 合法 https 網址即可 |