How to Build a Tap Heat Map Analytics Tool in FlutterFlow

In the Firebase console, navigate to Firestore Database and create a new collection named tap_events. Each document should have these fields: page (String — the screen name), x_pct (Number — tap X as percentage of screen width, 0.0 to 1.0), y_pct (Number — tap Y as percentage of screen height, 0.0 to 1.0), session_id (String — a UUID per app session), created_at (Timestamp), and device (String — 'ios' or 'android'). In FlutterFlow's Firestore schema editor (left sidebar → Firestore), add the tap_events collection with these fields so FlutterFlow can type-check references to it.

In FlutterFlow Custom Code, create a new Custom Widget named TapCaptureOverlay. This widget wraps its child in a GestureDetector with onTapUp. In the onTapUp callback, retrieve the tap position from TapUpDetails.globalPosition, divide x by MediaQuery.of(context).size.width and y by MediaQuery.of(context).size.height to get normalized percentages. Then call a Firestore write to tap_events with the normalized values. The widget accepts two parameters: pageName (String) and child (Widget). It is transparent and only captures taps, passing them through to the child so the underlying UI remains fully interactive.

1import 'package:flutter/material.dart';
2import 'package:cloud_firestore/cloud_firestore.dart';
3import 'package:uuid/uuid.dart';
4
5class TapCaptureOverlay extends StatefulWidget {
6  final String pageName;
7  final Widget child;
8  final String sessionId;
9
10  const TapCaptureOverlay({
11    Key? key,
12    required this.pageName,
13    required this.child,
14    required this.sessionId,
15  }) : super(key: key);
16
17  @override
18  State<TapCaptureOverlay> createState() => _TapCaptureOverlayState();
19}
20
21class _TapCaptureOverlayState extends State<TapCaptureOverlay> {
22  Future<void> _logTap(TapUpDetails details) async {
23    final size = MediaQuery.of(context).size;
24    final xPct = details.globalPosition.dx / size.width;
25    final yPct = details.globalPosition.dy / size.height;
26
27    await FirebaseFirestore.instance.collection('tap_events').add({
28      'page': widget.pageName,
29      'x_pct': xPct,
30      'y_pct': yPct,
31      'session_id': widget.sessionId,
32      'created_at': FieldValue.serverTimestamp(),
33      'device': Theme.of(context).platform == TargetPlatform.iOS
34          ? 'ios'
35          : 'android',
36    });
37  }
38
39  @override
40  Widget build(BuildContext context) {
41    return GestureDetector(
42      behavior: HitTestBehavior.translucent,
43      onTapUp: _logTap,
44      child: widget.child,
45    );
46  }
47}

In FlutterFlow, add an App State variable named currentSessionId (String, default empty). On your app's initialization (or in the first page's On Page Load action), call a Custom Action named generateSessionId that uses the uuid package to create a new UUID and stores it in currentSessionId. On each page you want to track, add the TapCaptureOverlay Custom Widget as the root element of the page and pass currentSessionId as the sessionId parameter and the page route name as pageName. This ensures every tap is associated with the user's current session for funnel analysis.

Create a second Custom Widget named HeatMapOverlay. This widget accepts a list of tap points (normalized x and y percentages) and a size parameter. It uses a CustomPainter to draw semi-transparent colored circles at each tap location on a transparent canvas. Scale each point back to pixel coordinates by multiplying x_pct by the canvas width and y_pct by the canvas height. Color the circles using a radial gradient from red (center, hot) to transparent (edge, cool). Increase opacity for clusters by drawing multiple overlapping circles — where many taps overlap, the combined opacity approaches full red, creating the classic heat map effect.

1import 'package:flutter/material.dart';
2
3class HeatMapPoint {
4  final double xPct;
5  final double yPct;
6  const HeatMapPoint(this.xPct, this.yPct);
7}
8
9class HeatMapOverlay extends StatelessWidget {
10  final List<HeatMapPoint> points;
11  final double radius;
12
13  const HeatMapOverlay({
14    Key? key,
15    required this.points,
16    this.radius = 40.0,
17  }) : super(key: key);
18
19  @override
20  Widget build(BuildContext context) {
21    return CustomPaint(
22      painter: _HeatMapPainter(points: points, radius: radius),
23      child: const SizedBox.expand(),
24    );
25  }
26}
27
28class _HeatMapPainter extends CustomPainter {
29  final List<HeatMapPoint> points;
30  final double radius;
31
32  _HeatMapPainter({required this.points, required this.radius});
33
34  @override
35  void paint(Canvas canvas, Size size) {
36    for (final point in points) {
37      final dx = point.xPct * size.width;
38      final dy = point.yPct * size.height;
39      final paint = Paint()
40        ..shader = RadialGradient(
41          colors: [
42            Colors.red.withOpacity(0.35),
43            Colors.orange.withOpacity(0.15),
44            Colors.transparent,
45          ],
46          stops: const [0.0, 0.5, 1.0],
47        ).createShader(Rect.fromCircle(
48          center: Offset(dx, dy),
49          radius: radius,
50        ));
51      canvas.drawCircle(Offset(dx, dy), radius, paint);
52    }
53  }
54
55  @override
56  bool shouldRepaint(_HeatMapPainter old) => old.points != points;
57}

For large tap datasets (over 10,000 events), fetching every document to the client is slow and expensive. Create a Firebase Cloud Function named aggregateTapEvents that accepts a pageName and a grid resolution (e.g., 20x20 cells). The function queries all tap_events for that page, buckets each point into its grid cell (Math.floor(x_pct * resolution)), counts the cell occupancy, and returns a compact JSON array of {cellX, cellY, count} objects. In FlutterFlow, call this Cloud Function from a Custom Action and convert the grid cells back to screen percentage coordinates before passing them to HeatMapOverlay.