Metrickle

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; ms is 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

OptionDefault
hosthttps://in.metrickle.comIngest origin
cookielessfalsePersist nothing; no anonymous or session id, surveys off
flushInterval5sAlso flushes at 20 queued events and on background
sessionTimeout30 minInactivity before a new session
rageTapstrueNeeds MetrickleScope
deadTapstrue$dead_click / $slow_click; needs MetrickleScope
debugfalseLogs queued events and send results
beforeSend(event) => event to scrub, null to drop
appVersion, appBuildread from the package infoSet them to override; the version is how releases are detected
deviceModel, osVersion, timezoneread where possibleFlutter can’t read the device model without a plugin
httpClient, storagehttp.Client(), SharedPreferencesInject for tests
openUrlsystem 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 by reset(). Your own user id (from identify) and consent are kept. optIn() starts a new anonymous id and fetches surveys and settings again.
  • cookieless: true stores nothing on the device.
  • consent(replay: true) records consent for research features (kept for parity with the web SDK).