Overview

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.

Installation

Add the dependency to your pubspec.yaml file:

dependencies:
  shepherd_tag: ^0.0.8
  shepherd_heat: ^0.0.10

Basic Setup

Wrap your application root or main 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',
        apiKey: 'YOUR_SHEPHERD_PROJECT_KEY',
        uploadInterval: const Duration(seconds: 10),
        maxBufferSize: 30,
        child: const MyAppHome(),
      ),
    ),
  );
}

Manual Tracking (Keyboard & Custom UI)

Sometimes, clicks might be swallowed by custom gesture detectors (like custom Design System components), or the interaction comes from a keyboard event (like pressing Enter to submit a form).

In these cases, you can manually force an interaction record using ShepherdHeat.reportInteraction:

// For a keyboard submission (e.g. user pressed ENTER):
TextFormField(
  onFieldSubmitted: (_) {
    ShepherdHeat.reportInteraction('submit_button', inputSource: 'KEYBOARD');
    _login();
  },
);

// For a custom button that swallows pointer events:
DSWebButton(
  onPressed: () {
    ShepherdHeat.reportInteraction('submit_button', inputSource: 'MOUSE');
    _login();
  },
);

Configuration Parameters

• uploadInterval: Time to wait before flushing the memory buffer to the backend (default: 10 seconds).
• maxBufferSize: Maximum number of events to store in memory before forcing a flush (default: 30).
• minWidth & minHeight: Minimum screen dimensions required to track an event (prevents recording data on screens that are too small).
• debugMode: Enable this to see logs when interactions are sent to the network.