truhuddle_widget 1.0.0
truhuddle_widget: ^1.0.0 copied to clipboard
Native TruHuddle customer support for Flutter with live messaging, AI agents, voice notes and workspace-controlled permissions.
TruHuddle Widget for Flutter #
Native Android and iOS support, opened from your app's own button as a full-screen page. Home, Messages and Profile follow the TruHuddle web widget, including its League Spartan font, Hugeicons, brand gradient, compact messages and voice waves. This package does not use a WebView and does not add a floating launcher.
Install #
Requires Flutter 3.41 / Dart 3.11 or newer.
dependencies:
truhuddle_widget: ^1.0.0
Create a session on your backend #
Native integration is available on Startup and Enterprise. Add your Android package / iOS bundle identifier in Widget settings. Your backend, not your app, authenticates the customer and chooses their stable ID, name and verified email.
// Server only: npm install @retinalabsllc/truhuddle-widget
import { createServerClient } from '@retinalabsllc/truhuddle-widget/server';
const support = createServerClient({
publicKey: process.env.SDK_PUBLIC_KEY!,
secretKey: process.env.SDK_SECRET_KEY!,
});
const session = await support.createWidgetSession({
packageName: 'com.example.app',
user: { id: signedInUser.id, name: signedInUser.name, email: signedInUser.email },
});
// Return session to this authenticated customer only. Cache-Control: private, no-store.
Protect this endpoint using your existing app login. Never accept an unchecked customer ID from the request body. A package allowlist is an integration label, not proof that an installed app is genuine; verify app attestation on your own backend when appropriate. Neither developer key belongs in a mobile binary.
Open support #
import 'package:truhuddle_widget/truhuddle_widget.dart';
await TruhuddleWidget.open(context, options: TruhuddleOptions(
appId: 'YOUR_PUBLIC_APP_ID',
packageName: 'com.example.app',
getSession: () async {
final sessionJson = await yourSignedInApi.createSupportSession();
return TruhuddleSession.fromJson(sessionJson);
},
));
You can also push TruhuddleWidget(options: options) through your existing
Navigator. For direct widget mounting, use a Flutter key tied to the signed-in
customer ID. Pop/unmount the page on logout or customer changes. The session provider
must always return the current, same authenticated customer's session for this
page. Verified sessions expire after 15 minutes; the package renews through this
callback and never falls back to anonymous identity on failure. Session tokens
stay in memory, never in URLs, logs or persistent storage.
Platform permissions #
Android (android/app/src/main/AndroidManifest.xml):
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
Use Android API 24 or newer. Microphone permission is requested only after the customer taps the enabled record button. Gallery images use the platform picker.
iOS (ios/Runner/Info.plist), with iOS 13 or newer:
<key>NSMicrophoneUsageDescription</key>
<string>Record voice notes for your support conversation.</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Share a photo with your support team.</string>
Do not enable cleartext HTTP or disable TLS validation for production. baseUrl
accepts HTTPS service origins; local HTTP is limited to loopback / Android emulator
addresses for development. The package targets Android and iOS, not Flutter Web.
Workspace-controlled behavior #
- Widget enabled/disabled state, plan checks, bans, tenant isolation and native package permissions are enforced by the server on every API request.
- Workspace light/dark/system theme, color, greeting, logo and branding are used.
- The supported attachment audience controls image and voice-note buttons. Uploads and downloads use authorized customer endpoints and private workspace storage.
- AI badges follow the workspace switch. Internal team notes are never returned.
- Customer lists show up to 20 recent conversations; history is bounded to the most recent 100 messages, loaded in 11-message pages. Older pages load on demand.
- New replies follow the scroll only when already near the bottom. Otherwise a floating count lets the customer jump to the new messages.
- Name/email passed by the developer remain read-only. No agent last-seen timestamp is exposed to the customer. The support header shows connected/available status.
- Sound and in-app message notice switches apply to the current page. They do not request OS push-notification permission or provide background push delivery.
Voice notes and images #
Voice recordings use AAC in an MP4/M4A container, capped at 90 seconds. Playback uses decoded audio waveforms and position-based highlighting, with seeking. Private recordings are downloaded only when played and temporary files are removed when their player/page is disposed. Supported playback codecs depend on the device OS; an unsupported recording shows an error rather than a fake player. Images open in an in-app full-screen zoomable preview. Select a supported image under 4 MB; recordings must be below 8 MB. The backend independently checks size, file signatures, plan, permissions and conversation ownership.
Live updates #
The page requests a short-lived, customer-scoped edge ticket, then connects to the Cloudflare WebSocket with the ticket in the subprotocol, not the URL. Events carry invalidation IDs; the actual messages are fetched from the authenticated API. After a disconnect or app resume, the page renews access and reloads authorized state. The API also supports an SSE fallback. App inactivity stops the live stream and recordings; five-minute activity heartbeats expire visitor presence.
Example and publishing #
example/lib/main.dart shows the complete button integration with a backend
session callback. To run it as a standalone example, generate its platform shells
with cd example && flutter create --platforms=android,ios ., then add the platform
permissions above before running it. Use your app's normal authentication there, never developer keys.
From packages/truhuddle_widget:
flutter pub get
flutter pub publish
Publishing is a manual action. Review the listed files and confirm the upload in
your terminal. The npm package is published separately from
packages/truhuddle-widget with npm publish --access public --registry=https://registry.npmjs.org/.
League Spartan is included under its bundled SIL Open Font License in
assets/fonts/OFL.txt; package source is MIT licensed.