embed_flutter 0.1.0

A powerful Flutter SDK that provides a powerful voice-enabled AI-agent functionality with real-time widget tree monitoring for screen context fetching and realtime voice communication.

Changelog

0.1.0

New public API

• Programmatic call control, available as statics on EmbedWidget and as top-level functions: startCall() / embedStartCall() (gated on FAB visibility), endCall() / embedEndCall() (not gated — a call can outlive the FAB), isCallActive / embedIsCallActive(), and collapseWidget() / embedCollapseWidget() (UI-only; the call keeps running).
• Exported EmbedLog developer diagnostics (opt-in via EmbedWidget(debug: true)) — explains why the agent button is or isn't visible on the current screen.

Fixes — call lifecycle & resource leaks

• Server-initiated disconnects now always tear the call down, including rooms that never published a local track. Teardown is re-entrancy-guarded, so agent_conversation_ended fires exactly once.
• The LiveKit Room, its listener, and its event subscription are now released on every teardown path — previously each call cycle leaked one room and two subscriptions.
• Removed a duplicate TrackSubscribedEvent handler that ran audio-route setup and a rebuild twice per subscribed track.
• Call teardown, startCall(), and the inactivity auto-trigger now share a single FAB-visibility definition. A backend is_live: false on config refresh and the host flipping showEmbedWidget to false both end an in-progress call.

Fixes — networking & events

• HttpClient is now closed after every API request; it previously leaked per call along with its connection pool.
• app_user_id is URL-encoded in query strings — emails with + or @ no longer corrupt the query. A null user id now sends empty instead of the literal string "null".
• All emitted event timestamps are now UTC (.toUtc()); they previously used device-local time with no offset suffix, skewing every event by the device's offset.
• embedInitialize's onResult no longer reports success on HTTP failure — success now means a usable config was obtained (fresh fetch or cached fallback).
• agent_conversation_ended now carries the real elapsed callDuration (previously omitted; the started event carried 0).
• Rage clicks now emit the flat event name rage_click (new SdkEventName.rageClick) instead of <elementId>_rage_click per element; elementId remains in the payload.
• embedTrackEvent no longer silently drops the reserved keys user_data, screen_state, and custom_event — it always sends an analytics-data event with the key as the event name; use embedEvent for typed events.
• embedOnAgent documentation corrected to the keys that actually fire: agent_conversation_started, agent_conversation_ended, popup_message_visible.

Behaviour changes

• embedClearStorageCache() is now a full logout: it clears stored keys for every flow (plus agent_data_*), queued analytics events, tracked form/tap data, and the in-memory app_user_id — and ends an active call, firing agent_conversation_ended.
• embedInitialize deliberately clears nothing: returning users keep their stored identity and the agent button reappears without the host re-sending a user_data event.

Tweaks

• Removed a dead token refresh on LiveKit reconnect — the server keeps the stored reconnect token current on its own.
• Bumped the SDK version reported to the backend (sdk_version) to 0.1.0.

0.0.20

Fixes

• Fixed agent audio dropping when a wired/Bluetooth headset is connected mid-call. The SDK no longer forces the audio route on a polling timer; it relies on LiveKit's native headset prioritization and reacts only to real device-change events.
• The inactivity tooltip no longer appears while a call is connecting/connected (previously it could pop up after the bar auto-collapsed).
• The inactivity tooltip now auto-dismisses on any user interaction (tap, scroll, drag), not only a FAB tap.

Features

