Flutter SDK
Last updated
Use the Flutter package to add Metrickle to a Flutter app on any platform it runs on. It’s written in Dart with no platform code of its own (it uses the standard shared_preferences, package_info_plus and url_launcher plugins), and follows the same rules as the other SDKs, so a funnel, task or survey means the same thing in Flutter as on the web. For what each event means and how to name your own, see Events, people and properties.
Accessibility-first UX research and conversion analytics for Flutter apps. Track screens and events, find friction (rage taps, dead and slow taps, u-turns, form errors), run in-app surveys and collect feedback, and segment every funnel and journey by assistive-technology use (screen reader, large text, reduced motion, …).
Works on iOS, Android, web and desktop. Uses package_info_plus (app version) and url_launcher
(study invite links) and no platform code of its own.
Install
flutter pub add metrickle
Set up
Initialise before runApp, add the navigator observer for automatic screen views, and wrap the app
in MetrickleScope for accessibility context, rage taps, dead and slow taps and the built-in survey
sheet.
import 'package:flutter/material.dart';
import 'package:metrickle/metrickle.dart';
Future<void> main() async {
await Metrickle.init(writeKey: 'mk_pub_YOUR_WRITE_KEY');
runApp(MaterialApp(
navigatorObservers: [MetrickleNavigatorObserver()],
builder: (context, child) => MetrickleScope(child: child!),
routes: {'Home': (_) => const HomePage(), 'Checkout': (_) => const CheckoutPage()},
initialRoute: 'Home',
));
}
Screens are named from RouteSettings.name. Unnamed routes and popups (dialogs, menus, bottom
sheets) are skipped; name them with MetrickleNavigatorObserver(nameExtractor: (route) => …).
go_router
final router = GoRouter(
observers: [MetrickleNavigatorObserver()],
routes: [
GoRoute(name: 'Home', path: '/', builder: (_, __) => const HomePage()),
GoRoute(name: 'Checkout', path: '/checkout', builder: (_, __) => const CheckoutPage()),
],
);
MaterialApp.router(
routerConfig: router,
builder: (context, child) => MetrickleScope(child: child!),
);
Give each GoRoute a name, or use nameExtractor. A ShellRoute has its own navigator: pass a
MetrickleNavigatorObserver in its observers too.
Events
final mk = Metrickle.instance;
mk.track('plan_selected', {'plan': 'team', 'seats': 5});
mk.screen('Onboarding step 2'); // manual screen views, if you don't use the observer
mk.identify('user_42', {'plan': 'team'});
mk.register({'experiment': 'b'}); // added to every later event
mk.formError(form: 'signup', field: 'email', reason: 'invalid');
mk.reset(); // on logout
await mk.flush();
Property values are strings (≤ 1024 chars), finite numbers, booleans or null; at most 64 per event.
Names starting with $ are reserved.
Sent automatically: $app_open (launch and each return to the foreground), $app_background,
$screen, $u_turn (A → B → back to A within 7s), $rage_click (3 taps within 1s inside 30
logical px, identified by Semantics(identifier:), a ValueKey<String> or the widget class), and
$dead_click / $slow_click (below).
Dead and slow taps
With MetrickleScope in place, a tap on a control that nothing answered is reported, with the same
event names and properties as dead clicks on the web:
$dead_click: nothing answered within 4 seconds.$slow_click: it answered, but only after more than a second;msis how long it took.
A tap is a touch, stylus or primary mouse press that lifts within the touch slop. It’s judged when
the nearest gesture handler under it has an enabled tap: GestureDetector(onTap:), InkWell, the
Material buttons, list tiles, checkboxes, switches and radios. Taps on text fields, disabled
controls and plain text aren’t judged, and neither are detectors with excludeFromSemantics: true.
Only the nearest handler counts, so a page-wide GestureDetector (e.g. one that hides the keyboard)
doesn’t make taps on a list’s blank space look like taps on a control; blank space outside any
scrollable under such a detector is judged, though.
An answer is anything the person could notice: an event after the tap (a new screen, your own
track(), the app going to the background to open a link; friction signals don’t count), or a
change on screen. The screen check compares a cheap fingerprint of the render tree, taken when the
finger goes down (before your handlers run), with the tree at 1s and then every 250ms until 4s: which
render objects are there, their sizes and positions, paragraph text, scroll offsets, offstage and
semantics state (checked, selected, expanded, value), plus the route stack. Ripples, pressed
colours and elevation are left out, since they come back by themselves. Text field contents are
never read. Something that animates on its own can hide a dead tap, but nothing makes a working tap
look dead.
Each event has selector and text (as for rage taps; never text field contents), input: touch,
affordance: control and the screen the tap was on as its path. Turn it off with
MetrickleOptions(deadTaps: false); rage taps are separate.
Revenue from Stripe or RevenueCat
Connect your RevenueCat project (or Stripe account) in the Metrickle dashboard under Integrations → Revenue. Purchases, renewals, refunds and cancels then arrive server-side on the person you identified, so a refund takes back the task they completed. Log in to RevenueCat with the same id:
mk.identify(user.id);
await Purchases.logIn(user.id);
// Or keep RevenueCat's id and name the Metrickle user:
// await Purchases.setAttributes({'metrickle_user_id': user.id});
Options
| Option | Default | |
|---|---|---|
host | https://in.metrickle.com | Ingest origin |
cookieless | false | Persist nothing; no anonymous or session id, surveys off |
flushInterval | 5s | Also flushes at 20 queued events and on background |
sessionTimeout | 30 min | Inactivity before a new session |
rageTaps | true | Needs MetrickleScope |
deadTaps | true | $dead_click / $slow_click; needs MetrickleScope |
debug | false | Logs queued events and send results |
beforeSend | (event) => event to scrub, null to drop | |
appVersion, appBuild | read from the package info | Set them to override; the version is how releases are detected |
deviceModel, osVersion, timezone | read where possible | Flutter can’t read the device model without a plugin |
httpClient, storage | http.Client(), SharedPreferences | Inject for tests |
openUrl | system browser (url_launcher) | How study invite links open; inject for tests |
Events are queued in SharedPreferences (up to 1000, dropped after 7 days) so they survive the app being killed and offline periods. Failed sends back off from 1s to 60s.
Surveys
Campaigns are authored in the Metrickle dashboard. With MetrickleScope in place, eligible surveys
open in a built-in bottom sheet designed to meet WCAG 2.2 AA: 48dp targets, scale buttons announced
with their end labels and selected state, screen-reader and keyboard focus on the heading, text
scaling without truncation, dark mode, high contrast, reduced motion, a visible Close button and
Escape/back to dismiss. The thank-you stays until the person closes it. Your brand accent is used
only when it has 4.5:1 contrast (7:1 in high contrast).
To render surveys yourself:
final stop = Metrickle.instance.surveys.onShow((survey) {
// Show survey.campaign.questions, then:
survey.shown();
survey.answer(question, const SurveyAnswer(score: 9));
survey.complete(); // or survey.dismiss(questionIndex)
});
Metrickle.instance.surveys.show('cmp_123'); // QA: show now, ignoring targeting
Follow-ups (study invites)
A campaign can invite people who answered into a study: a booked video call (moderated) or a self-guided test on the web (unmoderated), optionally only for some answers (e.g. NPS 0–6). After the last answer the built-in sheet asks for the respondent’s personal link (“One moment…” on the submit button, up to 5 seconds). If one comes back it shows the invite, with its heading focused and announced, “No thanks” and “Choose a time” / “Take part”, which opens the link in the system browser. Otherwise it shows the usual thank-you. The invite never closes on its own.
With your own renderer:
survey.complete();
if (survey.followUp != null && survey.qualifies()) {
final url = await survey.invite(); // null: show the plain thank-you
if (url != null) {
survey.followUpOffered(); // once the invite is on screen
// Show survey.followUp!.prompt with your buttons. When they accept:
survey.followUpAccepted();
await launchUrl(Uri.parse(url), mode: LaunchMode.externalApplication);
}
}
invite() asks once per response and only returns https links. $survey_follow_up is recorded at
most once for the offer and once for the acceptance.
Turn the built-in sheet off with MetrickleScope(builtInSurveys: false, child: …). The sheet opens on
the navigator of a MetrickleNavigatorObserver (or a Navigator above the scope).
Feedback
Built-in feedback sheet
Open the “Report a problem” sheet from your own button or menu item. It never opens by itself:
TextButton(
onPressed: () => Metrickle.instance.feedback.showSheet(context),
child: const Text('Report a problem'),
)
People choose what it’s about (Something’s broken, Something’s confusing, An idea or request, An
accessibility barrier, Something else; preselect one with showSheet(context, category: FeedbackCategory.accessibility)) and say what happened, up to 4000 characters. It sends through
feedback.submit, so the screen, device, app version, locale and accessibility settings are
attached, and no screenshot is taken. showSheet returns whether the feedback was sent. While
feedback is switched off for Flutter, or the user has opted out, it shows nothing and returns false.
The sheet is designed to meet WCAG 2.2 AA, like the survey sheet: focus and the screen reader move to its heading when it opens, the categories are a radio group with 48dp rows and a selected state, the message field has a visible label, errors appear under their fields with focus moved to the first, “Sending…” disables Send, a failure is announced and keeps what they wrote, and the thank-you is focused and stays until they choose Done. It scales with large text (scrolling, not truncating), follows dark mode and high contrast, doesn’t animate with reduced motion, has a visible Close button, and back or Escape dismisses it. “Powered by Metrickle” and your accent colour follow the branding settings in the dashboard; the accent is used only at 4.5:1 contrast (7:1 in high contrast).
To host it yourself, e.g. in a dialog or a page, use MetrickleFeedbackSheet(onClose: …).
Your own form
final shot = await Metrickle.instance.feedback.captureScreenshot(); // only after the user opts in
final result = await Metrickle.instance.feedback.submit(
category: FeedbackCategory.accessibility,
message: 'The Pay button is not announced',
screenshot: shot,
);
Feedback can be switched off per platform under Settings → Research in the dashboard. While it’s off, Metrickle.instance.feedback.isEnabled is false and submit sends nothing, so use it to hide your feedback button. Settings arrive after launch, so rebuild when they do:
ValueListenableBuilder(
valueListenable: Metrickle.instance.configListenable,
builder: (context, _, _) => Metrickle.instance.feedback.isEnabled ? const FeedbackButton() : const SizedBox.shrink(),
);
Session, screen, device, app version, locale and accessibility settings are attached. Screenshots are PNG, downscaled to 1280px on the long edge and at most 2 MB.
Privacy
- Text field contents are never captured, only identifiers and semantics labels.
- No advertising ids or device serials. The anonymous id is a random UUID in app storage.
optOut()stops all collection and network calls, clears the queue and removes the anonymous and session ids from the device, and is remembered. While opted out no anonymous id is created, on launch or byreset(). Your own user id (fromidentify) and consent are kept.optIn()starts a new anonymous id and fetches surveys and settings again.cookieless: truestores nothing on the device.consent(replay: true)records consent for research features (kept for parity with the web SDK).