heardock_flutter 0.1.0
heardock_flutter: ^0.1.0 copied to clipboard
In-app feedback for Flutter. Drop a native bottom sheet into your app, collect context (version, device, screen) automatically, and read every note in one private inbox.
heardock_flutter #
In-app feedback for Flutter. A native form — full screen by default, bottom sheet on request — context that travels with the note, and an offline queue that does not lose the user's words.
Alpha (
0.1.0). This package is the UI half of the Flutter SDK and depends onheardock_corefor transport, context, and the queue. Swift and the Web Widget come next.
What you get #
- One call to open a themed form:
Heardock.show(context). - Full-screen page by default; opt into the bottom sheet with one config field.
- Feedback centre with read-only team replies (
Heardock.open). - Category (bug / idea / question / praise) and message. No email field.
- Automatic context: app version, build, platform, OS, device, locale, screen.
- English + Simplified Chinese built in; follows the device locale.
- Offline-first: network failures are saved on the device and retried with backoff (1s → 5s → 30s → 2m → 10m, five attempts).
- No PII by default. Device and locale collection can be turned off.
- Material 3, light/dark inherited from your app; optional accent override.
Requirements #
- Flutter 3.27+ (Dart 3.6+) — the UI uses
Color.withValues. - Android or iOS. Web support is intentionally out of scope for the MVP.
Install #
flutter pub add heardock_flutter
Configure (once) #
import 'package:heardock_flutter/heardock_flutter.dart';
void main() {
Heardock.configure(
HeardockConfig(
publicKey: 'hd_pub_ab12cd34',
// Default: https://heardock.com. For the local Next.js app:
// baseUrl: 'http://localhost:3000',
collect: const CollectOptions(device: true, locale: true, screen: true),
theme: const HeardockTheme(
primaryColor: Color(0xFFE4572E),
borderRadius: 16,
),
),
);
runApp(const MyApp());
}
The publishable key (hd_pub_…) is safe to embed in a client. Never use a
secret key in an app.
Open the form #
ElevatedButton(
onPressed: () => Heardock.show(context),
child: const Text('Feedback'),
)
Heardock.show pushes a full-screen page by default. Choose the presentation
once in config, or override it for a single call:
Heardock.configure(HeardockConfig(
publicKey: 'hd_pub_ab12cd34',
// page (default) or sheet
presentation: FeedbackPresentation.sheet,
));
// Per-call override; config stays page.
await Heardock.show(context, presentation: FeedbackPresentation.sheet);
Returns a FeedbackResult? when the user finishes. In sheet mode it is a
bottom sheet on phones and a centered dialog on tablets/desktop (shortest side
≥ 600). In page mode it is a full-screen route with a 640px content column on
wide screens.
final result = await Heardock.show(context);
if (result != null) {
// result.queued == true → stored locally, will retry
// result.displayReference → e.g. "HS-7F3K2"
}
Feedback centre #
Use Heardock.open(context) for the single entry point: it fetches the
device's history, then decides what to show.
Heardock.open(context); // list -> thread (read-only); compose via the list's +
| Fetch result | What opens |
|---|---|
| Empty list | The form, directly |
| One or more notes | The feedback list |
| Fetch fails, nothing queued | Error + Retry + Send feedback; no auto-form |
show() skips that check and always opens the form. The centre reloads after
every submission, so a new note is listed immediately — including one that had
to be queued: it appears as a "Queued" row without a manual pull-to-refresh,
and opening it shows the local copy until it is sent.
- Threads are read with the install's device token; users cannot reply, they send a new note.
- Tapping a row opens the thread immediately ("Your feedback"): the note card and context come from the list entry, and the replies area renders skeleton cards until the request finishes. If it fails, the page keeps the note and offers an inline Retry; no replies gets a proper empty state.
- History and threads are cached in memory for 5 minutes, so reopening a note is instant; pull-to-refresh on the list forces a network read (and clears the thread cache). Opening a thread paints the cached copy, then revalidates in the background at most once every 30 seconds — re-entering the same note repeatedly does not hit the network.
- The app bar's delete action is a soft delete from the device's point of view: the note disappears from this phone after a confirmation, while the server keeps it and its replies for the operator's inbox. The row disappears from the list immediately, and a tombstone filters out a lagging list response. Replies cannot be deleted on their own. Queued notes are removed from the device only.
- Locally the SDK keeps the token, seen marks, the offline queue, and — unless
persistHistory: false— a 7-day snapshot of the list/threads so a cold start paints instantly. Uninstalling wipes all of it;clearPersistedCache()removes the snapshot on demand. No email or push — replies appear when this page opens. show()remains the direct compose call when you do not want a list.
Optional identity #
Nothing is collected unless you call this:
Heardock.identify(id: 'u_123', email: 'bob@example.com', name: 'Bob');
Heardock.clearIdentity();
The form no longer asks for an email. identify(email:) still attaches the
address as optional contact data on the payload.
Page context #
Set the current screen (and any metadata) whenever your route changes:
Heardock.setContext(page: '/settings/export', metadata: {'plan': 'pro'});
If you do nothing, Heardock.show falls back to the current ModalRoute name.
Submit without UI #
final result = await Heardock.submit(
message: 'Export PDF freezes at 80%',
category: FeedbackCategory.bug,
metadata: {'plan': 'pro'},
);
Fully custom UI #
Heardock.submit is enough for the occasional custom form. If you are
building a whole feedback flow, depend on heardock_core
instead: same transport, context capture, idempotency, and offline queue, plus
queue visibility (pendingCount, flushQueue report) and localized error copy
(HeardockStrings.errorFor) — with no widgets or HeardockTheme involved.
This package re-exports that API, so switching is a small change.
What is collected #
| Field | Source | Toggle |
|---|---|---|
app_version, build_number |
package_info_plus |
always on |
platform |
dart:io (ios, android, …) |
always on |
os_version, device |
device_info_plus |
CollectOptions.device |
locale |
PlatformDispatcher.locale |
CollectOptions.locale |
screen |
setContext / route name |
CollectOptions.screen |
| user id / email / name | identify() only |
opt-in |
metadata |
setContext / submit |
opt-in |
The SDK never reads contacts, photos, clipboard, or advertising IDs. Feedback is plain text; screenshots will be opt-in in the attachment milestone.
Offline behaviour #
- A network error, timeout, 429, or 5xx is queued locally (max 20 items).
- A 4xx validation/auth error is shown to the user instead of queued.
- Queued items are retried on
configure, when the form opens, and when you callHeardock.flushQueue(). There is no background scheduler. - Backoff: 1s, 5s, 30s, 2m, 10m; five attempts, then the item is dropped.
- Keys are idempotent, so a retry cannot create a duplicate feedback item.
Local development #
The demo API lives in this repo at apps/web:
# from the repo root
pnpm install
pnpm dev
Then run the example app:
cd packages/sdk-flutter/example
flutter run --dart-define=HEARDOCK_BASE_URL=http://localhost:3000
- iOS simulator:
http://localhost:3000works. - Android emulator: use
http://10.0.2.2:3000. - Demo publishable key:
hd_pub_demo_fieldnote(theFieldnoteproject). - Open
http://localhost:3000/inbox?token=devto read the notes.
Theming and i18n #
HeardockTheme(
primaryColor: Color(0xFFE4572E),
backgroundColor: Color(0xFFFFFDF8),
textColor: Color(0xFF191510),
borderRadius: 16,
fontFamily: 'Inter', // optional; defaults to your Theme text theme
);
The device locale picks en or zh. Force one with
HeardockConfig(locale: 'zh-CN'). Override any subset of the shared string keys for your own i18n system:
Heardock.configure(HeardockConfig(
publicKey: 'hd_pub_ab12cd34',
locale: 'zh-CN',
strings: const {'title': '告诉我们你的想法', 'send': '提交'},
));
// Replace locale + overrides and refresh any open bundled UI.
Heardock.updateLocalization(locale: 'en', strings: const {'title': 'Send feedback'});
The shared keys and error mappings live in packages/shared/localization.json. The form respects text scaling,
dark mode, reduced motion, and keyboard insets.
Testing #
flutter analyze
flutter test
The suite covers the API contract, idempotency, error mapping, offline backoff/drop rules, context collection, i18n, and the form's validation, success, queued, and error states.
Not in 0.1.0 #
- Screenshot / file attachments (API contract already reserves the field).
- Swift SDK, Web Widget.
- Background retry scheduling (no workmanager dependency).
- A hosted fallback URL for WebView.
Naming #
Heardock is a working name. The package and public API (Heardock.configure,
Heardock.show) intentionally match the product for now. A future rename
would publish a new package and keep an alias package for a transition period.
The display brand in the web app lives in packages/shared/src/brand.ts.