Format de présentation des enquêtes
Le format de présentation des enquêtes est le contrat JSON qui permet de conduire pas à pas une session d’enquête en direct. Chaque question arrive sous la forme d’un document autonome contenant tout ce dont un client a besoin pour l’afficher — intitulé, spécification du contrôle de saisie et options valides —, tandis que le moteur QML conserve sur le serveur la logique du parcours, les branchements et la validation des réponses.
Un questionnaire est le modèle vérifié ; une enquête est la session d’un répondant qui le parcourt. Le format de présentation décrit toujours une enquête : la question suivante pour ce répondant, calculée à partir de ses réponses précédentes.
Indépendant du framework par conception
Section intitulée « Indépendant du framework par conception »Le format ne contient délibérément ni HTML, ni CSS, ni référence à des composants :
- Vos composants d’interface : affichez chaque contrôle avec votre propre framework — React, Vue, Angular, une application mobile native ou un terminal
- Votre style : les questions adoptent naturellement l’apparence de votre application
- Une logique côté serveur : les branchements, les sauts de questions et la validation des postconditions restent dans le moteur QML vérifié — un client ne peut pas, par son affichage, emprunter un chemin invalide
- Un aller-retour par question : l’envoi d’une réponse renvoie l’étape suivante, incluse dans la réponse de l’API
Le moteur d’enquête d’Askalot lui-même (SirWay) est un client de ce même modèle d’items : le format n’est pas un export annexe, mais la manière dont les enquêtes sont réellement conduites.
La boucle de parcours
Section intitulée « La boucle de parcours »Piloter une enquête revient à faire fonctionner une machine à états à trois appels sur l’API REST :
| Méthode | Point de terminaison | Rôle |
|---|---|---|
GET |
/api/v1/surveys/{id}/current-step |
Question courante + options + statut. Initialise la session au premier appel. |
POST |
/api/v1/surveys/{id}/responses |
Envoie une réponse ; l’étape suivante est incluse dans la réponse de l’API. |
POST |
/api/v1/surveys/{id}/finish |
Termine explicitement l’enquête (idempotent). |
Les trois mêmes opérations sont disponibles sous forme d’outils MCP (get_survey_current_item, submit_survey_response, finish_survey) — consultez la référence des outils MCP d’enquête.
L’authentification utilise les identifiants REST standard — l’en-tête X-Api-Token (configuration du jeton).
GET current-step ──► render item ──► POST responses ──► render `next` │ └── status == "completed" ──► doneLes items informatifs Comment sont traités automatiquement sur le serveur : les clients ne reçoivent jamais que des questions auxquelles on peut répondre.
Le document d’étape
Section intitulée « Le document d’étape »GET /api/v1/surveys/{id}/current-step renvoie :
{ "survey_id": "c154e81f-4c19-4998-9ffc-df6fee50561f", "status": "in_progress", "control_type": "switch", "required": true, "message": null, "item": { "id": "q_question_switch", "kind": "Question", "text": null, "survey_id": "c154e81f-4c19-4998-9ffc-df6fee50561f", "extras": { "title": "Do you agree to participate in this survey?", "blockId": "block2", "input": { "control": "Switch", "true": "Yes", "false": "No" }, "outcome": null, "visited": false } }, "options": [ { "value": true, "text": "Yes" }, { "value": false, "text": "No" } ]}| Champ | Signification |
|---|---|
status |
"in_progress" ou "completed". Une fois l’enquête terminée, item vaut null et message en explique la raison. |
item.id |
L’identifiant QML de l’item — renvoyez-le lors de l’envoi de la réponse. |
item.kind |
"Question", "QuestionGroup" ou "MatrixQuestion" — détermine la forme du résultat que vous envoyez. |
item.extras.title |
L’intitulé de la question à afficher. |
item.text |
Texte descriptif plus long, facultatif, affiché sous l’intitulé. |
item.extras.input |
La spécification brute du contrôle de saisie QML (nom du contrôle et sa configuration — libellés, intervalles, etc.). |
control_type |
Discriminant du contrôle, en minuscules, destiné à l’affichage : radio, dropdown, checkbox, switch, slider, range, editbox, textarea. |
options |
Options prêtes à afficher, extraites à l’avance du contrôle (voir ci-dessous). |
required |
Indique si une réponse est obligatoire pour avancer. |
Les réponses sont des codes numériques
Section intitulée « Les réponses sont des codes numériques »Askalot représente les réponses par des nombres partout, sauf pour le texte libre (le contrôle textarea). Les labels d’un contrôle à choix associent des codes de réponse entiers à des libellés — par exemple {1: "Hourly", 2: "Daily", 3: "Weekly"} —, et le document d’étape les fournit sous forme de paires options ({"value": <code>, "text": <label>}). Votre interface affiche le text ; ce que vous envoyez, c’est le code. Les saisies numériques (editbox, slider) envoient le nombre lui-même, range envoie l’intervalle sous forme de paire [low, high], et switch correspond au code 1/0 (fourni sous la forme true/false dans les options — les booléens sont acceptés comme leurs équivalents numériques).
La sérialisation JSON peut transformer les codes en chaînes lors de la transmission (l’exemple ci-dessous montre "value": "0" pour la clé de libellé 0) ; le moteur reconvertit les chaînes numériques en nombres à l’envoi, mais envoyez de préférence de vrais nombres.
Options par type de contrôle
Section intitulée « Options par type de contrôle »Le tableau options est préparé sous une forme directement affichable, propre à chaque contrôle :
control_type |
Forme de options |
|---|---|
radio, dropdown, checkbox |
[{ "value": <integer answer code>, "text": <label> }, ...] |
slider |
[{ "type": "range", "min": 0, "max": 100, "step": 1 }] |
switch |
[{ "value": true, "text": "Yes" }, { "value": false, "text": "No" }] |
editbox, range, textarea |
[] — lisez les bornes (min/max, contrôles numériques) ou la configuration du texte dans item.extras.input |
Envoyer les réponses
Section intitulée « Envoyer les réponses »POST /api/v1/surveys/{id}/responses avec l’identifiant de l’item et le résultat :
{ "item_id": "q_question_switch", "outcome": true }La forme du résultat dépend du type d’item. Les valeurs sont les codes de réponse numériques décrits ci-dessus — le texte libre n’est utilisé que pour le contrôle textarea :
| Type d’item / contrôle | Forme du résultat | Exemple |
|---|---|---|
Question (radio, dropdown, slider, editbox) |
Un seul nombre — le code de réponse (contrôles à choix) ou la valeur elle-même (contrôles numériques) | 2, 42 |
Question avec un contrôle range |
Une paire [low, high] avec min <= low <= high <= max |
[20, 45] |
Question avec un contrôle switch |
1/0 (true/false acceptés) |
true |
Question avec un contrôle checkbox |
Entier servant de masque de bits — somme des codes de réponse sélectionnés (les codes sont des puissances de 2) | 5 (codes 1 + 4) |
Question avec un contrôle textarea |
Chaîne de texte libre | "We mostly use it on weekends" |
QuestionGroup |
Tableau de nombres, un par entrée de questions — toutes les sous-questions partagent le contrôle unique du groupe, si bien que toutes les valeurs proviennent du même espace de codes |
[1, 3, 2] |
MatrixQuestion |
Tableau imbriqué de nombres, rows × columns — un même contrôle partagé par toutes les cellules |
[[1, 2], [3, 1]] |
Avec un contrôle range, chaque sous-question d’un QuestionGroup et chaque cellule d’une MatrixQuestion est une paire [low, high] au lieu d’un nombre ([[1, 3], [2, 6]] pour un groupe de deux questions).
La réponse de l’API intègre l’étape suivante ; un seul aller-retour par question suffit donc :
{ "survey_id": "c154e81f-4c19-4998-9ffc-df6fee50561f", "status": "in_progress", "output": null, "next": { "control_type": "radio", "item": { "id": "q_question_radio", "kind": "Question", "extras": { "title": "Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris?", "input": { "control": "Radio", "labels": { "0": "Option 0", "1": "Option 1" } } } }, "options": [ { "value": "0", "text": "Option 0" }, { "value": "1", "text": "Option 1" } ], "required": true, "status": "in_progress" }}Lorsque l’envoi termine l’enquête, status vaut "completed" et next vaut null.
Validation côté serveur
Section intitulée « Validation côté serveur »Les postconditions écrites dans le QML (par exemple, le nombre d’enfants doit être inférieur au nombre de membres du foyer) sont évaluées à l’envoi. Une réponse refusée renvoie une enveloppe d’erreur dont le champ detail contient le message d’aide de la question, et le parcours n’avance pas — affichez de nouveau l’item courant avec ce message. Le client n’a jamais besoin de reproduire les règles de validation : elles accompagnent la définition formelle du questionnaire.
Schéma d’intégration type
Section intitulée « Schéma d’intégration type »- Créez des enquêtes pour vos répondants via l’API REST (
POST /api/v1/surveys) ou via une campagne - Votre backend relaie les trois appels de parcours avec son jeton API (gardez le jeton côté serveur — ne l’envoyez jamais à un navigateur)
- Votre frontend affiche chaque document d’étape avec ses propres composants et renvoie les résultats
- À la réception de
status: "completed", fermez la session ; les réponses sont immédiatement disponibles pour le pipeline de données
Si vous n’avez pas besoin d’un affichage personnalisé, le moteur d’enquête hébergé d’Askalot (SirWay) sert déjà chaque enquête via un lien magique — le format de présentation est destiné aux cas où l’enquête doit s’intégrer à l’expérience de votre produit.