shepherd_heat

Pure Flutter heat map tracking SDK for the Shepherd platform.

shepherd_heat captures user click/tap interactions in your Flutter applications by intercepting pointer events, performing hit-testing against shepherd_tag metadata, calculating normalized local coordinates, and batch-uploading them to the Shepherd BFF backend. This enables Microsoft Clarity-like thermal heat maps to visualize user behavior.

Features

• Semantic Event Association: Correlates user taps with semantic widgets annotated with ShepherdElementKey and ShepherdPageKey.
• Responsive Normalization: Coordinates are normalized to relative values (0.0 - 1.0) based on physical widget sizes, ensuring precise rendering across all device screen sizes.
• Smart Batching: Buffers click events in memory and uploads them in periodic batches to optimize network request usage.
• Low Footprint: Minimal overhead, built on native Flutter hit-testing.

Getting started

Add shepherd_heat and shepherd_tag to your pubspec.yaml:

dependencies:
  shepherd_tag: ^0.0.7
  shepherd_heat: ^0.0.1

Usage

Wrap your application root or page with the ShepherdHeatTracker widget:

import 'package:flutter/material.dart';
import 'package:shepherd_heat/shepherd_heat.dart';

void main() {
  runApp(
    MaterialApp(
      home: ShepherdHeatTracker(
        endpoint: 'https://union.shepherdplatform.com/graphql', // Your BFF endpoint
        apiKey: 'YOUR_SHEPHERD_PROJECT_KEY',
        uploadInterval: const Duration(seconds: 10),
        maxBufferSize: 30,
        child: const MyAppHome(),
      ),
    ),
  );
}

Make sure your target pages and elements are annotated with ShepherdPageKey and ShepherdElementKey from shepherd_tag:

import 'package:flutter/material.dart';
import 'package:shepherd_tag/shepherd_tag.dart';

class MyAppHome extends StatelessWidget {
  const MyAppHome({super.key});

  @override
  Widget build(BuildContext context) {
    return ShepherdPageKey(
      id: 'login_page',
      child: Scaffold(
        body: Center(
          child: ShepherdElementKey(
            id: 'submit_button',
            child: ElevatedButton(
              onPressed: () {},
              child: const Text('Login'),
            ),
          ),
        ),
      ),
    );
  }
}

Additional information

• Part of the Shepherd ecosystem.
• Report issues at the issue tracker.