Skip to content

Commit 27d443c

Browse files
AlexandreSiAlexandreSi
authored
Initiate in-app tutorial documentation
2 parents 67d1741 + be9924a commit 27d443c

3 files changed

Lines changed: 178 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,13 @@
11
# GDevelop-tutorials
2+
3+
![GDevelop logo](https://raw.githubusercontent.com/4ian/GDevelop/master/newIDE/GDevelop%20banner.png "GDevelop logo")
4+
5+
This repository holds official tutorials for the [GDevelop](https://gdevelop.io) editor.
6+
7+
At the moment, tutorials can only take the form of an in-app tutorial that guides a user step by step into accomplishing a specific task or discovering a whole part of the editor.
8+
9+
## Getting Started
10+
11+
| ❔ I want to... | 🚀 What to do |
12+
| ------------------------------- | ------------------------------------------------------------------------------ |
13+
| Create an in-app tutorial | First read [this README](./docs/inAppTutorial/README.md) and then submit a new tutorial of your own |

‎docs/inAppTutorial/README.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# In-App Tutorial
2+
3+
An in-app tutorial is a sequenced step by step tutorial that is displayed to the user directly in the editor.
4+
It reacts to user actions through different ways that are explained below.
5+
6+
GDevelop created its own components and orchestrator so that one can create a whole tutorial with only a JSON file. They are greatly inspired by [Userflow](https://userflow.com) work.
7+
8+
You can have a look at the components in [the editor storybook](https://gdevelop-storybook.s3.amazonaws.com/master/latest/index.html?path=/story/in-app-tutorial-elementhighlighterandtooltipdisplayer--default).
9+
10+
## How To Create An In-App Tutorial
11+
12+
Have a look at the [documentation](./REFERENCE.md) to learn how to build your JSON.

‎docs/inAppTutorial/REFERENCE.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
# GDevelop In-App Tutorial Documentation
2+
3+
## How is handled the translation?
4+
5+
To display the tutorial with different languages, every text that you will specify has to be an object `messageByLocale` with locales as keys and the translated sentence as value.
6+
7+
For example, this will be the description of a tooltip:
8+
9+
```json
10+
{
11+
...,
12+
"description": {
13+
"messageByLocale": {
14+
"en": "Click on the button",
15+
"fr-fr": "Cliquez sur le bouton"
16+
}
17+
}
18+
}
19+
```
20+
21+
Note: If the user language is not available, it will fallback to english.
22+
23+
## JSON Structure
24+
25+
An in-app tutorial is a JSON with 4 fields:
26+
27+
```json
28+
{
29+
"id": "physics2-joints",
30+
"flow": [...],
31+
"editorSwitches": {...},
32+
"endDialog": {...}
33+
}
34+
```
35+
36+
### `id`
37+
38+
This id is a string that should be unique across all in-app tutorials.
39+
40+
### `endDialog`
41+
42+
This field holds the content for the dialog that will displayed after the user has completed the last step of the [flow](#flow).
43+
44+
It's a field that contains an array under the `content` key.
45+
46+
The array contains either:
47+
48+
- an image (that can be clickable if `linkHref` field is provided)
49+
50+
```json
51+
{
52+
...,
53+
"endDialog": {
54+
"content": [
55+
...,
56+
{
57+
"image": {
58+
"imageSource": "https://resources.gdevelop-app.com/...",
59+
"linkHref": "https://gdevelop.io"
60+
}
61+
]
62+
}
63+
}
64+
```
65+
66+
- a text
67+
68+
```json
69+
{
70+
...,
71+
"endDialog": {
72+
"content": [
73+
...,
74+
{
75+
"text": {
76+
"messageByLocale": {
77+
"en": "you made it until the end of the tutorial!"
78+
}
79+
}
80+
}
81+
]
82+
}
83+
}
84+
```
85+
86+
### `flow`
87+
88+
A flow is an array of steps.
89+
90+
A step is more or less an element to highlight plus a trigger that can be detected programmatically to decide to go to the next step.
91+
92+
Here is the structure of a step (all fields are optional):
93+
94+
- `id` (string): Id of the step (useful for shortcuts and editor switches)
95+
- `elementToHighlightId` (string): the CSS selector of the element to highlight
96+
- `nextStepTrigger`: See [Triggers](#triggers)
97+
- `tooltip`: See [Tooltip](#tooltip)
98+
- `isTriggerFlickering`(true): Useful when a DOM mutation is not caught and the presence trigger is not fired.
99+
- `shortcuts`: List of steps that the flow can use as shortcuts.
100+
- `stepId`: id of the step to jump to
101+
- `trigger`: DOM trigger (presence of absence of element)
102+
- `skippable` (true): if the step can be skipped (useful when the user interaction can result in this step not being mandatory)
103+
- `isOnClosableDialog` (true): if the step is on a closable dialog, if the element to highlight is missing (meaning the dialog has been closed), the flow will go back to the previous step that is not on a closable dialog.
104+
105+
#### **Triggers**
106+
107+
At the moment, only one trigger can be specified to go the next step. Here is the list of supported triggers:
108+
109+
- `presenceOfElement` (string): the CSS selector of an element present in the DOM
110+
- `absenceOfElement` (string): the CSS selector of an element absent from the DOM
111+
- `valueHasChanged` (true): the CSS selector of an input whose value has changed
112+
- `instanceAddedOnScene` (string): the name of an object for which an instance has been added on the scene
113+
- `previewLaunched` (true): a preview has been launched
114+
- `clickOnTooltipButton` (string): the label of the button displayed in the tooltip that the user has to click to go to the next step.
115+
116+
Notes:
117+
118+
- You can learn about CSS selectors [here](https://www.w3schools.com/cssref/css_selectors.asp).
119+
120+
#### **Tooltip**
121+
122+
For each step, you can specify a tooltip to display next to the element you want to highlight. A tooltip contains the 3 following fields:
123+
124+
- `title`: (optional) Translated text
125+
- `description`: (optional) Translated text
126+
- `placement`: The placement of the tooltip relatively to the element to highlight. Either one of those values: `bottom`, `top`, `left`, `right` (default value `bottom`)
127+
128+
Notes:
129+
130+
- At least one field among `title` and `description` should be provided. If you don't want to display a tooltip, do not provide the `tooltip` field in your step.
131+
132+
### `editorSwitches`
133+
134+
The orchestrator detects when the user went into an editor (either the home page, a scene editor or an events sheet) that does not allow the tutorial to be continued.
135+
136+
For this to work, you must provide the editor switches that happen during your tutorial. Here is how to do it:
137+
138+
If your flow contains a step with id `ClickOnCreateObjectButton` (that should happen in the scene editor) and another step `ClickOnAddEventButton` (that should happen in the events sheet), here is what the field should look like:
139+
140+
```json
141+
{
142+
...,
143+
"editorSwitches": {
144+
{
145+
"ClickOnCreateObjectButton": "Scene",
146+
"ClickOnAddEventButton": "EventsSheet",
147+
}
148+
}
149+
}
150+
```
151+
152+
Notes:
153+
154+
- The possible values for the expected editor are: `Scene`, `EventsSheet`, `Home` (other editors are not supported at the moment)

0 commit comments

Comments
 (0)