Survey Presentation Format
Das Survey Presentation Format ist der JSON-Vertrag, mit dem eine laufende Umfragesitzung Schritt für Schritt durchgeführt wird. Jede Frage kommt als in sich geschlossenes Dokument an, das alles enthält, was ein Client zur Darstellung braucht – Titel, Spezifikation des Steuerelements und die gültigen Optionen –, während die QML-Engine Ablauflogik, Verzweigungen und Antwortvalidierung auf dem Server behält.
Ein Fragebogen ist die verifizierte Vorlage; eine Umfrage ist die Sitzung einer befragten Person darin. Das Presentation Format beschreibt immer eine Umfrage: die nächste Frage für diese befragte Person, berechnet aus ihren bisherigen Antworten.
Bewusst frameworkunabhängig
Abschnitt betitelt „Bewusst frameworkunabhängig“Das Format enthält absichtlich kein HTML, kein CSS und keine Verweise auf Komponenten:
- Ihre UI-Komponenten: Stellen Sie jedes Steuerelement mit Ihrem eigenen Framework dar – React, Vue, Angular, eine native Mobil-App oder ein Terminal
- Ihr Styling: Fragen übernehmen ganz von selbst das Erscheinungsbild Ihrer Anwendung
- Logik auf dem Server: Verzweigungen, Filterführung und die Validierung der Nachbedingungen bleiben in der verifizierten QML-Engine – ein Client kann durch seine Darstellung nicht auf einen ungültigen Pfad geraten
- Ein Roundtrip pro Frage: Das Absenden einer Antwort liefert den nächsten Schritt gleich in der Antwort mit
Auch Askalots eigene Umfrageoberfläche (SirWay) ist ein Client genau dieses Item-Modells – das Format ist kein Nebenprodukt, sondern die Art, wie Umfragen tatsächlich durchgeführt werden.
Die Ablaufschleife
Abschnitt betitelt „Die Ablaufschleife“Die Steuerung einer Umfrage ist ein Zustandsautomat mit drei Aufrufen der REST-API:
| Methode | Endpunkt | Zweck |
|---|---|---|
GET |
/api/v1/surveys/{id}/current-step |
Aktuelle Frage + Optionen + Status. Initialisiert die Sitzung beim ersten Aufruf. |
POST |
/api/v1/surveys/{id}/responses |
Eine Antwort absenden; der nächste Schritt ist in der Antwort enthalten. |
POST |
/api/v1/surveys/{id}/finish |
Die Umfrage ausdrücklich abschließen (idempotent). |
Dieselben drei Operationen gibt es als MCP-Tools (get_survey_current_item, submit_survey_response, finish_survey) – siehe Umfrage-Tools – MCP-Tool-Referenz.
Zur Authentifizierung dienen die üblichen REST-Zugangsdaten – der Header X-Api-Token (Token einrichten).
GET current-step ──► render item ──► POST responses ──► render `next` │ └── status == "completed" ──► doneInformative Comment-Items werden auf dem Server automatisch verarbeitet – Clients erhalten immer nur beantwortbare Fragen.
Das Schrittdokument
Abschnitt betitelt „Das Schrittdokument“GET /api/v1/surveys/{id}/current-step liefert:
{ "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" } ]}| Feld | Bedeutung |
|---|---|
status |
"in_progress" oder "completed". Bei Abschluss ist item gleich null, und message erklärt, warum. |
item.id |
Die QML-Kennung des Items – senden Sie sie beim Absenden der Antwort wieder mit. |
item.kind |
"Question", "QuestionGroup" oder "MatrixQuestion" – bestimmt die Form des Ergebnisses, das Sie absenden. |
item.extras.title |
Der anzuzeigende Fragentitel. |
item.text |
Optionaler längerer Beschreibungstext unter dem Titel. |
item.extras.input |
Die unveränderte QML-Spezifikation des Steuerelements (Name des Steuerelements und seine Konfiguration – Beschriftungen, Bereiche usw.). |
control_type |
Kleingeschriebene Kennung des Steuerelements für den Renderer: radio, dropdown, checkbox, switch, slider, range, editbox, textarea. |
options |
Darstellungsfertige Optionen, bereits aus dem Steuerelement extrahiert (siehe unten). |
required |
Ob eine Antwort nötig ist, um fortzufahren. |
Antworten sind numerische Codes
Abschnitt betitelt „Antworten sind numerische Codes“Askalot stellt Antworten überall als Zahlen dar, außer bei offenem Text (dem Steuerelement textarea). Die labels eines Auswahl-Steuerelements ordnen ganzzahligen Antwortcodes Anzeigetexte zu – z. B. {1: "Hourly", 2: "Daily", 3: "Weekly"} –, und das Schrittdokument liefert sie als options-Paare ({"value": <code>, "text": <label>}). Ihre Oberfläche zeigt den text; abgesendet wird der Code. Numerische Eingaben (editbox, slider) senden die Zahl selbst, range sendet das Intervall als Paar [low, high], und switch ist der Code 1/0 (in den aufbereiteten Optionen als true/false geliefert – boolesche Werte werden als ihre numerischen Entsprechungen akzeptiert).
Die JSON-Serialisierung kann Codes bei der Übertragung in Zeichenketten verwandeln (das Beispiel unten zeigt "value": "0" für den Beschriftungsschlüssel 0); die Engine wandelt numerische Zeichenketten beim Absenden zwar in Zahlen zurück, senden Sie aber besser gleich echte Zahlen.
Optionen nach Steuerelementtyp
Abschnitt betitelt „Optionen nach Steuerelementtyp“Das Array options ist für jedes Steuerelement bereits in eine darstellbare Form gebracht:
control_type |
Form von 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 |
[] – lesen Sie die Grenzen (min/max, numerische Steuerelemente) oder die Textkonfiguration aus item.extras.input |
Antworten absenden
Abschnitt betitelt „Antworten absenden“POST /api/v1/surveys/{id}/responses mit der Item-Kennung und dem Ergebnis:
{ "item_id": "q_question_switch", "outcome": true }Die Form des Ergebnisses richtet sich nach der Item-Art. Die Werte sind die oben beschriebenen numerischen Antwortcodes – Freitext nur beim Steuerelement textarea:
| Item-Art / Steuerelement | Form des Ergebnisses | Beispiel |
|---|---|---|
Question (radio, dropdown, slider, editbox) |
Eine einzelne Zahl – der Antwortcode (Auswahl-Steuerelemente) oder der Wert selbst (numerische Steuerelemente) | 2, 42 |
Question mit Steuerelement range |
Ein Paar [low, high] mit min <= low <= high <= max |
[20, 45] |
Question mit Steuerelement switch |
1/0 (true/false werden akzeptiert) |
true |
Question mit Steuerelement checkbox |
Bitmasken-Ganzzahl – Summe der ausgewählten Antwortcodes (die Codes sind Zweierpotenzen) | 5 (Codes 1 + 4) |
Question mit Steuerelement textarea |
Freitext als Zeichenkette | "We mostly use it on weekends" |
QuestionGroup |
Array von Zahlen, eine je Eintrag in questions – alle Teilfragen teilen sich das eine Steuerelement der Gruppe, daher stammen alle Werte aus demselben Coderaum |
[1, 3, 2] |
MatrixQuestion |
Verschachteltes Array von Zahlen, rows × columns – ein gemeinsames Steuerelement für jede Zelle |
[[1, 2], [3, 1]] |
Bei einem Steuerelement range ist jede Teilfrage einer QuestionGroup und jede Zelle einer MatrixQuestion statt einer Zahl ein Paar [low, high] ([[1, 3], [2, 6]] für eine Gruppe mit zwei Fragen).
Die Antwort enthält bereits den nächsten Schritt, sodass ein Roundtrip pro Frage genügt:
{ "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" }}Schließt die Antwort die Umfrage ab, ist status gleich "completed" und next gleich null.
Validierung auf dem Server
Abschnitt betitelt „Validierung auf dem Server“Im QML formulierte Nachbedingungen (z. B. es muss weniger Kinder als Haushaltsmitglieder geben) werden beim Absenden ausgewertet. Auf eine abgelehnte Antwort folgt eine Fehlerantwort, deren Feld detail den Hinweistext der Frage enthält, und der Ablauf geht nicht weiter – stellen Sie das aktuelle Item mit dem Hinweis erneut dar. Der Client muss Validierungsregeln nie nachbilden; sie gehören zur formalen Definition des Fragebogens.
Typisches Einbettungsmuster
Abschnitt betitelt „Typisches Einbettungsmuster“- Legen Sie Umfragen für Ihre Befragten über die REST-API (
POST /api/v1/surveys) oder über eine Kampagne an - Ihr Backend leitet die drei Ablaufaufrufe mit seinem API-Token weiter (das Token bleibt auf dem Server – geben Sie es nie an einen Browser weiter)
- Ihr Frontend stellt jedes Schrittdokument mit seinen eigenen Komponenten dar und sendet die Ergebnisse zurück
- Bei
status: "completed"schließen Sie die Sitzung; die Antworten stehen sofort für die Daten-Pipeline bereit
Brauchen Sie keine eigene Darstellung, liefert die von Askalot gehostete Umfrageoberfläche (SirWay) bereits jede Umfrage über einen Magic Link aus – das Presentation Format ist für die Fälle gedacht, in denen die Umfrage Teil Ihres Produkterlebnisses sein muss.