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 on heardock_core for 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 call Heardock.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:3000 works.
  • Android emulator: use http://10.0.2.2:3000.
  • Demo publishable key: hd_pub_demo_fieldnote (the Fieldnote project).
  • Open http://localhost:3000/inbox?token=dev to 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.

Libraries

heardock_flutter
In-app feedback for Flutter, with a bundled native sheet.