A kérdőív megjelenítési formátuma
A kérdőív megjelenítési formátuma (Survey Presentation Format) az a JSON-szerződés, amellyel egy folyamatban lévő kitöltés lépésről lépésre vezérelhető. Minden kérdés önálló dokumentumként érkezik, amely mindent tartalmaz, ami a kliensnek a megjelenítéséhez kell – a feliratot, a beviteli vezérlő leírását és az érvényes opciókat –, miközben a menet logikája, az elágazások és a válaszok validációja a QML-motorban, a szerveren marad.
A kérdőív (Questionnaire) az igazolt sablon; a kitöltés (Survey) az, amikor egy válaszadó végigmegy rajta. A megjelenítési formátum mindig egy kitöltést ír le: az adott válaszadó következő kérdését, amelyet a rendszer a korábbi válaszaiból számít ki.
Keretrendszertől független kialakítás
Szekció neve “Keretrendszertől független kialakítás”A formátum szándékosan nem tartalmaz HTML-t, CSS-t vagy komponenshivatkozásokat:
- Az Ön UI-komponensei: minden vezérlőt a saját keretrendszerével jeleníthet meg – React, Vue, Angular, natív mobilalkalmazás vagy akár terminál
- Az Ön stílusa: a kérdések természetes módon átveszik az alkalmazás megjelenését
- Szerveroldali logika: az elágazások, az ugrási logika és az utófeltétel-validáció az igazolt QML-motorban marad – a kliens bárhogyan jeleníti is meg a kérdéseket, nem juthat érvénytelen útvonalra
- Kérdésenként egy oda-vissza hívás: a válasz beküldése a következő lépést is visszaadja a válaszban
Az Askalot saját kérdőívfuttatója (a SirWay) is ugyanennek az elemmodellnek a kliense – a formátum nem utólag hozzátett exportlehetőség: a kitöltések ténylegesen így zajlanak.
A kitöltési ciklus
Szekció neve “A kitöltési ciklus”Egy kitöltés vezérlése három hívásból álló állapotgép a REST API-n:
| Metódus | Végpont | Rendeltetés |
|---|---|---|
GET |
/api/v1/surveys/{id}/current-step |
Az aktuális kérdés, az opciók és az állapot. Az első híváskor inicializálja a munkamenetet. |
POST |
/api/v1/surveys/{id}/responses |
Válasz beküldése; a következő lépés a válaszban érkezik. |
POST |
/api/v1/surveys/{id}/finish |
A kitöltés kifejezett lezárása (idempotens). |
Ugyanez a három művelet MCP-eszközként is elérhető (get_survey_current_item, submit_survey_response, finish_survey) – lásd az MCP-kitöltési eszközök referenciáját.
A hitelesítés a szokásos REST-hitelesítő adattal, az X-Api-Token fejléccel történik (a token beállítása).
GET current-step ──► render item ──► POST responses ──► render `next` │ └── status == "completed" ──► doneA tájékoztató Comment elemeket a szerver automatikusan feldolgozza – a kliensek csak megválaszolható kérdéseket kapnak.
A lépésdokumentum
Szekció neve “A lépésdokumentum”A GET /api/v1/surveys/{id}/current-step válasza:
{ "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" } ]}| Mező | Jelentés |
|---|---|
status |
"in_progress" vagy "completed". Befejezett állapotban az item értéke null, a message pedig megmagyarázza, miért. |
item.id |
Az elem QML-azonosítója – a válasz beküldésekor ezt kell visszaküldeni. |
item.kind |
"Question", "QuestionGroup" vagy "MatrixQuestion" – ez határozza meg a beküldendő kimenet alakját. |
item.extras.title |
A megjelenítendő kérdésfelirat. |
item.text |
Opcionális, hosszabb leíró szöveg a felirat alatt. |
item.extras.input |
A nyers QML beviteli vezérlőleírás (a vezérlő neve és a beállításai – címkék, tartományok stb.). |
control_type |
Kisbetűs vezérlőtípus-azonosító a megjelenítő számára: radio, dropdown, checkbox, switch, slider, range, editbox, textarea. |
options |
Megjelenítésre kész opciók, előre kinyerve a vezérlőből (lásd alább). |
required |
Kötelező-e válaszolni a továbblépéshez. |
A válaszok numerikus kódok
Szekció neve “A válaszok numerikus kódok”Az Askalot a válaszokat mindenhol számként ábrázolja, kivéve a szabad szöveget (a textarea vezérlőt). Egy választós vezérlő labels leképezése egész értékű válaszkódokat rendel megjelenített szövegekhez – pl. {1: "Hourly", 2: "Daily", 3: "Weekly"} –, a lépésdokumentum pedig ezeket options párokként ({"value": <code>, "text": <label>}) adja át. A felhasználói felület a text értéket mutatja; amit beküld, az a kód. A numerikus bevitelek (editbox, slider) magát a számot küldik be, a range a tartományt [low, high] párként, a switch pedig az 1/0 kódot (az opciókban true/false értékként érkezik – a logikai értékeket a rendszer a numerikus megfelelőjükként fogadja el).
A JSON-szerializáció átvitel közben szöveggé alakíthatja a kódokat (a lenti példában a 0 címkekulcshoz "value": "0" tartozik); a motor beküldéskor visszaalakítja a numerikus szövegeket számmá, de érdemesebb valódi számokat küldeni.
Opciók vezérlőtípusonként
Szekció neve “Opciók vezérlőtípusonként”Az options tömb vezérlőtípusonként már megjelenítésre kész alakban érkezik:
control_type |
Az options alakja |
|---|---|
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 |
[] – a határokat (min/max, numerikus vezérlőknél) vagy a szövegbeállításokat az item.extras.input mezőből olvassa ki |
Válaszok beküldése
Szekció neve “Válaszok beküldése”POST /api/v1/surveys/{id}/responses az elem azonosítójával és a kimenettel:
{ "item_id": "q_question_switch", "outcome": true }A kimenet alakja az elem fajtájától függ. Az értékek a fent leírt numerikus válaszkódok – szabad szöveg csak a textarea vezérlőnél:
| Elemfajta / vezérlő | A kimenet alakja | Példa |
|---|---|---|
Question (radio, dropdown, slider, editbox) |
Egyetlen szám – a válaszkód (választós vezérlőknél) vagy maga az érték (numerikus vezérlőknél) | 2, 42 |
Question range vezérlővel |
Egy [low, high] pár, ahol min <= low <= high <= max |
[20, 45] |
Question switch vezérlővel |
1/0 (true/false is elfogadott) |
true |
Question checkbox vezérlővel |
Bitmaszk egész szám – a kiválasztott válaszkódok összege (a kódok 2 hatványai) | 5 (az 1-es + a 4-es kód) |
Question textarea vezérlővel |
Szabad szöveges karakterlánc | "We mostly use it on weekends" |
QuestionGroup |
Számok tömbje, a questions minden bejegyzéséhez egy – minden alkérdés a csoport egyetlen vezérlőjén osztozik, így minden érték ugyanabból a kódtérből származik |
[1, 3, 2] |
MatrixQuestion |
Számok beágyazott tömbje, rows × columns – minden cellához ugyanaz az egy közös vezérlő tartozik |
[[1, 2], [3, 1]] |
range vezérlő esetén a QuestionGroup minden alkérdése és a MatrixQuestion minden cellája szám helyett egy [low, high] pár (kétkérdéses csoportnál [[1, 3], [2, 6]]).
A válasz a következő lépést is tartalmazza, így kérdésenként egy oda-vissza hívás elég:
{ "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" }}Ha a beküldés lezárja a kitöltést, a status értéke "completed", a next értéke pedig null.
Szerveroldali validáció
Szekció neve “Szerveroldali validáció”A QML-ben megírt utófeltételeket (pl. a gyermekek száma kevesebb kell legyen, mint a háztartás tagjaié) a rendszer beküldéskor értékeli ki. Elutasított válasz esetén hibaválaszt ad vissza, amelynek detail mezője a kérdés tippüzenetét tartalmazza, és a menet nem lép tovább – jelenítse meg újra az aktuális elemet a tippel együtt. A kliensnek soha nem kell megismételnie a validációs szabályokat; ezek a kérdőív formális definíciójának részei.
Szokásos beágyazási minta
Szekció neve “Szokásos beágyazási minta”- Hozzon létre kitöltéseket a válaszadói számára a REST API-n keresztül (
POST /api/v1/surveys) vagy egy kampánnyal - A backendje a saját API-tokenjével továbbítja a három menetvezérlő hívást (a tokent tartsa a szerveroldalon – soha ne juttassa el a böngészőbe)
- A frontendje a saját komponenseivel jeleníti meg az egyes lépésdokumentumokat, és visszaküldi a kimeneteket
status: "completed"esetén zárja le a munkamenetet; a válaszok azonnal elérhetők az adatfeldolgozási folyamat számára
Ha nincs szüksége egyedi megjelenítésre, az Askalot által üzemeltetett kérdőívfuttató (a SirWay) már minden kérdőívet kiszolgál egy belépési linken – a megjelenítési formátum arra az esetre való, amikor a kérdőívnek az Ön termékének részeként kell megjelennie.