跳至主要内容

TWT Visitor SDK

在 App 內打開訪客聊天頁面。宿主傳入 HTTPS 地址後,SDK 使用系統 WebView / WKWebView / ArkWeb 載入,並處理導航、權限、下載回傳與站點資料清理。

不使用 SDK、App 自建 WebView 打開訪客頁,見 訪客端 WebView 自行接入。

當前版本:0.0.4

平台要求整合
AndroidminSdk 23Maven Central:io.github.twt-chat:visitor-sdk:0.0.4
iOSiOS 15+SPM:https://github.com/TWT-Chat/twt-visitor-ios.git(tag 0.0.4,產品 TwtVisitorSDK)
FlutterFlutter ≥ 3.44,Dart ^3.12.0Git:https://github.com/TWT-Chat/visitor_flutter.git(ref 0.0.4)
HarmonyOSHarmonyOS 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 已示範)。


快速開始​

接入方只需搞清三件事:

  1. url(必填):控制台設定的 URL 地址,必須 HTTPS。
  2. 設定項:SDK 認識的欄位(isApp / language / theme / directChatId / newMessageSoundMode)。都有預設值,可不傳。
  3. 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
isAppfalsetrue 時寫 is_app=1App 內打開,訪客頁顯示關閉按鈕。false 不寫 is_app=0
languagezh-cn每次都寫 langen / zh-cn / zh-tw / ja / ko / de / fr / pt / ru / es / vi / th / id / ms / tl
themesystem每次都寫 themelight / dark / system。執行時 setTheme 只接受 light / dark
directChatIdnull有值時寫 direct=1&chatid=直達會話,並去掉 chat_id
newMessageSoundModeweb一般否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​

能力AndroidiOSFlutterHarmonyOS
打開獨立頁TwtVisitorSdk.startTwtVisitorSDK.presentVisitorFlutter.presentTwtVisitorSDK.start
嵌入TwtVisitorSdk.embedmakeEmbeddedControllerVisitorViewTwtVisitorSDK.embed + VisitorView
切換主題handle.setThemehandle.setThemeVisitorFlutter.setTheme / handle.setThemehandle.setTheme
下載回傳handle.reportDownloadStatus同左VisitorFlutter.reportDownloadStatushandle.reportDownloadStatus
關閉handle.close()handle.close()宿主 Navigator.pop();present 返回的 handle 在 iOS 上沒有關閉能力,改用宿主自建頁面handle.close()(僅限獨立頁)
清理站點資料TwtVisitorSdk.clearSiteDataTwtVisitorSDK.clearSiteDataVisitorFlutter.clearSiteDataTwtVisitorSDK.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:開始下載,完成後 reportDownloadStatus
  • onNewMessage:新訊息
  • onBack():返回鍵。true 表示宿主已處理
  • onPermissionResult:權限結果
  • onTitleChanged:網頁標題。SDK 不畫標題列,需要標題的宿主自行展示

iOS VisitorBridgeDelegate(弱引用)

  • visitorDownloadRequested(...)
  • visitorNewMessage()(可能重複)
  • visitorBack() -> Bool
  • visitorPermissionResult(...)
  • 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:開始下載,完成後 reportDownloadStatus
  • onNewMessage:新訊息(鈴聲模式為 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.startSDK 內置不用寫;需要二次確認時用 onBack() 攔
Android TwtVisitorSdk.embed宿主visitorView.handleBack { finish() }
iOS TwtVisitorSDK.present / makeEmbeddedController宿主自繪返回鍵 → handle.close() 或 dismiss
Flutter VisitorView宿主PopScope(canPop: false) + VisitorFlutter.handleBack()
Flutter VisitorFlutter.presentAndroid 內置 / iOS 宿主iOS 改用宿主自建頁面
HarmonyOS TwtVisitorSDK.startSDK 內建不用寫;需要二次確認時用 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、或排查返回沒生效時,協議只有三步:

  1. dispatch twt:visitor-event,detail.type = 'back'
  2. 頁面 300ms(iOS 350ms)內回包:置位 window.__twtVisitorBackConsumed,並通過 AppBridge 調 visitor_back_result(params.consumed = true 表示已處理,Flutter 外掛還會帶 requestId)
  3. 宿主讀 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
iOSWKWebView 的底部約束從 safeAreaLayoutGuide 改為 view.bottomAnchor + 可變常數,在 keyboardWillChangeFrame 中執行一次 layoutIfNeeded,不做動畫
Flutter平台檢視自行處理同一套 insets;宿主 Scaffold.resizeToAvoidBottomInset 保持預設(true)時,overlap 恆為 0,實際由 Flutter 縮小宿主容器
HarmonyOSArkWeb 使用 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。

鍵盤彈出時頁面閃一下?

見「行為說明 · 鍵盤與容器視覺」。容器收縮會重建繪製表面,這是已知代價。