The Acme Shop example

The reference app that exercises every SDK feature, and how to run it against the fake backend or the live runtime.

apps/example_flutter (package acme_shop) is a small shop: a product grid, a cart, an embedded chat tab and a Demo page with switches for every SDK feature. It is the app used in the screenshots throughout these docs and the app the end-to-end tests drive.

What it shows

Feature	Where in the app
Launcher and chat sheet	Orange bubble, bottom right; the Chat tab embeds `KletsoChat` directly
Custom component	`acme.productCard` rendered with the shop’s own `ProductCard` widget, declared in `lib/kletso_components.dart`
Local actions	`open_product` (navigates and closes the chat), `open_checkout`, `open_hotel`; “Add to cart” on a chat card updates the real cart
Host data bindings	Cart progress and label published with `setHostData` under `/host/cart/...`
Context and events	`screen('product')`, `updateContext({'viewingSku': …})`, `track('add_to_cart', …)`
Proactive notifications	Demo page buttons fire `geofence_entered`, `payment_failed`, `order_shipped`; a “Simulate push” button feeds a payload to `handlePushPayload`
System notifications	`flutter_local_notifications` on Android and the browser Notification API on web, wired through `onSystemNotification`
Theming	Branded theme from `KletsoTheme.fromServer`, dark mode
Resilience	Switches to drop the socket every 6 events, expire the token once, duplicate every third frame, seed a 20-message history
Live runtime	A switch (and `--dart-define`s) point the app at `api.kletso.ai` or a local `wrangler dev`

Run it

cd apps/example_flutter
flutter run -d chrome                       # fake backend, no account needed
flutter run -d chrome \
  --dart-define=LIVE_API=https://api.kletso.ai \
  --dart-define=LIVE_KEY=kl_pub_dev_…       # live runtime

On Android use any emulator or device; the example enables core library desugaring for the notifications plugin. iOS builds need a Mac with Xcode; the SDK itself has no platform code.

Tests

Unit and widget tests: flutter test in each package (client, connection, transports, blocks, goldens, notification host).
Integration test: integration_test/chat_flow_test.dart walks launcher → message → surface → local action → host navigation, then geofence → banner → tap → chat. Runs on web through chromedriver (scripts/web-e2e.sh) and on Android with flutter test integration_test -d <device>.