跳至主要内容

訪客端 WebView 自行接入

App 用自己的 WebView / WKWebView 打開訪客頁,不接入 Visitor SDK 時按本文對接。HarmonyOS 自建 ArkWeb 的橋接、權限與返回寫法,可直接參考 visitor_oh/twt_visitor_sdk/src/main/ets/pages/VisitorPage.ets。

優先使用 訪客 SDK。本文只覆蓋「自行載入頁面」。


打開頁面​

url 填 控制台設定的 URL 地址,必須 HTTPS。業務參數拼在 query 上,自行做 UTF-8 編碼。不要把密碼、Cookie、AppSecret 或長期 token 放進 URL。

App 內打開建議帶 is_app=1,訪客頁纔會顯示關閉按鈕。

控制台設定的 URL 地址?is_app=1&lang=zh-cn&theme=system

Android:

webView.settings.javaScriptEnabled = true
webView.settings.domStorageEnabled = true
webView.loadUrl(buildVisitorUrl())

iOS:

let config = WKWebViewConfiguration()
config.preferences.javaScriptEnabled = true
webView.load(URLRequest(url: visitorURL))

只加載 URL 即可聊天。關閉按鈕、原生下載、原生鈴聲、Android 錄音授權需要注入 AppBridge,見下文。


query 參數​

參數必填?含義
is_appApp 內建議 11 時顯示關閉按鈕,並走 App 返回邏輯
lang可選,預設頁面語言介面語言:en / zh-cn / zh-tw / ja / ko / de / fr / pt / ru / es / vi / th / id / ms / tl
theme可選,預設 lightlight / dark / system
direct直達會話時必填 1直達開關,沒有它時 chatid 無效
chatid直達會話時必填目標會話 ID(也認 chat_id)
sbs綁使用者時必填業務系統中的使用者唯一 ID
sbs_mm有 sbs 就要sbs 的簽名
ranstr有簽名就要參與簽名的隨機串
name可選訪客姓名
nickname可選訪客暱稱
email可選訪客郵箱
phone可選訪客手機號
customer_remark可選客戶備註
ext_fk_id可選已有訪客 ID,用來續歷史會話
referer可選來源頁 URL(也認 referer_url)
source_title可選來源頁標題
new_message_sound_mode可選native:新訊息由 App 響鈴;不傳則頁面自己響

不要傳 visitor_id。source=webview 效果等同 is_app=1,傳一個即可。


