Customizable heat map interface analysis library

Last update: Dec 12, 2022

Overview

Round Spot

Customizable heat map interface analysis library

Round Spot simplifies the UI accessibility and behaviour analysis for Flutter applications by handling the data gathering and processing. It produces beautiful heat map visualizations that aim to make the UI improvement and troubleshooting easy and intuitive.

⚠️ Note: This tool still in its development and currently only offers local on device heat map generation. This limits the number of interactions that can be included in a single image and therefore can be considered as a preview.

Usage

Import the package in your main file:

import 'package:round_spot/round_spot.dart';

Setup

Wrap your MaterialApp widget to initialize the library:

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

Add an observer for monitoring the navigator:

MaterialApp(
  navigatorObservers: [ Observer() ]
)

Configuration

Provide the callbacks for saving the processed output:

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

Configure the tool to better fit your needs:

initialize(
  config: Config(
    minSessionEventCount: 5,
    uiElementSize: 15,
    heatMapPixelRatio: 2.0,
  )
)

UI Instrumentation

Route naming

Route names are used to differentiate between pages. Make sure you are consistently specifying them both when using named routes and pushing PageRoutes (inside RouteSetting)

Scrollable widgets

To correctly monitor interactions with any scrollable space a Detector has to be placed as a direct parent of that widget:

Detector(
  areaID: id,
  child: ListView(
    children: /* children */,
  ),
)

Contributors

Created by Stanisław Góra

License

This tool is licenced under MIT License

Comments

Decoupling heat map generation

Hello

First of all I would like to congratulate you on this amazing package.

I was looking for some solution for heatmaps in flutter and found your package. However, the generation of heat maps is coupled with an analytics, and I needed to use it with my own analytics.

So, inspired by your package, I created flutter_heat_map, which only takes care of generating heat maps.

Thanks!

opened by apps-auth 1
Scroll-space events not recorded during scrolling

Description

Touch events that happen on a Detector observed scroll-space during scrolling of that area are not recorded by that Detector and instead end up on the page-wide heat map.

This happens because during scrolling further events are blocked from the scroll widget children. A new, outside Detector implementation is needed.
bug

opened by stasgora 0
Popup support

Description

Popups are neither detected nor supported. Interactions with them are not filtered.

Proposal

Detector should support monitoring a popup and its interactions.
bug

opened by stasgora 0
Scrolling and dynamic content

Description

Currently all events are rendered relative to screen space, irrespective of the UI elements they correspond to. In order to be relevant the underlying image and event coordinate space must match.
bug

opened by stasgora 0
Sensitive data filtering

Description

Currently the screenshots are not altered in any way leaving potentially identifiable and sensitive information on the images being collected, processed and examined. The goal is to remote any such information so that this library could be used without causing privacy concerns.

Solution

Introduce another marker widget Blur(child) to mark an area as sensitive

Alternative solution

Use the Google ML Kit Text Recognition component to paint out all text from the images

opened by stasgora 0
Heat map rendering improvements

Improvements

Smoother gradient on bigger blobs

Current look:

Improved gradient shape for blobs with complex shapes

Current look:

Finer control over the top color and gradient of a single blob

Currently it's directly tied to the number of events in its cluster in relation to the biggest one.
enhancement

opened by stasgora 0
Dynamic content

Description

Aside from scrollable areas, dynamic content is not properly handled. Events are currently processed based on their coordinates. If the widget arrangement changes during the capturing of a single session events will be rendered in places not corresponding to their original target widgets.

Solution

Events should be tied by a position relative to their target widget.
bug

opened by stasgora 0
Smarter event area assignment

Current state

Currently the innermost Detector always catches the interaction. There are cases when an additional Detector has to be placed due to a scrollable list but the current content does not overflow the widget area.

Solution

Every Detector that handles a scrollable area should be able to detect if there is currently any content overflow. If not there is no need to process that area in separation and the event should propagate to the Detector higher up the tree.
enhancement

opened by stasgora 0
Gesture event support

Description

Currently only touch events are detected and rendered. As a common mobile input method, gesture events should also be captured and rendered. Events that are part of gestures should not be reported as individual presses like right now.
enhancement

opened by stasgora 0

Releases(v0.5.0)

