品牌 App 條款攔截串接規格(Android/iOS)

品牌可以要求會員簽署條款。App 要做兩件事:(1) 會員還有未完成的強制條款時,進入頁面就開全螢幕 WebView 讓會員在 17FIT 條款服務完成,條款服務導向 back_url 後 App 關閉 WebView;(2) 在「我的帳戶」顯示提示條款的紅點。條款畫面全部由條款服務提供,App 不做任何條款 UI。開工前唯一缺的是 member_token API(C06),可先用 mock 開發。

技術規格(交接給品牌 App 工程師)|2026-10-17|已依 17FIT 現行實作校對,與舊版說明不一致時以本文件為準|agent 版:spec-brand-app-break-point.md

要串的東西

三支 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已上線
取 tokenGET /appapi/v1.0.0/approval-term/member-token(暫定)尚未提供
開啟條款服務WebView POST https://approve.17fit.com/auth已上線

功能概念:強制條款與提示條款C01

品牌設定的條款分兩種:強制條款(break)在會員進頁面時攔下來,完成才能繼續;提示條款(warn)只在「我的帳戶」顯示紅點。

兩種條款在什麼時機影響會員,App 分別做什麼 品牌後台設定條款種類強制條款 break不可略過提示條款 warn可略過進入任何頁面(中斷點命中)我的帳戶紅點+數字條款服務列表/填寫/送出完成→back_url設為設為App 強制開 WebView會員點擊開 WebViewApp 只負責:查中斷表、比對頁面、開關 WebView、顯示紅點;條款畫面全部由條款服務提供
這張圖回答「兩種條款分別在什麼時機影響會員、App 要做什麼」:藍色是 App 必須主動做的強制攔截,黑色是會員自己點進去的提示入口,兩條路最後都進條款服務。

品牌在後台把每份條款設成強制或提示。強制條款:會員登入後進入任何頁面(目前設定是所有頁面),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。

整體流程C02

一次攔截依序是:抓中斷表 → 比對頁面 → 取 member_token → WebView POST /auth → 會員完成 → 導向 back_url → App 關閉並重抓。

強制條款一次完整攔截的請求順序 品牌 App17FIT API條款 WebView(條款服務)(1) GET break-pointsdata:中斷表(2) 頁面顯示 → 比對命中(3) GET member-token(暫定)data.member_token(60 秒內用掉)(4) POST /auth 表單(5) 會員填寫、送出(6) 導向 back_url → App 攔下並關閉(7) 移除該 id 後重抓 break-points
這張循序圖回答「一次攔截的請求依序打到哪裡」:編號對應下表的步驟;紅色虛線是尚待後端提供的 member-token,藍色是 WebView 與條款服務之間的往返。

App 登入後先抓一次中斷表放在記憶體。每次頁面顯示時用頁面類別名稱比對,命中就取一次性 member_token,用 WebView 把表單 POST 到條款服務。會員在條款服務內完成後,條款服務導向 App 給的 back_url;App 攔下這個導向、關閉 WebView,先把剛才那個 flow 從本機中斷表移除,再重抓一次確認。

序執行者動作成功結果失敗處置
1App登入後呼叫中斷表 API(C05)中斷表存在記憶體視為空,放行(C09)
2App頁面顯示時以類別名稱比對(C10)命中某列,記下 id未命中:不動作
3App呼叫 member_token API(C06)取得 member_token提示錯誤,回待命(C11)
4App開全螢幕 WebView,POST 表單到 /auth(C07)顯示該 flow 的未完成條款清單導向 error_url(C08)
5會員在條款服務內逐份填寫送出全部完成後導向 back_url頁內錯誤以 toast 顯示,WebView 不關
6App攔下 back_url/error_url:取消載入、關閉 WebViewWebView 關閉—
7App移除該 id 的所有列後重抓中斷表,再比對目前頁面不會再攔已完成的條款重抓失敗:視為空,放行

API 共通約定C03

三支 17FIT API 沿用 App 既有的 appapi 主機與認證參數;成功回 HTTP 200+code 0,失敗回 HTTP 400+字串錯誤碼。

