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
| Option | Best for | What you own |
|---|---|---|
| Visitor SDK integration | Native app teams that need a ready-made container and platform callbacks | SDK configuration, permissions, download handling, and app navigation |
| Embed the chat page in a visitor WebView | Existing WebView implementations that already have an AppBridge contract | WebView 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
| Platform | Minimum requirement | Package |
|---|---|---|
| Android | minSdk 23 | io.github.twt-chat:visitor-sdk:0.0.4 from Maven Central |
| iOS | iOS 15+ | TwtVisitorSDK from Swift Package Manager, tag 0.0.4 |
| Flutter | Flutter ≥ 3.44, Dart ^3.12.0 | visitor_flutter from Git, ref 0.0.4 |
| HarmonyOS | HarmonyOS 6.1 (API 23)+ | twt_visitor_sdk@0.0.4 from the ohpm central registry, or a local source/HAR dependency |
Integration flow
- Add the package for your platform and declare the permissions used by your app.
- Open an HTTPS visitor page and pass business parameters through the SDK
querymap. - Subscribe to download, message, permission, and page-lifecycle callbacks.
- Report download completion or failure with the original
requestId. - 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 = truein the host project'sbuild-profile.json5. - Deduplicate callbacks with
requestIdandmessageId, 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.