Zum Inhalt springen
Wissensdatenbank

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.

Das Format enthält absichtlich kein HTML, kein CSS und keine Verweise auf Komponenten:

  1. Ihre UI-Komponenten: Stellen Sie jedes Steuerelement mit Ihrem eigenen Framework dar – React, Vue, Angular, eine native Mobil-App oder ein Terminal
  2. Ihr Styling: Fragen übernehmen ganz von selbst das Erscheinungsbild Ihrer Anwendung
  3. 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
  4. 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 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" ──► done

Informative Comment-Items werden auf dem Server automatisch verarbeitet – Clients erhalten immer nur beantwortbare Fragen.

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.

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.

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

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.

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.

  1. Legen Sie Umfragen für Ihre Befragten über die REST-API (POST /api/v1/surveys) oder über eine Kampagne an
  2. 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)
  3. Ihr Frontend stellt jedes Schrittdokument mit seinen eigenen Komponenten dar und sendet die Ergebnisse zurück
  4. 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.