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 snippet goes in that file's <head>. Flutter draws the UI into a canvas rather than DOM elements, so pageviews and manual events work as usual while anything that inspects the DOM does not.

Get your tracking snippet

In your Rybbit dashboard, open Site Settings → Tracking Script and copy your snippet. It looks like this:

<script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>

YOUR_SITE_ID is the numeric ID of your site. If you self-host Rybbit, app.rybbit.io is the domain of your own instance.

Add the snippet to Flutter web

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

web/index.html

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

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

Navigation is tracked automatically with either URL strategy. Flutter's default hash strategy writes routes as /#/settings, and the tracker listens for hashchange and records #/settings as the path /settings. With usePathUrlStrategy() the Navigator uses the History API, and the tracker wraps history.pushState and history.replaceState and listens for popstate.

Verify installation

Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

If nothing shows up:

View the page source and search for script.js?siteId= to confirm the snippet is on the page.
Open the browser Network tab and check that script.js returns 200 and that POST requests go to /api/track.
Disable ad blockers, or set up a proxy so the script loads from your own domain.
See the script troubleshooting guide for other common causes.

Track custom events

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

lib/analytics.dart

import 'dart:js_interop';

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

void trackEvent(String name, [Map<String, Object?>? properties]) {
  _rybbitEvent(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 DOM-based features (data-rybbit-event attributes, outbound-link tracking, button-click autocapture, session replay) have no elements to observe. Use the Dart interop above for events.
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, production hosting must be configured.
rybbit is undefined in Dart: the snippet is deferred, 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 button clicks.
Identify users to connect sessions to accounts.
Proxy the script through your own domain to bypass ad blockers.
Script attributes let you skip or mask URLs and tag events.