Flutter MySpot is a plugin alowing you to easily implement tutorial in your app

Features Manage scenario with scene to explain élément on your flutter widget adding key to desired widget Allow reponsive and moving widget as target, Audio support (using audioplayer), Handle play once (using flutter_secure_storage), Deformable spot to accept all widget geometrie, Simply add help button to call your scénario, Support multiple scenarion on one screen,

Getting started

To install plug-in add to your public.yaml :

dependencies:
  flutter:
    sdk: flutter

  flutter_myspot:
    git: https://github.com/mynumeric-mobile/flutter_myspot

Usage

examples for package could be found in example folder

• first wrap your page with HoleWidget

this widget hold scenario. Scenario is composed by properties and an array of scenes. Each scene is used sequencialy to highlight a designet widget.

note that your widget must have a key :

HoleWidget(
          scenario: SpotScenario(
            titleWidget: SpotScenario.textWidgetBuilder(text: "Wellcome to our tutorial", context: context),
            // and a scene for each widget to highlight
            scenes: [
              SpotScene(
                description: SpotScenario.textWidgetBuilder(
                    text: "You can change this number",
                    context: context,
                    style: const TextStyle(color: Colors.white, fontSize: 20)),
                audioAsset: "number.mp3",
              ),
            ],
            
          ),
          child: MyHomePage(title: 'Flutter Demo Home Page', key: GlobalKey()),
        ));
  }

• Next designate widget to highlight : add in top of your main widget an array 'tutorialKeys' add as many GlobalKey as you want scene

class MyHomePage extends StatefulWidget {
  MyHomePage({super.key, required this.title});
  final List<GlobalKey> tutorialKeys = [GlobalKey()];// add this line
....

and add tutorialKey to desired widget.

  Text(
    key: widget.tutorialKeys[0],

Handle play once

If you want to display tutorial only on first use, you can call createState("home") where "home" is a unique id for your scene. Your state must be set before any scenario is play in main or in splashscreen. When state is created you just have to set key property of your scene to limit to display her content to first run.

For exemple :

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await SpotScenario.createState(["home"]); //option if you want to display only once
  runApp(const MyApp());
}

in your scenario declaration add

HoleWidget(
          scenario: SpotScenario(
            titleWidget: SpotScenario.textWidgetBuilder(text: "Wellcome to our tutorial", context: context),
            // and a scene for each widget to highlight
            scenes: [
              SpotScene(
                id:"home,
                description: SpotScenario.textWidgetBuilder(
                    text: "You can change this number",
...

Note that you can use state for other purpose. You just need to at a unique ID.

to set value

SpotScenario.setState("myUniqueID", false);

to read state

SpotScenario.spotIDs["myUniqueID"]

Scénario life cycle

1 Display title

2 Play audio title and wait to the end if exist

3 Move to first scene object using movmentDuration*

4 Display first scene description

5 Play first scene audio if exist and wait to the end

6 Wait for delay*

7 hide first scene description

Go to next scene (step 3) or quit

*user define scenario properties.

Adding help button

MySpot provide a widget to easily add help button to your screen:

SpotButton.tutorial(
            context,HoleWidget(...

Defining scenario

To have more readable code you could define your tutorials in external class

class Tutorial {
  static HoleWidget home(context) => HoleWidget(
        scenario: SpotScenario(
          id: "home",
            ...
          child:MyScreenWidget()
          }

and then you can use just like this :

Navigator.push(
                      context,
                      MaterialPageRoute(
                        builder: (context) => Tutorial.home(context),
                      ),
                    );

And help button become just :

SpotButton.tutorial(context, Tutorial.home(context))

Defining endMode

EndMode define behavior after end of scenario. There is 3 modes :

redirectTochild

This is the default one. When end is reach we leave tutorial and navigate to the child widget.

loop

In this mode we play scenario in loop.

stayInactive

If you want to keep MySpot to read another scenario for exemple you must use this one.

Changing scénario

In some case it could be intresting having svereal scenario for one screen. For exemple a scenario for introducing screen then give the hand to user to do an action and play after that an other scenario or after returning from popup. For that you have to add key for HoleWidget et the use it as follow:

widget.spotKey?.currentState?.changeScenario(Tutorial.home2(
                      context,
                      HomeWidget()));

dependencies

shared_preferences: ^2.2.0 audioplayers: ^4.1.0

Powered by My-Numeric.com