訪客端 App 接入

將訪客聊天能力嵌入 Android、iOS 或 Flutter App。SDK 統一處理 WebView 載入、原生權限、下載回傳、訊息事件與頁面生命週期。

選擇接入方式

方式	適用情境	宿主需要負責
訪客SDK接入文件	新接入的行動端專案，需要現成的容器與平台回呼	SDK 設定、權限宣告、下載處理與 App 導航
APP 內嵌訪客端 WebView	已自建 WebView，並需要沿用現有 AppBridge 協議	WebView 設定、橋接層注入、訊息驗證與原生處理

新專案建議優先使用 SDK；已有 WebView 與 AppBridge 協議的專案，請依第二篇文件接入，避免同時維護兩套橋接邏輯。

支援平台

平台	最低要求	依賴
Android	minSdk 23	Maven Central：io.github.twt-chat:visitor-sdk:0.0.1
iOS	iOS 15+	Swift Package Manager：TwtVisitorSDK
Flutter	Flutter ≥ 3.44，Dart ^3.12.2	Git：visitor_flutter

建議接入流程

1. 依平台加入依賴，並宣告 App 實際使用的權限。
2. 開啟 HTTPS 訪客頁，透過 SDK 的 query 傳入業務參數。
3. 監聽下載、訊息、權限與頁面生命週期回呼。
4. 使用原始 requestId 回傳下載成功或失敗狀態。
5. 切換帳號前關閉訪客頁，確認會話釋放後再清理網站資料。

安全與生命週期要點

• 僅使用 HTTPS，不要把密碼、Cookie、AppSecret 或長期 token 放進訪客 URL。
• 下載地址、回呼資料與頁面事件都應視為外部輸入，交給原生 API 前先驗證。
• 只有在使用者觸發對應操作時，才申請麥克風或相機權限。
• 使用 requestId、messageId 去重；頁面銷毀時，將未完成下載標記為失敗。
• 弱網、背景、鎖屏、檔案選擇、下載與 WebSocket 重連請在真機驗證。

完整的平台程式碼與設定請查看訪客SDK接入文件。