三支 API 共用的請求參數與回應信封 status/{level}break-pointsmember-token(暫定)共通請求GET /appapi/v1.0.0/…query:agent_token、token+各 API 參數HTTP 200code: 0(數字)data:固定形狀HTTP 400code: "A2009"(字串)data:不讀成功失敗解析時把 code 一律轉成字串再比較;msg、message 兩種回應都有
這張圖回答「三支 API 共用哪些請求參數、回應長什麼樣」:左邊三支 API 都帶同一組認證參數,右邊依 HTTP 狀態碼分成兩種回應信封。

三支 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只在成功時有固定形狀;失敗時不讀
快取伺服器端無快取

待完成數量 API(status)C04

GET …/approval-term/prompt/status/warn?studio_id= 回 data.count,App 用它顯示紅點數字。

status/warn 的回應怎麼決定紅點 我的帳戶頁GET status/warn?studio_idHTTP 200data.count = NHTTP 400A2006/A2008/A2009N > 0:紅點顯示 NN = 0:不顯示紅點不顯示紅點、記 log成功失敗App 只需要 level = warn;強制條款改用中斷表 API
這張圖回答「status/warn 的回應怎麼決定紅點」:成功時依 count 是否大於 0 決定顯示與否,失敗一律不顯示。

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=...
參數位置型別必填規則
levelpathstring是warn 或 break;其他值回 A2008
studio_idqueryint是數字;缺少或非數字回 A2006;會員不屬於此品牌回 A2009
agent_tokenquerystring是C03
tokenquerystring是C03
{ "code": 0, "msg": "success", "message": "", "data": { "count": 2 } }
欄位型別說明
data.countint,≥ 0未完成的該等級條款數

中斷表 API(break-points)C05

GET …/approval-term/prompt/break-points?studio_id=&platform= 回陣列;一列=一份未完成強制條款 × 一個本平台中斷點,所以同一個 id 會重複。

中斷表每一列從哪裡來、為什麼會重複、App 怎麼處理 User Flow被攔截的操作情境id:"any-pages"未完成的強制條款會員還沒完成的一份approval_term_id中斷表列(data[i])一份條款 × 一個本平台中斷點idapproval_prompt_levelbreak_point_pattern_typebreak_point_pattern_value ↳ name_regexpapproval_term_id11..*R0111..*R02App 以 id 去重同一 id 只開1 個 WebView3 份未完成強制條款 → 3 列,id 都是 any-pages;回應不保證排序
這張物件圖回答「中斷表每一列從哪裡來、為什麼會重複」:線兩端是基數,R01 表示一個 User Flow 展開成 1 到多列,R02 表示一份未完成條款展開成 1 到多列;App 最後以 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來源目標來源端基數目標端基數承載欄位何時消失
R01User Flow中斷表列11..*id完成該 flow 全部強制條款後
R02未完成的強制條款中斷表列11..*approval_term_id完成該條款後
GET /appapi/v1.0.0/approval-term/prompt/break-points
    ?studio_id={studio_id}
    &platform={platform}
    &agent_token=...
    &token=...
參數位置型別必填規則
studio_idqueryint是同 C04
platformquerystring是Android studio-android;iOS studio-ios;其他值回 A2007
agent_tokenquerystring是C03
tokenquerystring是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 是否使用說明
idstring使用User Flow id,例 any-pages;開 WebView 時當 user_flow_id 送出。欄位名是 id,不是 user_flow_id
approval_prompt_levelstring使用恆為 "break",比對時仍要檢查
break_point_pattern_typestring使用Android "android-fragment";iOS "ios-view-controller"
break_point_pattern_valueobject使用{"name_regexp": "…"};若收到字串先當 JSON 解析一次
user_flow_display_namestring選用顯示名稱,例「登入後」,可用於 log
approval_term_idint不使用只用來理解為何同一 id 會重複
break_point_idint不使用—
approval_policy_typestring不使用—
setting_owner_typestring不使用恆為 "studio"
setting_owner_idint不使用等於 studio_id
signature_prompt_levelstring不使用—
規則說明
排序不保證,不可依賴
重複同一 id 可出現多列(R01)
未知欄位忽略;後端可能新增欄位
目前上線值Android、iOS 各一個中斷點:id = any-pages、name_regexp = ".*",即登入後任何頁面都攔