• The expanded voice bar auto-collapses back to the FAB after a call connects while keeping the call live. Delay is configurable via collapsedView.collapsedTime (seconds, default 15s).
• Added a "live call" pulse around the collapsed FAB that appears only after the bar fully collapses and only while the user or agent is speaking. Color is configurable via colorPalette.pulseColor (default purple #B391F3).
• The default avatar fallback now uses a Lottie animation instead of the Material chat/person icons.

Tweaks

• Reduced the expanded bar height, Connect-button padding, and mute/end-call button sizes.
• Bumped the SDK version reported to the backend (sdk_version) to 0.0.20.

0.0.19

Fixes

• Relaxed the livekit_client constraint from the exact pin 2.6.5 back to ^2.5.3. The exact pin transitively forced meta ^1.17.0 (required by livekit_client 2.6.5), which broke pub get for apps on older Flutter SDKs that pin meta 1.16.0. The range lets pub select a compatible livekit_client version per app.

0.0.18

FAB pre-show delay & per-flow delay policy

• Added embedButtonDelayMs (on EmbedWidget / EmbedProvider) — global delay before the FAB appears after navigating to an enabled route. Default 0 (no delay).
• Added groupDelays (Map<String, EmbedButtonDelay>) — per-flow delay override with EmbedButtonDelayPolicy: perScreen, oncePerGroupEntry, oncePerAppSession. Falls back to embedButtonDelayMs.
• Added React-API aliases on EmbedButtonContinuity: continuous (= keepVisible) and perScreen (= reset), plus EmbedButtonContinuity.fromString / EmbedButtonDelayPolicy.fromString parsers.

Fixes

• Nudge/inactivity countdown now starts when the FAB becomes visible (after embedButtonDelayMs), not when the route is first entered.
• inactivity_behaviour: "auto_trigger" now maps to InactivityMode.AUTO_TRIGGER (auto-starts the call like start_call); previously it silently fell back to showing the popup. Added InactivityMode.fromBehaviour.
• FAB no longer renders off-screen on the app's initial/home route — position is recomputed once the screen size is available (post first layout) and on metrics changes.
• Fixed agentTapToOpen / agentTapToClose enum identifiers (backend values agent_tap_to_open / agent_tap_to_close unchanged).

Docs

• Added doc/fab-visibility-advanced.md (Flutter FAB visibility guide) and doc/embed-button-delay.md.

0.0.17

• Typewriter transcription panel: vertical expansion from bottom to top when type == "calculation" data received via LiveKit
• FAB positioning: widget_position (bottom-right, bottom-left, top-right, top-left) now respected from backend config
• Fixed bottomPadding and rightPadding not applying correctly to FAB position
• Bounce animation on FAB when transcription panel closes
• Analytics event names updated: agent_tap_to_open / agent_tap_to_close
• SdkEventName enum added for all internally-fired analytics event names (exported as public API)
• All public event APIs (embedEvent, embedTrackEvent, etc.) now return Future<bool> for send-success feedback
• EmbedRouteListener widget added for GoRouter / ShellRoute automatic route detection
• EmbedNavigatorObserver now accepts optional nameExtractor for GoRouter alias support
• Route matching now strips leading slashes — GoRouter paths (/home) match aliases (home)
• Cache-first config strategy restored in _fetchUIConfig with API fallback on cold start
• Removed all debug logs; all exceptions handled internally — zero crash guarantee for host app
• Removed dead _buildTranscriptionPanel overlay (superseded by inline vertical expansion)

0.0.16

• Graceful exception handling across SDK — zero crash guarantee
• Fixed event routing and SDK key resolution issues
• Stability Improvements

0.0.15

• Stability Improvements

0.0.14

• Minor Bug Fixes and Stability Improvements

0.0.13

• Minor Bug Fixes and Stability Improvements

0.0.12

• Added capability to send ANALYTICS_DATA event from screens which are not part of enabled routes.

0.0.11

• Added ANALYTICS_DATA event for tracking structured analytics events with a specific event identifier

0.0.10

• Minor Bug Fixes and UI improvements

0.0.9

• Added rightPadding and bottomPadding to set the initial position of Embed Widget

0.0.8

• Added onPermissionStatusChanged callback to recieve the permission status change events
• Minor Bug Fixes and Stability Improvements

0.0.7

• Minor Bug Fixes and Stability Improvements

0.0.6

• Bluetooth Headset Support added
• Added Inactivity Actions
• Minor Bug Fixes and Stability Improvements

0.0.5

• Added Multi Flow Support with enabledroutes

0.0.4

• Added Support for Re-initialisation of embed agent

0.0.3

• Added Support for Buttons
• Added Route based activation
• Added embedEvent call for user generated USER_DATA nd SCREEN_STATE events
• Added Embed Config Service for management of apiKey and embedUrl
• Improved widget context extraction
• Updated Documentation

0.0.2

• Removed the requirement for bluetooth permissions
• Updated License

0.0.1

• Initial release of Embedded Agent SDK
• Core functionality for automatic widget tree traversal
• Real-time widget monitoring with collapsible interface
• Comprehensive widget property extraction
• Cross-platform support for Android and iOS
• Example applications demonstrating SDK usage
• JSON output format for widget information
• Performance-optimized widget tree analysis