跳至主要内容

訪客端 App 接入

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

選擇接入方式​

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

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

支援平台​

目前 SDK 版本:0.0.4。

平台最低要求依賴
AndroidminSdk 23Maven Central:io.github.twt-chat:visitor-sdk:0.0.4
iOSiOS 15+Swift Package Manager:TwtVisitorSDK(tag 0.0.4)
FlutterFlutter ≥ 3.44,Dart ^3.12.0Git:visitor_flutter(ref 0.0.4)
HarmonyOSHarmonyOS 6.1(API 23)+ohpm 中心倉庫:twt_visitor_sdk@0.0.4

HarmonyOS 宿主 HAP 必須在 module.json5 自行宣告麥克風 / 相機權限;bytecode HAR 要求 strictMode.useNormalizedOHMUrl = true。clearSiteData 僅清理目標 origin 的 Web Storage,不會刪除 Cookie。完整整合要求與限制請見訪客SDK接入文件。

建議接入流程​

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

安全與生命週期要點​

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

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