member_token API(暫定,待後端提供)C06

開 WebView 前要向 17FIT API 取一次性 member_token;這支 API 目前不存在,是唯一阻擋開工串接的項目。

member_token 何時取、多久內要用掉 品牌 App17FIT API條款服務 /authGET member-token?studio_id(暫定)data.member_tokent = 0 秒,不儲存、不解析WebView POST /auth(60 秒內)驗證 token → 進條款頁超過 60 秒 → error_url?error_code=A2002
這張循序圖回答「token 什麼時候取、多久內要用掉」:取得當下算 t=0,WebView 必須在 60 秒內 POST 出去,超過就會被導向 error_url 並帶 A2002。

App 可以先用 mock 開發,正式路徑與回應以 17FIT 後端通知為準。token 是一次性的:每次開 WebView 前都重新取,取到立刻送出;不儲存、不重用、不解析內容,當不透明字串原樣送出。取得失敗就不開 WebView,提示錯誤並回待命,下次頁面顯示時再試。

GET /appapi/v1.0.0/approval-term/member-token
    ?studio_id={studio_id}
    &agent_token=...
    &token=...
參數位置型別必填規則
studio_idqueryint是同 C04;會員不屬於此品牌回 A2009
agent_tokenquerystring是C03
tokenquerystring是C03
{
  "code": 0, "msg": "success", "message": "",
  "data": { "member_token": "eyJ0eXAiOiJKV1Qi..." }
}
欄位型別說明
data.member_tokenstring一次性 token,簽發後 60 秒過期

開啟條款服務:POST /authC07

條款 WebView 以表單 POST https://approve.17fit.com/auth;break 與 warn 送的欄位不同。

POST /auth 送出後會走到哪個畫面 表單欄位auth_type=member_tokenmember_tokenback_url/error_urlsuccess_entryuser_flow_id*by_pass_single_item*條款服務驗證欄位與 token流程攔截頁(break)列出該 flow 的未完成條款條款列表頁(warn)列出品牌全部條款error_url?error_message&error_code&status=fail條款服務錯誤頁不會回 AppPOSTuser-flowterms驗證失敗沒帶 error_url* 只有 break 送目前即使只有一份條款也會先顯示流程攔截頁;後端修正後自動直跳填寫頁,App 不需改
這張圖回答「表單送出後會走到哪個畫面」:success_entry 決定進流程攔截頁或條款列表頁;驗證失敗導向 error_url,若連 error_url 都沒帶就停在條款服務自己的錯誤頁、回不了 App。

POST 必須由 WebView 本身送出(不是 App 的 HTTP client),因為條款服務要在 WebView 內建立登入狀態。Content-Type 是 application/x-www-form-urlencoded,每個值都要 URL encode。正式環境網址 https://approve.17fit.com/auth,測試環境網域待 17FIT 提供。

欄位強制條款攔截(break)提示條款紅點(warn)規則
auth_typemember_tokenmember_token必填固定值;其他值回 A2004
member_tokenC06 取得的值同左必填;過期回 A2002
back_urlApp 定義的完成網址同左必填;必須是合法 https 網址,否則 A2001
error_urlApp 定義的錯誤網址同左必填;空值回 A2003 且不會回到 App
success_entryuser-flowterms決定進入哪個畫面
user_flow_id命中列的 id(例 any-pages)不送user-flow 時必填,缺少回 A2001
by_pass_single_item1不送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_urlC08

條款服務用「導向 back_url」表示完成或返回、用「導向 error_url+錯誤參數」表示開啟失敗;App 攔下導向、取消載入、關閉 WebView。

