# Flutter Release Notes

> Release notes for embed_flutter — what changed in each release, with upgrade steps.

URL: /embed/integration/flutter/flutter-releases
Markdown: /embed/integration/flutter/flutter-releases.md



# Flutter SDK — Release Notes [#flutter-sdk--release-notes]

`embed_flutter` · release history, newest first. Install the latest with `flutter pub add embed_flutter`; confirm the current version on [pub.dev](https://pub.dev/packages/embed_flutter).

***

## 0.2.0 [#020]

*Released: September 2026*

The native-parity release — config wiring, call/agent modes, back navigation, widget UX, and the action-intelligence runtime brought **in line with the Android and React Native SDKs**, plus an **on-device UI-graph cache** and a hardened **no-crash guarantee** for the host app. Verified live on a physical device. Upgrading from **0.0.x** requires a few code changes; work through the [upgrade steps](#upgrade-steps-00x--020) below.

### Breaking changes [#breaking-changes]

| Change                                                        | What to do                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Multi-agent (`flowName`) removed**                          | One integration is one agent (React / React Native parity). Drop `flowName` from `embedInitialize` / `embedEvent` / `embedTrack*`; `enabledRoutes` becomes a flat `List<String>`; per-flow `groupContinuity` / `groupDelays` collapse to `continuity:` / `buttonDelay:` (or the new `buttonVisibility` groups). Existing on-device caches stay valid; multi-agent apps must split into separate integrations. |
| **`embedInitialize` is the single, all-named intake**         | `embedInitialize(apiKey: …, appVersion: …, embedUrl: …)`. `apiKey` moved from positional to a **required named** parameter; `appVersion` is now **required** (`embedSetAppVersion()` and the `package_info_plus` auto-derivation are gone).                                                                                                                                                                   |
| **`EmbedProvider` removed**                                   | It only forwarded credentials and mounted an `EmbedWidget`. Call `embedInitialize` before `runApp` and wrap with `EmbedWidget` directly.                                                                                                                                                                                                                                                                      |
| **Host position/color props removed**                         | Delete `apiKey` / `embedUrl` / `primaryColor` / `rightPadding` / `bottomPadding` / `groupInsets` (and `EmbedButtonInset`) from `EmbedWidget`. FAB position (`widget_config.position`) and colors (`widget_config.colorPalette`) now come from the dashboard.                                                                                                                                                  |
| **Server-driven panels/cards render only in `workflow` mode** | A call started from the FAB (or the inactivity auto-trigger) is co-pilot and drops inbound panel frames. To keep panels, start from host code: `EmbedWidget.startCall(agentTriggerMode: AgentTriggerMode.WORKFLOW)`.                                                                                                                                                                                          |
| **`other_data` flags removed**                                | Move opt-outs to `action_config.flags.dataCapture` (snapshot/capture) and `EmbedWidget(usePlatformRouteAllowlist: true)` (route allowlist).                                                                                                                                                                                                                                                                   |

### New [#new]

* **`AgentTriggerMode` (co-pilot / workflow)** — host-declared at `EmbedWidget.startCall(agentTriggerMode:)` and latched per call; decides who owns the UI, whether panels render, and whether the avatar surface opens. Enum values `CO_PILOT` / `WORKFLOW` (identifier-for-identifier with Android); cross-SDK wire string is lowercase `copilot` / `workflow` (`mode.wire` / `parseAgentTriggerMode(...)`).
* **Host-crash safety net** — `embedInitialize` installs a **chained** `PlatformDispatcher.onError` guard that swallows only `livekit_client` / `flutter_webrtc` async errors and delegates everything else to the host's handler. Combined with type-coerced config and fully guarded timers/listeners, nothing the SDK does can crash the host app.
* **On-device UI-graph cache + sync** — screens are captured to a durable on-disk store (one JSON file per screen) and synced to the backend, gated by the dashboard `action_config.flags.dataCapture` master switch.
* **Visibility groups (`buttonVisibility`)** — `EmbedWidget(buttonVisibility: EmbedButtonVisibilityConfig(groups: [...]))`; each group gives a set of screens its own FAB continuity / delay / delay-policy (first matching group wins; a group's `screens` also join the allow-list).
* **New host controls** — `EmbedWidget.expandWidget()` (programmatic inverse of `collapseWidget()`, emits `agent_tap_to_open`; `startCall()` does not auto-expand) and `EmbedWidget.openAvatarScreen()` (opens the full-screen agent surface, starting a workflow call if none is running).
* **`action_config` / `widget_config` coverage completed** — `dataCapture` master gate; `awakeningEffect` / `activeBorderGlow` / `highlighting` / `clickTracking` kill-switches; all 26 `effects.*` tuning knobs; `position.*` and `agentAvatar.avatarSize` merged; `isCollapsed` opening state honored once per widget lifetime.
* **`call_id`** — latched from `/token` and sent flat on `agent_conversation_started` / `_ended` (Android parity).
* **System-back rung** — `back` now sweeps every reachable navigator (deepest-first, `PopScope`-aware), so nested / per-tab hosts no longer exhaust the find ladder.

### Fixed / clarified [#fixed--clarified]

* **Inactivity/nudge parity:** `nudgeDelay <= 0` = off; the popup shows only with a non-empty tooltip; captions suppress the auto-collapse and cancel a running countdown.
* **Widget UX:** one centered expanded-bar width; awakening plays only while no call is live; collapse artifacts fixed; a silent config revalidate no longer collapses an open bar; the avatar can no longer surface on a co-pilot call.
* **Memory (OOM guard):** the exploration log is now call-scoped and LRU-capped to 12 screens — it can no longer grow unbounded across calls in a long-lived host process.
* **No double submits:** a semantic tap/navigate that fired but produced zero observable evidence now fails after **one** attempt; rely on the backend `failure_reason: tap_had_no_observable_effect` to re-plan.
* **Secure fields:** capture-time (sticky) redaction — typed field contents no longer ride `text` or stable ids.
* **Config cache un-brick:** cached config is versioned with TTL + revalidate, so a stale cache can no longer hide the widget for the life of the install.

### Upgrade steps: 0.0.x → 0.2.0 [#upgrade-steps-00x--020]

1. Bump `embed_flutter` to `^0.2.0` in `pubspec.yaml`, then `flutter pub get` and (iOS) `pod install`. Re-check platform floors in the [Compatibility & Dependency Matrix](/embed/integration/flutter/flutter-dependencies).
2. Move credentials into `embedInitialize` (named, required): `embedInitialize('KEY', flowName: 'main')` → `embedInitialize(apiKey: 'KEY', appVersion: '1.0.0')`. Delete any `embedSetAppVersion()` call.
3. Drop `EmbedProvider` — call `embedInitialize` before `runApp` and wrap with `EmbedWidget` directly.
4. Flatten `enabledRoutes`: `{'main': ['home', 'account']}` → `['home', 'account']`.
5. Remove host position/color props (`apiKey` / `embedUrl` / `primaryColor` / `rightPadding` / `bottomPadding` / `groupInsets`) from `EmbedWidget`; set position and colors from the dashboard.
6. Replace `groupContinuity` / `groupDelays` with `continuity:` / `buttonDelay:`, or model per-screen behavior with `buttonVisibility` groups.
7. If you rely on server-driven panels/cards, start the call in workflow mode: `EmbedWidget.startCall(agentTriggerMode: AgentTriggerMode.WORKFLOW)`.
8. Rebuild fully and re-test a call on a real device.

***

## 0.0.20 and earlier [#0020-and-earlier]

The pre-parity line: floating voice-agent FAB (LiveKit), flow-scoped `enabledRoutes` with `flowName`, `EmbedProvider`, host-side FAB positioning (`rightPadding` / `bottomPadding`), the four event keys (`USER_DATA`, `SCREEN_STATE`, `CUSTOM_EVENT`, `ANALYTICS_DATA`), FAB pre-show delays (0.0.18), and Bluetooth-headset audio fixes (0.0.20). No agent trigger modes, no UI-graph cache, no crash guard, no visibility groups. If you are still on 0.0.x, upgrade via the steps above — the 0.0.x line is not maintained.

***

<CardGroup cols="1">
  <Card title="Back to Flutter integration" href="/embed/integration/flutter">
    Installation, native setup, &#x2A;*`embedInitialize`*&#x2A;, &#x2A;*`EmbedWidget`**, navigator integration, events, call control, and troubleshooting.
  </Card>
</CardGroup>

***

## Support [#support]

* **Docs:** [https://docs.revrag.ai](https://docs.revrag.ai/)
* **Email:** [contact@revrag.ai](mailto:contact@revrag.ai)
* **Dashboard:** [app.revrag.ai](https://app.revrag.ai)