TWT Visitor SDK
在 App 內打開訪客聊天頁面。宿主傳入 HTTPS 地址後,SDK 使用系統 WebView / WKWebView / ArkWeb 載入,並處理導航、權限、下載回傳與站點資料清理。
不使用 SDK、App 自建 WebView 打開訪客頁,見 訪客端 WebView 自行接入。
當前版本:0.0.4
| 平台 | 要求 | 整合 |
|---|---|---|
| Android | minSdk 23 | Maven Central:io.github.twt-chat:visitor-sdk:0.0.4 |
| iOS | iOS 15+ | SPM:https://github.com/TWT-Chat/twt-visitor-ios.git(tag 0.0.4,產品 TwtVisitorSDK) |
| Flutter | Flutter ≥ 3.44,Dart ^3.12.0 | Git:https://github.com/TWT-Chat/visitor_flutter.git(ref 0.0.4) |
| HarmonyOS | HarmonyOS 6.1(API 23)+ | ohpm 中心倉庫:twt_visitor_sdk@0.0.4;也可本機依賴 SDK 原始碼倉庫的 visitor_oh/twt_visitor_sdk |
整合
Android
dependencyResolutionManagement {
repositories {
google()
mavenCentral()
}
}
dependencies {
implementation("io.github.twt-chat:visitor-sdk:0.0.4")
}
SDK 已合併 INTERNET、RECORD_AUDIO、CAMERA(required=false)。Android 9 及以下若下載到公共 Downloads,請自行添加 WRITE_EXTERNAL_STORAGE。
iOS
Xcode → File → Add Package Dependencies,填入:
https://github.com/TWT-Chat/twt-visitor-ios.git
Dependency Rule 選擇 Exact Version 0.0.4,產品勾選 TwtVisitorSDK。Deployment Target ≥ iOS 15。
在 Info.plist 中宣告:
<key>NSMicrophoneUsageDescription</key>
<string>用於發送語音訊息</string>
<key>NSCameraUsageDescription</key>
<string>用於拍攝並傳送照片或影片</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>用於儲存會話圖片</string>
<key>UIFileSharingEnabled</key>
<true/>
<key>LSSupportsOpeningDocumentsInPlace</key>
<true/>
請保持 App Transport Security 預設設定。公開 API 須在主執行緒呼叫。
Flutter
dependencies:
visitor_flutter:
git:
url: https://github.com/TWT-Chat/visitor_flutter.git
ref: 0.0.4
flutter pub get
Android 端需設定 mavenCentral()(見上方 Android 整合)。若使用 RepositoriesMode.PREFER_SETTINGS,還須保留 Flutter Engine 倉庫 https://storage.googleapis.com/download.flutter.io。iOS 端無需再添加 SPM,按 iOS 一節設定 Info.plist 即可。
HarmonyOS
最低系統要求為 HarmonyOS 6.1(API 23)。在入口模組的 oh-package.json5 中從 ohpm 中心倉庫安裝:
{
"dependencies": {
"twt_visitor_sdk": "0.0.4"
}
}
中心倉庫提供的是 bytecode HAR,宿主專案的 build-profile.json5 必須保持 strictMode.useNormalizedOHMUrl = true(DevEco 範本預設值),關閉後會在編譯時報錯:00306046 Bytecode HAR [twt_visitor_sdk] not supported when useNormalizedOHMUrl is not true。
若不使用中心倉庫,可依賴原始碼目錄 "twt_visitor_sdk": "file:../twt_visitor_sdk"(即 visitor_oh/twt_visitor_sdk),或直接執行 ohpm install ./libs/twt_visitor_sdk-0.0.4.har。授權為 Apache-2.0(Android / iOS 目前為 Proprietary)。
HAR 已宣告 ohos.permission.INTERNET、ohos.permission.MICROPHONE、ohos.permission.CAMERA。需要使用者授權的權限不能僅靠 HAR 的宣告生效,宿主 HAP 還必須在自己的 module.json5 中再次宣告 MICROPHONE / CAMERA(範例 visitor_oh/entry/src/main/module.json5 已示範)。
快速開始
接入方只需搞清三件事:
url(必填):控制台設定的 URL 地址,必須 HTTPS。- 設定項:SDK 認識的欄位(
isApp/language/theme/directChatId/newMessageSoundMode)。都有預設值,可不傳。 query:給訪客頁的業務參數。SDK 不解釋 key,只負責 UTF-8 編碼拼進 URL。匿名訪客可以不傳。
不要自己拼 ?a=1&b=2。不要把密碼、Cookie、AppSecret 或長期 token 放進 URL。
最少打開(只傳 url)時 SDK 拼出:
控制台設定的 URL 地址?lang=zh-cn&theme=system
lang=zh-cn、theme=system 由預設設定寫入。App 內若要顯示關閉按鈕,再設 isApp = true。
Android
val handle = TwtVisitorSdk.start(
this,
VisitorConfig(url = "控制台設定的 URL 地址"),
)
start 會先校驗設定,URL 為空或不是 HTTPS 時拋 IllegalArgumentException,宿主需要 try / catch。校驗通過後打開 VisitorActivity 並返回 VisitorHandle。傳入非 Activity Context 時會自動加上 FLAG_ACTIVITY_NEW_TASK。下載、新訊息等回呼見「回呼與事件」。
要自己畫標題列就用 embed,拿到裸 WebView 放進自己的佈局:
val visitorView = TwtVisitorSdk.embed(this, config, listener)
// 自己的工具列(返回鍵 + 標題)在最上面,visitorView 放它下面
範例頁是普通頁面:頂部系統狀態列,下面是自繪的 56dp 工具列(返回鍵 + 網頁標題),再下面是 WebView。targetSdk 35+ 強制 edge-to-edge,宿主需要給根佈局補 WindowInsetsCompat.Type.systemBars() 的 padding(範例裡是 applySystemBarInsets()),否則工具列會被狀態列壓住。
宿主要把 onBackPressed(visitorView.handleBack(::finish))、onResume / onPause、onDestroy(visitorView.destroySession())、onActivityResult、onRequestPermissionsResult 轉發給它。完整範例見 android/sample/.../EmbeddedVisitorActivity.kt。
iOS
打開獨立頁(全螢幕裸 WebView):
import TwtVisitorSDK
let config = VisitorConfiguration(
url: URL(string: "控制台設定的 URL 地址")!
)
let handle = try TwtVisitorSDK.present(from: self, configuration: config, delegate: self)
.fullScreen 呈現,沒有系統返回手勢,SDK 也不畫任何容器 UI、不處理返回,也不轉發頁面裡的 close。要退出只能靠宿主自繪的按鈕調 handle.close()(或自己 dismiss)。dismiss 之後 handle 失效。
需要標題列和返回鍵就自己包一層容器:
let controller = try TwtVisitorSDK.makeEmbeddedController(configuration: config, delegate: self)
let container = UINavigationController(rootViewController: controller)
// iOS 26 的導覽列是玻璃的,會採樣 WebView 底色,給不透明 appearance 才穩。
let appearance = UINavigationBarAppearance()
appearance.configureWithOpaqueBackground()
container.navigationBar.standardAppearance = appearance
container.navigationBar.scrollEdgeAppearance = appearance
controller.navigationItem.leftBarButtonItem = UIBarButtonItem(
image: UIImage(systemName: "chevron.backward"),
primaryAction: UIAction { [weak container] _ in container?.dismiss(animated: true) }
)
present(container, animated: true)
網頁標題通過 visitorTitleChanged(_:) 回填到 controller.navigationItem.title。
Flutter
宿主自建頁面(推薦):Scaffold + 自己的 AppBar,WebView 只佔內容區:
import 'package:visitor_flutter/visitor_flutter.dart';
final config = VisitorConfiguration(url: '控制台設定的 URL 地址');
Scaffold(
appBar: AppBar(title: Text(_webTitle ?? '在線客服')), // _webTitle 來自 titleChanged
body: VisitorView(configuration: config),
)
VisitorView 必須放在有確定尺寸的父佈局中(如 Scaffold 的 body、Expanded、SizedBox)。
傳入新的 configuration(URL、query、isApp、language、theme、directChatId)會重建平台檢視並載入新地址;只改 newMessageSoundMode 不重新載入頁面。執行期間切主題用 VisitorFlutter.setTheme,不要改 configuration。
打開獨立原生頁:
final handle = await VisitorFlutter.present(configuration: config);
Android 上它是 SDK 的 Activity,系統返回鍵由 SDK 處理(頁面優先,未消費才關)。iOS 上它是全螢幕裸 WebView,既沒有系統返回手勢,SDK 也不給關閉入口,建議改用上面的宿主自建頁面,否則使用者退不出去。
HarmonyOS
打開獨立頁(裸 WebView,無標題列,系統返回由 SDK 處理):
import { common } from '@kit.AbilityKit';
import { TwtVisitorSDK, VisitorConfig, VisitorHandle } from 'twt_visitor_sdk';
const config = new VisitorConfig();
config.url = '控制台設定的 URL 地址';
config.isApp = true;
const handle: VisitorHandle | null = TwtVisitorSDK.start(
getContext(this) as common.UIAbilityContext,
config,
listener,
);
if (handle === null) {
// URL 或 query 無效,SDK 不會打開頁面
}
與 Android 不同,URL 無效時 start 會返回 null,不會拋出例外。
使用獨立頁時,在宿主入口 import 一次頁面檔案,確保已註冊具名路由:
import 'twt_visitor_sdk/src/main/ets/pages/VisitorPage';
需要自繪標題列時,使用 embed + VisitorView:
const session = TwtVisitorSDK.embed(config, listener);
// 自己的標題列(返回鍵 + 標題)在最上面,VisitorView 放在下方
VisitorView({ session: session })
SDK 不繪製任何容器介面;網頁標題由 VisitorBridgeListener.onTitleChanged 回傳。自繪返回鍵和系統返回都呼叫 session.handleBack(() => { ... }):SDK 先詢問頁面(300ms),頁面未處理且 WebView 無歷史記錄時才執行回呼。完整範例見 visitor_oh/entry/src/main/ets/pages/EmbeddedPage.ets。
設定項
四端欄位相同。SDK 會把部分設定寫成 URL query,並覆蓋 query 裏的同名 key。
| 欄位 | 預設 | 進 URL? | 說明 |
|---|---|---|---|
url | 空(必填) | 基址 | 控制台設定的 URL 地址,僅 HTTPS。HTTP、file、javascript、自訂 scheme、帶 user:pass 的地址會被拒絕 |
query | 空 Map | 原樣拼接 | 業務參數,見下一節。不要手拼 ?a=1 |
isApp | false | true 時寫 is_app=1 | App 內打開,訪客頁顯示關閉按鈕。false 不寫 is_app=0 |
language | zh-cn | 每次都寫 lang | en / zh-cn / zh-tw / ja / ko / de / fr / pt / ru / es / vi / th / id / ms / tl |
theme | system | 每次都寫 theme | light / dark / system。執行時 setTheme 只接受 light / dark |
directChatId | null | 有值時寫 direct=1&chatid= | 直達會話,並去掉 chat_id |
newMessageSoundMode | web | 一般否 | web:頁面播放;native:宿主在新訊息回呼中播放。走 JS 橋,不靠 URL(Flutter Android present() 會額外帶 new_message_sound_mode) |
寫入順序:url 自帶 query → config.query → is_app / lang / theme / direct+chatid。後者覆蓋前者。
query 業務參數
query 是透明 Map,SDK 只編碼拼接,不解釋 key。匿名訪客可以整份不傳。is_app / lang / theme / direct / chatid 用設定項,不要再寫進 query。
綁定業務使用者時:
query = mapOf(
"sbs" to "user-123",
"sbs_mm" to signature,
"ranstr" to randomStr,
"name" to "張三",
)
| 參數 | 必填? | 含義 |
|---|---|---|
sbs | 綁使用者時必填 | 業務系統中的使用者唯一 ID,訪客頁用它識別已登入客戶 |
sbs_mm | 有 sbs 就要 | sbs 的簽名 |
ranstr | 有簽名就要 | 參與簽名的隨機串 |
name | 可選 | 訪客姓名,進入客服工作臺展示 |
nickname | 可選 | 訪客暱稱 |
email | 可選 | 訪客郵箱 |
phone | 可選 | 訪客手機號 |
customer_remark | 可選 | 客戶備註,隨登入提交給客服側 |
ext_fk_id | 可選 | 已有訪客 ID,用來續上該訪客的歷史會話 |
referer | 可選 | 來源頁 URL(也認 referer_url),客服側顯示為來源鏈接 |
source_title | 可選 | 來源頁標題 |
不要傳 visitor_id、source=android / ios / flutter:訪客頁不讀。App 標識用設定項 isApp=true。
會話 API
| 能力 | Android | iOS | Flutter | HarmonyOS |
|---|---|---|---|---|
| 打開獨立頁 | TwtVisitorSdk.start | TwtVisitorSDK.present | VisitorFlutter.present | TwtVisitorSDK.start |
| 嵌入 | TwtVisitorSdk.embed | makeEmbeddedController | VisitorView | TwtVisitorSDK.embed + VisitorView |
| 切換主題 | handle.setTheme | handle.setTheme | VisitorFlutter.setTheme / handle.setTheme | handle.setTheme |
| 下載回傳 | handle.reportDownloadStatus | 同左 | VisitorFlutter.reportDownloadStatus | handle.reportDownloadStatus |
| 關閉 | handle.close() | handle.close() | 宿主 Navigator.pop();present 返回的 handle 在 iOS 上沒有關閉能力,改用宿主自建頁面 | handle.close()(僅限獨立頁) |
| 清理站點資料 | TwtVisitorSdk.clearSiteData | TwtVisitorSDK.clearSiteData | VisitorFlutter.clearSiteData | TwtVisitorSDK.clearSiteData |
下載狀態:started / completed / failed / cancelled。requestId 必須與請求一致。可選欄位:path / progress / sourceUrl / mimeType / bytes / errorCode / message。iOS 相冊完成路徑為 photos://localIdentifier。
清理結果:SUCCESS / INVALID_URL / UNSUPPORTED / IN_USE / FAILED(Flutter 為小寫駝峯)。IN_USE 表示仍有會話佔用該 host。
HarmonyOS 的 clearSiteData 僅清理目標 origin 的 Web Storage:ArkWeb 沒有依站點刪除 Cookie 的 API,SDK 不會清空全域 Cookie。
切換帳號:關閉頁面 → 等待銷毀完成 → clearSiteData 成功 → 再打開下一個帳號。
回呼與事件
回呼在主執行緒。請按 requestId / messageId 去重;頁面銷毀時把未完成的下載標為 failed。
Android VisitorBridgeListener
onDownloadRequested:開始下載,完成後reportDownloadStatusonNewMessage:新訊息onBack():返回鍵。true表示宿主已處理onPermissionResult:權限結果onTitleChanged:網頁標題。SDK 不畫標題列,需要標題的宿主自行展示
iOS VisitorBridgeDelegate(弱引用)
visitorDownloadRequested(...)visitorNewMessage()(可能重複)visitorBack() -> BoolvisitorPermissionResult(...)visitorTitleChanged(_:):網頁標題。SDK 不畫標題列,需要標題的宿主自行展示
Flutter VisitorFlutter.events
無監聽時不緩存事件,進入頁面即 listen,離開時 cancel。
late final StreamSubscription<VisitorBridgeEvent> sub;
@override
void initState() {
super.initState();
sub = VisitorFlutter.events.listen((e) {
switch (e.type) {
case 'downloadRequested':
break;
case 'titleChanged': // payload: {'title': ...}
break;
case 'backRequested': // 原生返回:系統返回鍵 / iOS 邊緣手勢
unawaited(_handleBack());
break;
case 'webReady':
case 'webLoadFailed':
case 'close':
case 'new_message':
break;
}
});
}
@override
void dispose() {
sub.cancel();
super.dispose();
}
事件名:downloadRequested、webReady、webLoadFailed、close、backRequested、new_message、titleChanged、theme。
backRequested 是原生側識別的返回(Android 系統返回鍵、iOS 邊緣手勢)。它只上報,不關頁面;跟系統返回一樣走上面的 handleBack() 判斷。(範例裡的 unawaited 來自 dart:async。)
嵌入式頁面處理返回:
PopScope(
canPop: false,
onPopInvokedWithResult: (_, __) async {
if (!await VisitorFlutter.handleBack()) {
if (context.mounted) Navigator.of(context).pop();
}
},
child: VisitorView(configuration: config),
)
handleBack() == true 表示頁面已消費返回(例如從會話詳情回到列表)。首次載入失敗可呼叫 VisitorFlutter.reload()。
HarmonyOS VisitorBridgeListener
onDownloadRequested:開始下載,完成後reportDownloadStatusonNewMessage:新訊息(鈴聲模式為native時)onBack():返回鍵。true表示宿主已處理onPermissionResult:權限結果onTitleChanged:網頁標題。SDK 不畫標題列,需要標題的宿主自行展示
HarmonyOS 的返回 / 下載 / 上傳範例方法:
| 情境 | 範例方法 | 位置 |
|---|---|---|
| 獨立頁返回 | VisitorPage.onBackPress() → VisitorHandle.handleBack() → VisitorView.handleBackRequest() | twt_visitor_sdk/src/main/ets/pages/VisitorPage.ets |
| 嵌入頁返回 | 宿主 onBackPress() / 自繪返回鍵 → session.handleBack(() => ...) | entry/src/main/ets/pages/EmbeddedPage.ets |
| 下載 | DemoListener.onDownloadRequested() → DemoDownloadManager.handleDownload() → copyToTarget() → handle.reportDownloadStatus() | entry/src/main/ets/service/DemoListener.ets、DemoDownloadManager.ets |
| 上傳 | VisitorView.onShowFileSelector() → pickFromAlbum() / pickDocuments() → stageForWeb() → finishPicked() | twt_visitor_sdk/src/main/ets/pages/VisitorPage.ets |
| 新訊息鈴聲 | DemoListener.onNewMessage() → DemoRingTonePlayer.play()(通知音訊通道,資源缺失或播放失敗時改用震動) | entry/src/main/ets/service/DemoListener.ets、DemoRingTonePlayer.ets |
上傳由 SDK 內部接管,宿主只需在 module.json5 宣告麥克風 / 相機權限;下載必須由宿主自行實作,SDK 只將 URL 交給宿主。
返回處理
訪客頁是單頁應用:返回可能只是關掉圖片預覽,或從會話詳情退回列表,所以要先問頁面——頁面消費了就留在頁面,沒消費才關容器。SDK 只負責轉發和上報,關不關頁面由宿主決定。
| 入口 | 返回由誰處理 | 宿主程式碼 |
|---|---|---|
Android TwtVisitorSdk.start | SDK 內置 | 不用寫;需要二次確認時用 onBack() 攔 |
Android TwtVisitorSdk.embed | 宿主 | visitorView.handleBack { finish() } |
iOS TwtVisitorSDK.present / makeEmbeddedController | 宿主 | 自繪返回鍵 → handle.close() 或 dismiss |
Flutter VisitorView | 宿主 | PopScope(canPop: false) + VisitorFlutter.handleBack() |
Flutter VisitorFlutter.present | Android 內置 / iOS 宿主 | iOS 改用宿主自建頁面 |
HarmonyOS TwtVisitorSDK.start | SDK 內建 | 不用寫;需要二次確認時用 onBack() 攔截 |
HarmonyOS TwtVisitorSDK.embed + VisitorView | 宿主 | session.handleBack(() => router.back()) |
範例程式碼:android/sample/.../EmbeddedVisitorActivity.kt、ios/Sample/TwtVisitorSample/MainViewController.swift、visitor_flutter/example/lib/main.dart。
Android
獨立頁不用寫程式碼:系統返回鍵和系統手勢返回都會進入 Activity 的返回回呼 → 問頁面 → 頁面未消費 → 關 Activity。要在關閉前加一道確認(例如「確認結束諮詢」),實現 onBack() 返回 true 即可:
override fun onBack(): Boolean {
showExitConfirmDialog()
return true // 已攔下,SDK 不再關閉頁面
}
嵌入頁把同樣的邏輯接到宿主 Activity 上,自繪返回鍵也調它:
override fun onBackPressed() {
visitorView.handleBack { finish() }
}
backButton.setOnClickListener { visitorView.handleBack { finish() } }
物理返回鍵、系統手勢返回、自繪返回鍵都走這一個入口——handleBack 內部已經問過頁面(300ms),宿主不用再判斷一次。
iOS
原生 SDK 不接管返回,也不轉發頁面裡的 close。返回按鈕和左邊緣手勢都由宿主容器提供,兩者調同一個關閉方法:
let visitor = try TwtVisitorSDK.makeEmbeddedController(configuration: config, delegate: self)
visitor.navigationItem.leftBarButtonItem = UIBarButtonItem(
image: UIImage(systemName: "chevron.backward"),
style: .plain,
target: self,
action: #selector(closeVisitor)
)
let container = UINavigationController(rootViewController: visitor)
container.modalPresentationStyle = .fullScreen
// 左邊緣手勢返回
let edgeBack = UIScreenEdgePanGestureRecognizer(target: self, action: #selector(handleEdgeBack(_:)))
edgeBack.edges = .left
edgeBack.cancelsTouchesInView = false // 不打斷點擊和滾動
container.view.addGestureRecognizer(edgeBack)
present(container, animated: true)
@objc private func handleEdgeBack(_ gesture: UIScreenEdgePanGestureRecognizer) {
guard gesture.state == .ended else { return }
closeVisitor()
}
@objc private func closeVisitor() { dismiss(animated: true) }
要點:
- SDK 已經把 WebView 自帶的
allowsBackForwardNavigationGestures關掉,宿主的邊緣手勢才不會被 WebView 搶走;宿主自己不要再打開它 present出來的全螢幕裸頁面沒有導覽列也沒有手勢,使用者唯一的出口是宿主給的按鈕,頁面內關閉按鈕在 iOS 原生端不生效- 想「先問頁面再關」(頁面裡有圖片預覽/會話詳情),目前原生 iOS 沒有公開介面,只能直接關
Flutter
PopScope(
canPop: false, // 先別讓系統直接 pop
onPopInvokedWithResult: (didPop, result) {
if (!didPop) unawaited(_handleBack());
},
child: VisitorView(configuration: config),
)
Future<void> _handleBack() async {
if (await VisitorFlutter.handleBack()) return; // 頁面消費,留在頁面
if (mounted) Navigator.of(context).pop();
}
三種返回都接到 _handleBack():
| 來源 | 怎麼到宿主 |
|---|---|
| AppBar 返回箭頭 | 預設走 Navigator.maybePop,被 PopScope(canPop: false) 攔下後觸發回呼 |
| Android 物理返回鍵 / 系統手勢返回 | 同上,走 Flutter 的返回回呼 |
| iOS 邊緣手勢、原生側識別的返回 | backRequested 事件 |
頁面裡的關閉按鈕走 close 事件,直接 pop。外掛內部等頁面 300ms(iOS 350ms),超時按未消費處理。
HarmonyOS
獨立頁不用寫程式碼:VisitorPage 的 onBackPress 會先詢問頁面,未處理再退出。若要在關閉前加一道確認,讓 listener.onBack 返回 true。
嵌入頁將系統返回和自繪返回鍵接到同一個方法:
onBackPress(): boolean {
const session = this.session;
if (session === null) {
return false; // 沒有會話時交給系統預設處理,避免停留在錯誤頁
}
session.handleBack(() => {
this.getUIContext().getRouter().back();
});
return true;
}
頁面內的關閉按鈕:獨立頁由 SDK 轉發並退出;嵌入頁不轉發,由宿主自己的關閉 / 返回按鈕處理。
頁面側協議
自己接 WebView、或排查返回沒生效時,協議只有三步:
- dispatch
twt:visitor-event,detail.type = 'back' - 頁面 300ms(iOS 350ms)內回包:置位
window.__twtVisitorBackConsumed,並通過 AppBridge 調visitor_back_result(params.consumed = true表示已處理,Flutter 外掛還會帶requestId) - 宿主讀
window.__twtVisitorBackConsumed或等visitor_back_result;false/ 超時就關容器
頁面側細節見 訪客端 WebView 自行接入 的「系統返回」。
行為說明
導航
同域 HTTPS 留在容器內;跨域 HTTPS 使用系統瀏覽器;其他 scheme 攔截。
存儲
Cookie、LocalStorage、IndexedDB 預設持久化。第三方 Cookie 與混合內容關閉。
權限
僅同域 HTTPS 的麥克風 / 相機採集會進入系統授權,跨域一律拒絕。
例外:Flutter 在 Android 上的嵌入頁只允許麥克風,相機會被拒絕。需要拍攝時請使用獨立頁或原生 SDK。
HarmonyOS 僅允許目前訪客頁 origin 的採集請求;宿主 HAP 必須自行宣告麥克風 / 相機權限。
檔案選擇
走系統 / WebKit 檔案選擇器,支援單選與多選。HarmonyOS 由 VisitorView.onShowFileSelector() 接管:圖片 / 影片使用相簿選擇器(pickFromAlbum),文件使用檔案選擇器(pickDocuments);HEIC 等不符合頁面 accept 的原圖,會經 stageForWeb() 轉為 JPEG 後再交給頁面。
下載
WebView 下載與頁面內下載都會回呼給宿主,由宿主執行後再回傳狀態。HarmonyOS 的 ArkWeb 內建下載會由 SDK 取消,只將 URL 交給宿主,避免檔案存入暫存目錄;範例見 VisitorView.setupDownloadDelegate() 與 DemoDownloadManager.handleDownload()。
返回
見「返回處理」。範例:獨立頁 VisitorPage.onBackPress(),嵌入頁 EmbeddedPage.onBackPress() → session.handleBack()。
標題列
四端容器都是裸 WebView,SDK 不畫標題列。需要標題的宿主通過 onTitleChanged / visitorTitleChanged / titleChanged 事件拿到網頁標題,自己在容器外面繪製 AppBar。iOS 用 KVO 盯 webView.title,單頁應用切換會話後改標題也會回呼;Android 走 onReceivedTitle,HarmonyOS 走 onTitleReceive,同樣會隨標題變化觸發。
鍵盤與容器視覺
訪客頁使用 100dvh 固定視口,鍵盤避讓依靠容器收縮,四端實作不同:
| 平台 | 作法 |
|---|---|
| Android | 將 ime insets 作為 padding 加在 VisitorView(FrameLayout)上,VisitorKeyboardAvoidance 使用 WindowInsetsAnimationCompat 逐幀插值;收起鍵盤時,結合 isVisible(ime) 與 insets 的到達順序判斷方向;API < 30 交給系統 adjustResize |
| iOS | WKWebView 的底部約束從 safeAreaLayoutGuide 改為 view.bottomAnchor + 可變常數,在 keyboardWillChangeFrame 中執行一次 layoutIfNeeded,不做動畫 |
| Flutter | 平台檢視自行處理同一套 insets;宿主 Scaffold.resizeToAvoidBottomInset 保持預設(true)時,overlap 恆為 0,實際由 Flutter 縮小宿主容器 |
| HarmonyOS | ArkWeb 使用 setKeyboardAvoidMode(RESIZE),頁面銷毀時恢復宿主原本的模式 |
已知代價:改變容器尺寸會重建 WebKit / Blink 的繪製表面,鍵盤彈出時可能看到一幀閃爍;若要徹底消除,需要 H5 使用 visualViewport 自行避讓。Android 的 insets 必須加在父容器上,WebView 本身的 padding 不參與 H5 佈局。
容器與 WebView 背景跟隨頁面配色:淺色 #F5F7F9、深色 #191919(VisitorChromePolicy.resolvePageBackground、VisitorView 的 paletteColor),避免調整尺寸與首幀出現白底;iOS 另外設定 isOpaque = false,並清空 scrollView 背景。
iOS 獨立頁關閉 scrollView.bounces / alwaysBounceVertical / alwaysBounceHorizontal,固定視口頁面才不會被拖出回彈空白。
常見問題
為什麼打開失敗?
檢查地址是否為 HTTPS,以及 query 的 key 是否合法。iOS 還會校驗 directChatId。
為什麼清不掉站點資料?
會話仍在會返回 IN_USE。先關閉全部相關頁面,等銷毀完成後再清理。iOS 按 host 匹配 WebKit 記錄,同一記錄下的兄弟子域可能一併清除,但不會做全局清空。
嵌入的 Flutter 頁面高度為 0?
給 VisitorView 明確高度,例如包在 Expanded 裏。
如何直達某個會話?
設定 directChatId。
如何綁定已登入使用者?
在 query 裏傳 sbs、sbs_mm、ranstr。不要傳 visitor_id。
如何在 App 內顯示關閉按鈕?
isApp = true,頁面會顯示關閉按鈕。點擊後:Flutter 會收到 close 事件(宿主自己 pop);HarmonyOS 獨立頁由 SDK 退出,嵌入頁不轉發;原生 Android / iOS 目前不轉發,需要宿主自繪返回鍵。
主題如何跟隨系統?
初始使用 theme = system。執行期間只能切到 light 或 dark。
弱網、後台、鎖屏、WebSocket?
請在真機上驗證。SDK 不額外封裝網路層。
Android 打開時拋 IllegalArgumentException?
start / embed 會立刻校驗 URL,空值、非 HTTPS、帶 user:pass 都會拋。在按鈕回呼裡 try / catch,把錯誤提示留在表單裡,不要讓它冒到主執行緒。
自繪工具列被狀態列壓住?
targetSdk 35+ 強制 edge-to-edge。給根佈局補 WindowInsetsCompat.Type.systemBars() 的 padding(範例裡的 applySystemBarInsets())。
自繪標題不居中?
左右兩側留等寬的空間(返回鍵和佔位同寬),標題才會落在螢幕中線上。
iOS 獨立頁退不出去?
present 是全螢幕裸 WebView,系統返回手勢和關閉按鈕都沒有。請由宿主按鈕呼叫 handle.close() / dismiss,或改用 makeEmbeddedController 搭配宿主自行建立的容器。原生 iOS SDK 不轉發 H5 close。
HarmonyOS 獨立頁打不開,記錄提示找不到 VisitorPage?
在宿主入口 import 一次 twt_visitor_sdk/src/main/ets/pages/VisitorPage,才會註冊具名路由。
HarmonyOS 的 start 為什麼返回 null?
URL / query / directChatId 校驗失敗。空值、非 HTTPS、帶 user:pass、無效連接埠都會返回 null,不會打開頁面。
HarmonyOS 為什麼清不掉 Cookie?
ArkWeb 沒有依站點刪除 Cookie 的 API。clearSiteData 僅刪除目標 origin 的 Web Storage,不會清空全域 Cookie;切換帳號前請先讓頁面完成退出。
HarmonyOS 麥克風 / 相機不顯示授權提示?
HAR 的權限宣告不會單獨生效,宿主 HAP 的 module.json5 必須再次宣告 ohos.permission.MICROPHONE / ohos.permission.CAMERA。
是否支援截圖橋、圖片剪貼簿?
不提供截圖橋。圖片剪貼簿不保證所有系統 WebView 都能使用。
ohpm install twt_visitor_sdk 提示套件不存在?
確認版本號填寫為 0.0.4(中心倉庫依精確版本取得),並確認該版本已通過審核。可用 ohpm info twt_visitor_sdk 查詢可用版本。
HarmonyOS 編譯時出現 00306046 Bytecode HAR not supported?
HAR 是 bytecode 套件,宿主專案的 build-profile.json5 必須保持 strictMode.useNormalizedOHMUrl = true。
鍵盤彈出時頁面閃一下?
見「行為說明 · 鍵盤與容器視覺」。容器收縮會重建繪製表面,這是已知代價。