round_spot library

Customizable heat map interface analysis library

Usage

Setup

Wrap your MaterialApp widget to initialize() the library:

void main() {
  runApp(rs.initialize(
    child: Application()
  ));
}

Add an Observer for monitoring the navigator:

MaterialApp(
  navigatorObservers: [ rs.Observer() ]
)

Configuration

Provide the callbacks for saving the processed output:

rs.initialize(
  localRenderCallback: (data, info) => sendHeatMapImage(data)
)

Use Config to make the tool better fit your needs:

rs.initialize(
  config: rs.Config(
    minSessionEventCount: 5,
    uiElementSize: 15,
    heatMapPixelRatio: 2.0,
  ),
  loggingLevel: rs.LogLevel.warning // recommended for integration testing
)

Important aspects

Route naming

Route names are used to differentiate between pages. Read about their usage in relation to this library at Observer page.

Scrollable widgets

Scrollable spaces need manual instrumentation to be correctly monitored. Read about the use of a Detector widget to learn more.

Current limitations

Widgets that dynamically change their size, position, dis/appear or otherwise cause other widgets to shift their positions relative to the viewport (for example in response to a user action) are not supported.

When that happens during a session recording it will cause some of the gathered interactions to be displaced in relation to the background image and the rest of data making the heat map difficult to interpret and understand.

Commonly used terms

Area

A visual space taken by a particular widget and its children. Can be portion or the whole screen.

Session

A collection of user interactions recorded in a particular area during some period of time. It is a base for a single heat map output.

All current sessions are ended when user puts the application into background, as defined by the AppLifecycleState.paused state. You can additionally control it by setting the Config.maxSessionIdleTime.

Classes

Config

Holds the configuration relating to the specifics of data gathering and processing.

Detector

Detects user interactions in the child widget tree.

Observer

Keeps track of Navigator PageRoute changes.

OutputInfo

Holds additional information about the exported heat map.

Enums

HeatMapStyle

Available heat map styles.

LogLevel

Available library logging levels.

OutputType

Available output data types.

Properties

config → Config

Provides access to the current Config and allows to change it.

no setter

enabled ↔ bool

A shortcut to Config.enabled for easy access.

getter/setter pair

Functions

initialize({required Widget child, Config? config, LogLevel loggingLevel = LogLevel.off, LocalRenderCallback? localRenderCallback, DataCallback? dataCallback}) → Widget

Initializes the Round Spot library.

Typedefs

DataCallback = void Function(Uint8List data)

Signature for the data output callback.

LocalRenderCallback = void Function(Uint8List data, OutputInfo info)

Signature for the local render output callback.