條款服務在什麼情況導向 back_url 或 error_url 流程攔截頁列出未完成條款填寫頁完成頁條款列表頁(warn 入口)POST /auth 失敗back_url原字串,不加參數JavaScript 導向error_url+error_code 等三個參數HTTP 302 導向點選送出按完成 → 回清單重查未完成 = 0按返回驗證失敗App:取消載入、關閉 WebView頁內錯誤只顯示 toast,不導向
這張圖回答「會員在條款服務裡怎麼走到出口」:藍色兩條通往 back_url(JavaScript 導向,原字串不加參數),紅色通往 error_url(HTTP 302,附 error_code 等參數);右側是 App 攔截後要做的事。

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不導向 AppApp 無從得知,所以 error_url 一定要帶
條款頁內部錯誤不導向不需處理

中斷表生命週期C09

登入後、冷啟動、關閉 WebView 後、切換品牌時抓中斷表;只存記憶體;抓取失敗就放行。

什麼事件會讓 App 抓取或清空中斷表 記憶體中斷表不寫磁碟登入成功抓取+立即比對目前頁冷啟動(已登入)抓取+立即比對目前頁關閉 WebView先移除該 id,再抓取回到前景*抓取(建議,待 PM)切換 studio清空+抓取登出清空抓取失敗放行(不攔截)
這張圖回答「什麼事件會讓 App 抓取或清空中斷表」:左邊是事件,中間是記憶體中的中斷表,右邊是對應動作;星號表示待確認。

中斷表只放記憶體,因為條款完成狀態以伺服器為準,寫入磁碟會在離線或換帳號時用到過期資料。抓取失敗(逾時、HTTP 400、斷網)一律放行,不能讓 App 卡住。關閉條款 WebView 時要先在本機移除觸發的 id,再重抓、重抓完成才回到待命,這樣底層頁面重新出現時不會用舊資料再攔一次。

時機動作
登入成功抓中斷表;抓完立刻對目前頁面比對一次
冷啟動且已登入同上
關閉條款 WebView先移除觸發的 id,再重抓;完成後才回待命並比對目前頁面
切換品牌清空並重抓
從背景回到前景重抓(建議;待確認)
登出清空
抓取失敗視為空,放行;下一個重抓時機再試
未登入不抓、不比對

頁面比對規則C10

以目前頁面的類別名稱對 name_regexp 做完整比對,且 level=break、pattern_type=本平台,三者都成立才攔。

一個頁面要通過哪些判斷才會被攔 頁面顯示SkipBreakCheck?以 id 去重否level = break?pattern_type = 本平台?是name_regexp 完整比對?是命中 → 開 WebView是不攔截,維持原頁是否否否Android:javaClass.simpleName;iOS:String(describing: type(of:))
這張圖回答「一個頁面要通過哪些判斷才會被攔」:由上往下逐關判斷,任何一關不符就走右邊「不攔截」。

比對前先以 id 去重。頁面名稱用類別的簡單名稱,正規表達式要對整個名稱做完整比對(不是部分包含)。例如 CancelSubscriptionFragment 只命中該頁,CancelSubscription.* 命中所有以 CancelSubscription 開頭的頁面,.* 命中所有頁面。正規表達式無法編譯就略過該列並記 log,不可閃退。

