Tovább a tartalomhoz
Tudástár

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:

  1. 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
  2. Az Ön stílusa: a kérdések természetes módon átveszik az alkalmazás megjelenését
  3. 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
  4. 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.

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

A tájékoztató Comment elemeket a szerver automatikusan feldolgozza – a kliensek csak megválaszolható kérdéseket kapnak.

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.

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.

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

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.

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.

  1. 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
  2. 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)
  3. A frontendje a saját komponenseivel jeleníti meg az egyes lépésdokumentumokat, és visszaküldi a kimeneteket
  4. 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.