Flutter web

A Flutter web app is served from the web/index.html template in your project, which flutter build web copies to build/web/index.html. The tag goes in that file's <head>. Flutter draws the UI itself, so a few DOM-based features behave differently.

Copy your tracking snippet

In OnyxMetric, open your site's Site Settings and copy the tracking script. It looks like this:

<script src="https://app.onyxmetric.com/api/script.js?siteId=YOUR_SITE_ID" async></script>

YOUR_SITE_ID is the numeric ID of your site.

Add the snippet to Flutter web

Open web/index.html in your Flutter project.
Paste the snippet inside <head>, above the generated flutter_bootstrap.js script:

web/index.html

<head>
  <meta charset="UTF-8" />
  <title>My App</title>
  <script src="https://app.onyxmetric.com/api/script.js?siteId=YOUR_SITE_ID" async></script>
</head>

Rebuild with flutter build web and deploy the build/web folder.

Navigation is tracked with either URL strategy. Flutter's default hash strategy writes routes like /#/settings, and hash routes are recorded as page paths automatically.

Check that it works

Load your live site and click through a few pages. Pageviews show up in the OnyxMetric dashboard within seconds.

If nothing arrives:

View the page source and search for script.js?siteId= to confirm the tag is present.
In the browser's Network tab, check that script.js returns 200 and that requests go to /api/track.
Turn off ad blockers, or proxy the script through your own domain.
Read script troubleshooting for other causes.

Track custom events

Flutter widgets are not HTML elements, so data-onyx-event attributes have nothing to attach to. Call window.onyx.event() from Dart through dart:js_interop:

lib/analytics.dart

import 'dart:js_interop';

@JS('onyx.event')
external void _onyxEvent(String name, [JSAny? properties]);

void trackEvent(String name, [Map<String, Object?>? properties]) {
  _onyxEvent(name, properties?.jsify());
}

ElevatedButton(
  onPressed: () {
    trackEvent('signup_click', {'plan': 'pro'});
  },
  child: const Text('Sign up'),
)

Guard the call with kIsWeb if the same code also compiles for mobile or desktop targets.

Troubleshooting

Clicks, outbound links, and session replay show nothing: the CanvasKit and Skwasm renderers paint into a single <canvas>, so features that read the DOM have nothing to observe. Track those interactions with trackEvent.
Deep links 404 after switching to usePathUrlStrategy(): path URLs need the web server to rewrite every route to index.html. The Flutter dev server does this for you, but production hosting must be configured.
onyx is undefined in Dart: the script is async, so it is not ready during main(). Send events from user interactions, not from app start-up.

Next steps

Track custom events such as signups, purchases, and clicks.
Identify users to tie sessions to accounts.
Proxy the script through your own domain to get past ad blockers.
Script attributes let you skip or mask URLs and tag events.