v0.5.0(Sep 11, 2021)
NEW: refreshed data output implementation that uses a binary Protobuf serialized format

BREAKING: output types and callbacks have been renamed:

graphicalRender ➡️ localRender

rawData ➡️ data (data callback no longer provides the OutputInfo parameter)

BREAKING: only one output type can now be chosen (Config.outputTypes ➡️ Config.outputType)

Source code(tar.gz)
Source code(zip)
v0.4.0(May 23, 2021)
NEW: support for popups 💬

FIX: popup interactions included in outputs from below them

BREAKING: Detector.hasGlobalScope renamed to Detector.cumulative

NEW: background screenshot taking improvements:

FIX: background could be captured before the route transition animation has ended

Improved screenshot taking policy in regard to the screen loading period

Source code(tar.gz)
Source code(zip)
v0.3.3(May 17, 2021)
FIX: interactions not cleared when heat map is generated

Source code(tar.gz)
Source code(zip)
v0.3.2(May 17, 2021)
FIX: scroll state loss when switching routes

FIX: incorrect scrollable heat map scaling when using custom Config.heatMapPixelRatio

Source code(tar.gz)
Source code(zip)
v0.3.1(May 4, 2021)
FIX: PageView config not correctly detected by the Detector

Source code(tar.gz)
Source code(zip)
v0.3.0(May 4, 2021)
BREAKING: reworked Detector implementation - should be placed around the scrolling widgets

NEW: support for lazy loaded scroll widgets like ListView.builder()

FIX: events misreported during scrolling

NEW: support for custom scroll widgets - using Detector.custom() constructor

NEW: scrolling heat maps smart cropping - saves on image size

REFACTOR: removed ListDetector - not needed anymore

FIX: rendering bug when Config.heatMapPixelRatio was changed during session recording

Source code(tar.gz)
Source code(zip)
v0.2.0(Apr 11, 2021)
Adjustable heat map resolution

Unified output callbacks signatures

Source code(tar.gz)
Source code(zip)
v0.1.1(Apr 9, 2021)
Example application

Private API documentation

Source code(tar.gz)
Source code(zip)
v0.1.0(Apr 8, 2021)
Initial release

Heat map creation

Raw data exporting

Scrolling spaces support

Source code(tar.gz)
Source code(zip)

Owner

Stanisław Góra

Software Engineer · Flutter enthusiast · Building Alexa @ Amazon

GitHub https://pub.dev/packages/round_spot

soTired is an application for cognitive fatigue assessment. It includes a stand-alone Android app for fatigue detection and an additional part for data management and further analysis.

Motivation soTired is an application for cognitive fatigue assessment. It includes a stand-alone Android app for fatigue detection and an additional p

5 Oct 22, 2021

Bacco app mock up from Bachelor Thesis at Politecnico di Milano developed by Pietro Chierico and Flavia Di Scala. The Thesis is named: 'An app for the assessment of the individual well-being through the analysis of four areas: Nutrition, Stress, Sleep, Fitness'.

bacco_app Bacco app mock up from Bachelor Thesis at Politecnico di Milano developed by Pietro Chierico and Flavia Di Scala. The Thesis is named: 'An a

2 Sep 23, 2021

How to get the most value from Dart static analysis

This package is deprecated. Before it was deprecated, it was the way to get analysis options matching those used internally at Google. This was useful

324 Nov 4, 2022

How to get the most value from Dart static analysis

This package is deprecated. Before it was deprecated, it was the way to get analysis options matching those used internally at Google. This was useful

324 Nov 4, 2022

A SECURE personal data Analysis and Storage system.

Magic Data Bottle Our goal is to design and implement a secure personal data analysis and storage system. Repo Structure app An android app written in

3 Sep 27, 2022

An intuitive Token Parser that includes grammar definition, tokenization, parsing, syntax error and debugging. Implementation based on Lexical Analysis for Dart.

Token Parser An intuitive Token Parser that includes syntax/grammar definition, tokenization and parsing. Implementation based on Lexical Analysis. Re

2 Dec 15, 2022

Nexus is a state management library that makes it easy to create and consume your application's reactive data to the user interface.

Nexus ?? Nexus is a state management library that makes it easy to create and consume your application's reactive data to the user interface. With nex