Aller au contenu
Base de connaissances

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.

Le format ne contient délibérément ni HTML, ni CSS, ni référence à des composants :

  1. Vos composants d’interface : affichez chaque contrôle avec votre propre framework — React, Vue, Angular, une application mobile native ou un terminal
  2. Votre style : les questions adoptent naturellement l’apparence de votre application
  3. 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
  4. 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.

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" ──► done

Les items informatifs Comment sont traités automatiquement sur le serveur : les clients ne reçoivent jamais que des questions auxquelles on peut répondre.

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.

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.

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

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.

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.

  1. Créez des enquêtes pour vos répondants via l’API REST (POST /api/v1/surveys) ou via une campagne
  2. Votre backend relaie les trois appels de parcours avec son jeton API (gardez le jeton côté serveur — ne l’envoyez jamais à un navigateur)
  3. Votre frontend affiche chaque document d’étape avec ses propres composants et renvoie les résultats
  4. À 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.