Skip to main content

Visitor App Integration

Embed the visitor chat experience in an Android, iOS, Flutter, or HarmonyOS app with a maintained WebView container, native permission handling, download callbacks, and lifecycle controls.

Current SDK version: 0.0.4.

Choose an integration​

OptionBest forWhat you own
Visitor SDK integrationNative app teams that need a ready-made container and platform callbacksSDK configuration, permissions, download handling, and app navigation
Embed the chat page in a visitor WebViewExisting WebView implementations that already have an AppBridge contractWebView setup, bridge injection, message validation, and native handlers

The SDK is the recommended starting point for a new mobile integration. Use the AppBridge guide when your app already owns the WebView and must keep its existing bridge protocol.

Supported platforms​

PlatformMinimum requirementPackage
AndroidminSdk 23io.github.twt-chat:visitor-sdk:0.0.4 from Maven Central
iOSiOS 15+TwtVisitorSDK from Swift Package Manager, tag 0.0.4
FlutterFlutter ≥ 3.44, Dart ^3.12.0visitor_flutter from Git, ref 0.0.4
HarmonyOSHarmonyOS 6.1 (API 23)+twt_visitor_sdk@0.0.4 from the ohpm central registry, or a local source/HAR dependency

Integration flow​

  1. Add the package for your platform and declare the permissions used by your app.
  2. Open an HTTPS visitor page and pass business parameters through the SDK query map.
  3. Subscribe to download, message, permission, and page-lifecycle callbacks.
  4. Report download completion or failure with the original requestId.
  5. Before switching accounts, close the visitor page and clear site data after the session is released.

Security and lifecycle essentials​

  • Use HTTPS only. Do not put passwords, cookies, AppSecrets, or long-lived tokens in the visitor URL.
  • Treat download URLs, callback payloads, and page events as untrusted input; validate them before handing them to native APIs.
  • Request microphone and camera permissions only when the user starts the related action.
  • On HarmonyOS, declare microphone and camera permissions in the host HAP as well as the HAR. Site-data cleanup clears the target origin's Web Storage; it does not clear cookies.
  • For the HarmonyOS bytecode HAR, keep strictMode.useNormalizedOHMUrl = true in the host project's build-profile.json5.
  • Deduplicate callbacks with requestId and messageId, and mark unfinished downloads as failed when a page is destroyed.
  • Test weak networks, backgrounding, lock-screen recovery, file selection, downloads, and WebSocket reconnects on real devices.

See Visitor SDK integration for platform code and configuration details.