項目AndroidiOS
「頁面」指的是FragmentUIViewController
頁面名稱fragment.javaClass.simpleNameString(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 或中斷點時,照本節通用規則比對就會自動生效

攔截狀態機C11

攔截守門員有四個狀態:未就緒、重抓中、待命、攔截中;只有「待命」會觸發攔截。

攔截守門員有哪些狀態、什麼事件讓它轉移 未就緒重抓中待命攔截中登入/冷啟動抓取成功或失敗命中某 idback_url/error_url:移除 id 後重抓取 token 失敗 → 回待命頁面顯示但未命中/跳過:留在待命攔截中收到任何頁面顯示事件:忽略登出(任何狀態)
這張狀態圖回答「什麼事件讓守門員換狀態」:只有待命會因頁面顯示而進入攔截中;攔截中與重抓中一律忽略頁面事件;登出從任何狀態回到未就緒。

這是建議設計,用來避免兩個實際會發生的問題:(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/iOS)C12

Android 掛 onFragmentResumed+WebView.postUrl+shouldOverrideUrlLoading;iOS 掛共用 base VC 的 viewDidAppear+WKWebView POST+decidePolicyFor。

兩個平台把頁面事件接到守門員、再開 WebView 的位置 AndroidonFragmentResumed (recursive)iOSbase VC viewDidAppear攔截守門員C10 比對+C11 狀態android.webkit.WebViewpostUrl + shouldOverrideUrlLoadingWKWebViewPOST URLRequest + decidePolicyFor頁面顯示頁面顯示命中命中禁用 Chrome Custom Tabs禁用 SFSafariViewController;全螢幕+不可下滑
這張圖回答「兩個平台各自從哪裡接頁面事件、用什麼開 WebView」:左邊是頁面顯示事件來源,中間是共用的守門員,右邊是可攔截導向的 WebView 元件。

選「頁面顯示後覆蓋」而不是「跳頁前攔截」:返回鍵、切 tab、推播、deep link 不一定經過共用跳頁函式,跳頁前攔截會漏;頁面顯示事件涵蓋所有進入方式,會員完成後 WebView 關閉,人已在原本要去的頁面。WebView 必須能攔截導向,所以不能用 Chrome Custom Tabs 或 SFSafariViewController。

項目AndroidiOS
頁面顯示事件registerFragmentLifecycleCallbacks(cb, true) 的 onFragmentResumed(true=含子 Fragment)共用 base VC 的 viewDidAppear;沒有 base class 時改掛 navigationController(_:didShow:animated:) 並另處理 tab、modal
WebView 元件android.webkit.WebViewWKWebView
禁用Chrome Custom TabsSFSafariViewController
送出 POSTwebView.postUrl(authUrl, formBytes)URLRequest:httpMethod POST、Content-Type form-urlencoded、httpBody 表單
攔截導向shouldOverrideUrlLoading;onPageStarted 再判斷一次作保險decidePolicyFor 回 .cancel
設定javaScriptEnabled、domStorageEnabled、接受 cookie預設值
呈現全螢幕.fullScreen+isModalInPresentation = true
返回鍵/手勢canGoBack 時 goBack,否則不動作;不關閉不可下滑關閉;不放關閉按鈕
Android(Kotlin)片段
// 頁面顯示事件:在主 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 都可能收到同一個網址。

iOS(Swift)片段
// 頁面顯示事件:所有頁面共用的 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

提示條款紅點流程C13

「我的帳戶」以 status/warn 的 count 顯示紅點;點擊以 success_entry=terms 開 WebView,關閉後重查。

提示條款紅點從查詢到更新 我的帳戶頁17FIT API條款 WebViewGET status/warn?studio_iddata.count = MM > 0 顯示紅點與數字點擊 → GET member-tokenPOST /auth success_entry=terms會員填寫或按返回導向 back_url → 關閉再查 status/warn → 更新紅點
這張循序圖回答「紅點從查詢、點擊到更新經過哪些呼叫」:開 WebView 前一樣要取 member_token,關閉後再查一次 status/warn 更新數字。

提示條款不經過守門員的「攔截中」狀態,但條款 WebView 頁面屬於 SkipBreakCheck,開啟期間不會觸發強制條款攔截。

序執行者動作成功結果失敗處置
1App進入「我的帳戶」呼叫 status/warn取得 data.count不顯示紅點
2Appcount > 0 時「合約或問卷」顯示紅點與數字——
3會員點「合約或問卷」——
4App取 member_token,開 WebView,POST /auth:success_entry=terms,不送 user_flow_id、by_pass_single_item顯示條款列表頁導向 error_url(C14)
5會員填寫,或按「返回」導向 back_url—
6App攔下 back_url,關閉,重查 status/warn紅點更新維持原數字

錯誤碼與 App 處置C14

API 錯誤以 HTTP 400+code 回傳;開啟失敗以 error_url 的 error_code 帶回;每個碼都有固定處置。

每種錯誤碼最後導向 App 的哪個處置 17FIT APIHTTP 400+body codePOST /autherror_url 的 error_code00027 → 導回登入00003 → 重取 agent_tokenA2000/A2006–A2009 → 放行A2001/A2004 → 發生錯誤A2002 → 畫面逾時A2003 → 條款服務錯誤頁不會回 App關閉 WebView 後回待命
這張圖回答「每個錯誤碼最後 App 要怎麼處理」:上半是 17FIT API 的錯誤,下半是 POST /auth 的錯誤;A2003 是唯一不會回到 App 的情況。

提示文字為建議,App 可依自己的文案調整。error_url 帶回的 error_message 是給工程師看的中文訊息,不建議直接顯示給會員。

codemsg觸發條件App 處置
00027UserNotFound會員 token 缺少或無效依既有做法導回登入
00003Unauthorizedagent_token 無效依既有做法重取 agent_token
A2006InvalidStudioIdstudio_id 缺少或非數字記 log;不攔截/不顯示紅點
A2007InvalidPlatformplatform 不在允許值記 log;不攔截
A2008InvalidLevellevel 不是 warn/break記 log;不顯示紅點
A2009MemberNotInStudio會員不屬於這個品牌記 log;不攔截/不顯示紅點
A2000UnknowError伺服器未預期錯誤記 log;不攔截;下次重抓再試
error_code觸發條件App 處置
A2001欄位缺漏或格式錯(網址不合法、缺 member_token、break 缺 user_flow_id 或 by_pass_single_item)關閉;提示「發生錯誤,請再試一次」;回待命
A2002member_token 過期(超過 60 秒)或無效關閉;提示「畫面逾時,請再試一次」;下次頁面顯示重取 token
A2003沒帶 error_url不會回到 App;一律帶 error_url 即可避免
A2004auth_type 不是 member_token同 A2001

限制與非功能要求C15

member_token 60 秒內要用掉;同時最多 1 個條款 WebView;API 無快取,會員完成後下一次呼叫就反映。

token 時間窗、資料即時性、WebView 數量三個限制 取得 token t=0POST /autht=60 秒過期必須在此區間內送出之後送出 → A2002會員完成條款下一次 break-points已不含該條款伺服器無快取不需等待立即反映頁面快速連續切換攔截中忽略新事件最多 1 個 WebView
這張圖回答三個限制:上方是 token 的 60 秒時間窗;中間是完成條款到中斷表更新之間不需等待;下方是快速切頁時仍只會有一個 WebView。
項目規則驗證方式
member_token 時效60 秒;取得後立即送出取得後等 61 秒才送,應得 A2002
WebView 數量同時最多 1 個快速連續切頁只出現一個
資料即時性伺服器無快取;完成後下一次呼叫即不含該條款完成後立刻呼叫,回 [] 或少了該列
失敗策略抓取失敗放行斷網登入仍可使用
排序不依賴—
Android release保留 Fragment 類別名稱release 版 log 頁面名稱為原始名稱
舊版 App不攔截;新版上線即生效—

驗收條件C16

16 條 Given/When/Then,涵蓋攔截、去重、不重複觸發、逾時、錯誤、紅點、混淆、換帳號。

#GivenWhenThen
(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 是會員不屬於的品牌呼叫中斷表 APIHTTP 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

表格,無結構可圖示:各條互相獨立。

術語

詞定義
品牌 App17FIT 為單一品牌打包的原生 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_urlApp 指定的「完成」/「開啟失敗」網址,條款服務導向它們代表要關閉 WebView

未決事項與假設

項目目前假設誰決定影響
member_token API 正式路徑與回應暫定 GET /appapi/v1.0.0/approval-term/member-token?studio_id=,回 data.member_token17FIT 後端阻擋串接;可先用 mock 開發
測試環境 appapi 主機、條款服務網域、測試品牌與帳號由 17FIT 提供17FIT阻擋測試
單一條款直接進填寫頁(by_pass_single_item)目前未生效,App 照送 117FIT 後端不影響 App 實作
從背景回到前景是否重抓重抓17FIT PM影響 C09 一列
攔截中是否提供「登出」出口不提供17FIT PM影響 C12 返回鍵行為
back_url/error_url 實際網址https://<App 團隊控制的網域>/approve-term/back、…/errorApp 團隊合法 https 網址即可

出處