Flutter Shake to Report a Bug: Build It and What to Capture

To add shake to report a bug in a Flutter app, listen to the accelerometer, capture the current screen when the phone shakes, and send that capture with the device context to your inbox. You can build it in an afternoon, or use an SDK that already does it.

Shake is the right trigger for testers on phones. No floating button covers the UI, and nobody has to hunt through a menu while the bug is still on screen. Here is how to build it, where the DIY version falls short, and what a report needs to be fixable.

Why shake beats a floating button on mobile

A floating button sits on top of your layout. It hides the exact corner where the bug often lives, and it shows up in every screenshot. A shake gesture costs no screen space and works from any screen, including modals and full-screen video.

Keep a manual entry point as well, such as a "Send feedback" item in settings. Some testers will never think to shake, and shaking is awkward on a train or a tablet on a stand.

Detect the shake in Flutter

The accelerometer stream from the sensors_plus package is enough. The idea is to compare the acceleration magnitude against a threshold and debounce it, so one shake triggers one report.

StreamSubscription? _sub;
DateTime _last = DateTime.fromMillisecondsSinceEpoch(0);

void startShakeListener(VoidCallback onShake) {
  _sub = userAccelerometerEventStream().listen((e) {
    final g = sqrt(e.x * e.x + e.y * e.y + e.z * e.z);
    final now = DateTime.now();
    if (g > 15 && now.difference(_last) > const Duration(seconds: 2)) {
      _last = now;
      onShake();
    }
  });
}

Tune the threshold on real devices. A value that feels right on a Pixel can fire constantly on a phone in a pocket, so test walking, not just sitting at a desk. Cancel the subscription when the app goes to the background.

Capture the screen before the dialog opens

Grab the screenshot first, then open the feedback screen. If you open the dialog first, you capture the dialog. Wrap your app in a RepaintBoundary with a key, then call toImage() on its render object and encode the result as PNG.

Two details are easy to miss:

• Platform views, such as maps and web views, can come out blank in a Flutter-side capture. Warn testers or fall back to a text description.
• Let the tester draw on the capture. An arrow on the broken button saves a paragraph of explanation.

What the report needs besides the screenshot

A screenshot says what the tester saw. It does not say why. The fixable version of a report also carries:

• App version, build number and environment (staging or production)
• Device model, OS version and locale
• Recent log output and the last failed network requests
• The screen or route the tester was on

Without these you end up asking "which phone, which build, can you reproduce it?" in a chat thread, which is the loop you were trying to avoid. The same reasoning applies to Flutter bug reporting in general and to tracking Flutter bugs from tester to ticket.

Build it or use an SDK

The DIY route is fine for a single internal app. The cost shows up later: you still need an upload endpoint, storage, a place to read reports, deduplication so one bug reported nine times is not nine tickets, and a way to forward to your tracker.

Tracebird ships shake to report in its Flutter SDK. Reports land in the same inbox as web reports, with the annotated capture, console output and recent network requests attached, and duplicates are grouped. If your testers use iOS builds, pair it with a clear TestFlight feedback process so reports do not scatter across channels.

Whichever way you go, test the shake on a physical device before you hand the build to anyone. Simulators fake the gesture, and the threshold is exactly the part you cannot tune there.