WebView 要求​

  • 啓用 JavaScript、DOM Storage
  • Cookie / LocalStorage 預設持久化,不要無故清掉(清掉會丟訪客身份)
  • 僅加載 HTTPS;系統 ATS / Cleartext 保持預設
  • 同域麥克風、相機:在系統中宣告權限(Android RECORD_AUDIO / CAMERA;iOS NSMicrophoneUsageDescription / NSCameraUsageDescription;HarmonyOS 在宿主 HAP 的 module.json5 宣告 MICROPHONE / CAMERA)
  • 附件選擇走 WebView 檔案選擇器,各端都要自行接入(HarmonyOS 為 onShowFileSelector),見「附件上傳」
  • 同域 HTTPS 留在 WebView;跨域 HTTPS 用系統瀏覽器
  • 容器與 WebView 背景設為頁面配色(淺色 #F5F7F9 / 深色 #191919),避免首幀和尺寸變化時閃白
  • iOS 關閉 scrollView.bounces / alwaysBounceVertical / alwaysBounceHorizontal,固定視口頁面才不會被拖出空白
  • 鍵盤避讓加在容器上,見「鍵盤與視口」

鍵盤與視口​

訪客頁使用 100dvh 固定視口,鍵盤彈出時頁面本身不會讓位;容器必須收縮,否則輸入框會被遮住。

  • 容器收縮:將鍵盤 insets 加在容器上,縮小 WebView 高度。Android 必須加到父 FrameLayout,WebView 本身的 setPadding 不參與 H5 佈局計算;ArkWeb 使用 setKeyboardAvoidMode(KeyboardAvoidMode.RESIZE);iOS 調整 WKWebView 的底部約束。
  • 不要依賴捲動避讓:iOS 關閉 scrollView.bounces / alwaysBounceVertical / alwaysBounceHorizontal,固定視口頁面被拖動時只會整體回彈並露出白底。
  • 底色:容器和 WebView 背景設為頁面配色(淺色 #F5F7F9 / 深色 #191919),iOS 還要設定 isOpaque = false + backgroundColor = .clear,避免收縮與首幀閃白。
  • 已知代價:改變尺寸會重建 WebKit / Blink 的繪製表面,鍵盤彈出時可能有一幀閃爍。若要徹底消除,需要 H5 使用 visualViewport 自行避讓,並保持容器尺寸不變。

標題列與返回​

不使用 SDK 時,標題列、返回鍵、關閉按鈕全部由 App 自行繪製,訪客頁不會在 App 內繪製任何容器介面。

標題

監聽 WebView 的標題變化,顯示在自己的導覽列中:

  • Android:WebChromeClient.onReceivedTitle
  • iOS:使用 KVO 觀察 webView.title。只靠 didFinish 不夠,該方法只能取得初始標題;單頁應用切換會話後還會再次修改標題

返回

使用者觸發返回(Android 系統返回鍵、iOS 邊緣手勢、自繪返回按鈕)時,先詢問頁面(見「系統返回」),頁面未處理再關閉 WebView 或退出目前頁面。

iOS 邊緣手勢

要加入自己的左邊緣滑動手勢,先將 webView.allowsBackForwardNavigationGestures 設為 false。WKWebView 內建的返回手勢會攔截螢幕邊緣的觸控,宿主的 UIScreenEdgePanGestureRecognizer 收不到事件,表現就是「手勢沒有反應」。

Android 安全區域

targetSdk 35+ 強制 edge-to-edge。自繪的導覽列要放在 systemBars() inset 下方(為根佈局加上 padding),否則會被狀態列遮住。

附件上傳(檔案選擇器)​

訪客頁使用 <input type="file"> 選擇附件。系統不會替你彈出選擇器:Android 要覆寫 onShowFileChooser,iOS 要覆寫 runOpenPanelWith,HarmonyOS 要在 Web 的 onShowFileSelector 中返回 true 並自行開啟選擇器。遺漏時不會報錯,使用者點擊後可能「沒有反應」或「選取後是空的」。

Android​

private var pendingCallback: ValueCallback<Array<Uri>>? = null
private val REQ_FILE = 1001

webView.webChromeClient = object : WebChromeClient() {
override fun onShowFileChooser(
view: WebView,
filePathCallback: ValueCallback<Array<Uri>>,
params: FileChooserParams,
): Boolean {
// 先取消上一次尚未回傳的結果,否則下一次點選可能不會彈窗
pendingCallback?.onReceiveValue(null)
pendingCallback = filePathCallback
val intent = params.createIntent().addCategory(Intent.CATEGORY_OPENABLE)
intent.putExtra(Intent.EXTRA_ALLOW_MULTIPLE, params.mode == FileChooserParams.MODE_OPEN_MULTIPLE)
return runCatching {
startActivityForResult(intent, REQ_FILE)
true
}.getOrElse {
pendingCallback = null
filePathCallback.onReceiveValue(null)
true
}
}
}

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
super.onActivityResult(requestCode, resultCode, data)
if (requestCode != REQ_FILE) return
val callback = pendingCallback ?: return
pendingCallback = null
if (resultCode != Activity.RESULT_OK) return callback.onReceiveValue(null)
val uris = mutableListOf<Uri>()
data?.data?.let(uris::add) // 單選
data?.clipData?.let { clip -> // 多選
for (i in 0 until clip.itemCount) clip.getItemAt(i).uri?.let(uris::add)
}
callback.onReceiveValue(uris.takeIf { it.isNotEmpty() }?.toTypedArray())
}

要點:

  • 一定要重用 FileChooserParams.createIntent()。它會帶上頁面的 accept 和目前 Activity 的讀取權限。自行拼接 ACTION_GET_CONTENT 或使用第三方圖庫也能彈窗,但頁面讀不到回傳 URI 的位元組,表現就是「選了但空」。
  • 每個 onShowFileChooser 必須且只能回傳一次 onReceiveValue。null 等於使用者取消。遺漏回傳時,頁面的 input 會永久卡在等待狀態。
  • 只讀取 intent.data 和 intent.clipData。如果宿主自有選圖/選檔頁面,結果只在 EXTRA_STREAM,要先把檔案拷貝到自己的沙箱,再用 FileProvider 的 content:// URI 回傳。
  • 不要回傳 file://。宿主通常會關閉 allowFileAccess,頁面讀不到,且 Android 7 起還可能拋出 FileUriExposedException。
  • 回傳的 URI 必須交給發起 startActivityForResult 的同一個 Activity。讀取權限只授予它,換 Activity 就會失效。
  • 如果宿主自己的 Activity 已經處理 onActivityResult,注意 requestCode 不要與現有值衝突。

iOS​

func webView(_ webView: WKWebView,
runOpenPanelWith parameters: WKOpenPanelParameters,
initiatedByFrame frame: WKFrameInfo,
completionHandler: @escaping ([URL]?) -> Void) {
let picker = UIDocumentPickerViewController(
forOpeningContentTypes: [.item], asCopy: true) // 直接給沙箱副本
picker.allowsMultipleSelection = parameters.allowsMultipleSelection
picker.delegate = self
self.openPanelCompletion = completionHandler
present(picker, animated: true)
}

func documentPicker(_ controller: UIDocumentPickerViewController, didPickDocumentsAt urls: [URL]) {
defer { openPanelCompletion = nil }
guard let completion = openPanelCompletion else { return }
// 安全作用域外的 URL 先拷貝進 tmp,否則 WebKit 讀到 0 位元組
let copied = urls.compactMap(copyToTemporaryDirectory)
completion(copied.isEmpty ? nil : copied)
}

func documentPickerWasCancelled(_ controller: UIDocumentPickerViewController) {
openPanelCompletion?(nil)
openPanelCompletion = nil
}

要點:

  • 不實作 runOpenPanelWith 就沒有檔案選擇器,點擊「上傳」什麼都不會發生(WKUIDelegate 只宣告還不夠,必須真的實作這個方法)。
  • completion 只能呼叫一次,取消時傳入 nil。
  • iCloud、檔案 App 的檔案屬於安全作用域。不呼叫 startAccessingSecurityScopedResource() 或不先拷貝到 NSTemporaryDirectory(),WebKit 拿到 URL 也讀不到內容,上傳會是 0 位元組。使用 asCopy: true 最省事。
  • 想使用相簿選圖(PHPickerViewController)或拍照也可以,但取得的不是檔案 URL,要先寫入暫存檔再回傳,不能把 UIImage 或相簿 item 識別碼直接丟給 completion。

HarmonyOS​

範例方法:VisitorView.onShowFileSelector() → pickFromAlbum() / pickDocuments() → stageForWeb() → finishPicked()(見 visitor_oh/twt_visitor_sdk/src/main/ets/pages/VisitorPage.ets)。

Web({ src: url, controller: this.controller })
.onShowFileSelector((event: OnShowFileSelectorEvent) => {
this.onShowFileSelector(event);
return true; // true:宿主自行開啟選擇器;false 會使用 ArkWeb 預設實作
})

private onShowFileSelector(event: OnShowFileSelectorEvent): void {
const accept = event.fileSelector.getAcceptType();
const multiple = event.fileSelector.getMode() === FileSelectorMode.FileOpenMultipleMode;
// 圖片 / 影片使用相簿;文件選擇器無法選取相簿內容,HEIC 原圖也會被頁面捨棄
const wantsMedia = accept.some((t: string) => t.startsWith('image/') || t.startsWith('video/'));
if (wantsMedia) {
this.pickFromAlbum(event.result, accept, multiple);
} else {
this.pickDocuments(event.result, multiple);
}
}

要點:

  • 必須 return true。返回 false 時,ArkWeb 會使用內建選擇器,回傳給頁面的是它自己的暫存路徑,宿主無法取得檔案。
  • event.result.handleFileList(uris) 只能回傳一次。取消時回傳空陣列 [],遺漏回傳會讓頁面的 input 永久等待。
  • 相簿回傳的 file://media/Photo/... 只有一次性授權,請先用 fs.copyFile 複製到沙箱,再用 fileUri.getUriFromPath 產生 Web 可讀取的 URI。
  • 頁面 accept 沒有 heic / heif 時,相簿原圖必須先用 image.createImageSource + packing 轉為 JPEG 再回傳,否則選取後會是空的。
  • 文件選擇器提供的 file://docs/... 也必須先複製到沙箱,不能直接將 docs URI 交給頁面。
  • 相簿 / 相機權限必須在宿主 HAP 的 module.json5 宣告,HAR 中的宣告不會單獨生效。

各端都要注意​

  • HEIC:訪客頁 accept 沒有 heic / heif 時,iOS 相簿原圖、部分 Android 相簿直接提供 HEIC,URI 有效但頁面會靜默丟棄。要支援相簿原圖,回傳前先轉成 JPEG(或另存一份 JPEG)。
  • 檔案大小:SDK 不會代為壓縮,超大檔案由頁面自行處理;宿主可以在回傳前檢查上限並提示使用者。

選取後是空檔案,怎麼查​

現象常見原因
點擊上傳沒有反應iOS 沒實作 runOpenPanelWith;Android 上一次 onReceiveValue 沒有回傳;HarmonyOS onShowFileSelector 沒有返回 true 或沒有回傳 handleFileList
選了檔案,input 仍然是空的取消或 data 為空時回傳了 null;URI 只在 EXTRA_STREAM 裡但沒有讀取
有檔名,上傳卻是 0 位元組Android 回傳了 file://;URI 的讀取權限不在目前 Activity;iOS 安全作用域 URL 沒有拷貝
選了相簿圖片卻沒有進清單HEIC 被頁面的 accept 過濾

AppBridge​

頁面通過 window.AppBridge.call(method, params, callback) 調 App。頁面每次加載前注入下面腳本(建議 atDocumentStart,不要等 onPageFinished)。

(function () {
window.__TWT_VISITOR_BRIDGE_CONFIG__ = { newMessageSoundMode: 'web' };
window.AppBridge = {
_callbacks: {},
call: function (method, params, callback) {
var id = callback ? 'cb_' + Date.now() + '_' + Math.random().toString(16).slice(2) : null;
if (callback) this._callbacks[id] = callback;
var msg = JSON.stringify({ method: method, params: params || {}, callback: id });
if (window.AppBridgeChannel_native) {
window.AppBridgeChannel_native.postMessage(msg);
} else if (window.webkit && window.webkit.messageHandlers.AppBridgeChannel) {
window.webkit.messageHandlers.AppBridgeChannel.postMessage(msg);
}
return Promise.resolve({ status: 'sent', callbackId: id });
},
invokeCallback: function (id, result) {
var cb = this._callbacks[id];
if (cb) { cb(result); delete this._callbacks[id]; }
}
};
})();

Android 註冊名爲 AppBridgeChannel_native 的 JavascriptInterface(方法名 postMessage)。

iOS 註冊名爲 AppBridgeChannel 的 WKScriptMessageHandler。HarmonyOS 使用 javaScriptProxy 註冊同名通道,範例見 VisitorView 的 proxy 與 bridgeScript。

訊息 JSON:{ "method": "...", "params": {}, "callback": "cb_..." }。

頁面會調用的方法​

method何時App 做什麼
close使用者點頁面關閉按鈕關閉 WebView / 退出當前頁
download儲存圖片、視頻、檔案下載 params.url;完成後見下方回傳
new_message收到新訊息且鈴聲爲 native播放提示音。params 可能含 messageId / chatId
android_recording_permissionAndroid 錄音申請麥克風。回傳 { code: 1, data: { permission: true/false } }
visitor_back_result頁面應答了返回見「系統返回」

不注入 Bridge 時:關閉按鈕無效果;下載走瀏覽器;鈴聲由頁面自己播。

下載回傳​

download 的 params:

欄位含義
url檔案地址
typeimage / video / 其他
fileName建議檔案名
mimeTypeMIME
requestId本次下載 ID

有 callback 時,下載結束調用:

window.AppBridge.invokeCallback(callbackId, {
code: 1,
data: { requestId: '...', status: 'completed' }
})

status:completed / failed / cancelled。失敗時 code 用 0。

HarmonyOS 的 ArkWeb 會自行開始下載,必須在 WebDownloadDelegate.onDownloadStart 中攔截並呼叫 item.cancel(),再將 item.getUrl() / getMimeType() / getSuggestedFileName() 交給宿主,範例見 VisitorView.setupDownloadDelegate()。若不取消,仍可下載,但檔案會存入 ArkWeb 暫存目錄,系統也會顯示一則無關的「下載完成」提示。

若要把鈴聲交給 App,注入時把 newMessageSoundMode 設爲 'native',或 URL 帶 new_message_sound_mode=native。


系統返回(可選)​

使用者按系統返回時,先問頁面(關閉預覽、從會話退回列表):

window.dispatchEvent(new CustomEvent('twt:visitor-event', {
detail: { type: 'back', payload: {} }
}))

頁面收到後會將處理結果寫入兩處:將 window.__twtVisitorBackConsumed 設為 true/false,並透過 AppBridge 呼叫 visitor_back_result(params.consumed)。宿主只需讀取其中一處即可。約 300ms(iOS 350ms)內沒有回應就視為「未處理」,不要無限等待。

Android:

webView.evaluateJavascript(
"(function(){window.__twtVisitorBackConsumed=false;" +
"window.dispatchEvent(new CustomEvent('twt:visitor-event',{detail:{type:'back',payload:{}}}));})()",
null,
)
Handler(Looper.getMainLooper()).postDelayed({
webView.evaluateJavascript("!!window.__twtVisitorBackConsumed") { raw ->
if (raw != "true") finish() // 頁面未處理才關閉
}
}, 300)

iOS:

let js = "window.__twtVisitorBackConsumed=false;" +
"window.dispatchEvent(new CustomEvent('twt:visitor-event',{detail:{type:'back',payload:{}}}))"
webView.evaluateJavaScript(js) { _, _ in
DispatchQueue.main.asyncAfter(deadline: .now() + 0.35) {
webView.evaluateJavaScript("!!window.__twtVisitorBackConsumed") { result, _ in
if (result as? Bool) != true { dismiss(animated: true) }
}
}
}

HarmonyOS(範例 VisitorView.handleBackRequest()):

this.controller.runJavaScript(
"window.__twtVisitorBackConsumed=false;" +
"window.dispatchEvent(new CustomEvent('twt:visitor-event',{detail:{type:'back',payload:{}}}))",
);
setTimeout(() => {
this.controller.runJavaScript('!!window.__twtVisitorBackConsumed').then((raw: string) => {
if (raw !== 'true') {
this.getUIContext().getRouter().back(); // 頁面未處理才關閉
}
});
}, 300);

自繪返回鍵、Android 系統返回鍵、iOS 邊緣手勢、HarmonyOS 系統返回(onBackPress)都連接到同一個函式。iOS 記得先停用 allowsBackForwardNavigationGestures,否則邊緣手勢會被 WebView 攔截。

執行中切主題(僅 light / dark):

window.dispatchEvent(new CustomEvent('twt:visitor-event', {
detail: { type: 'themeChanged', payload: { theme: 'dark' } }
}))