Die Quiz-API für erweiterte Anpassungen nutzen

Mit der Quiz-API kommuniziert Ihr eigenes JavaScript mit einem Quiz, während ein Besucher es ausfüllt. Sie können auslesen, was er geantwortet hat, einen Block ändern, zu einem Schritt springen oder absenden – ganz ohne das Quiz im Builder anzufassen. Sie können sie überall einsetzen, wo JavaScript auf der Seite läuft: im Custom Code des Quiz, in einem Skript-Block oder in einem Snippet Ihres Tag-Managers.

Die API abrufen

Die API wird Ihnen vom Event ll-quiz-init als event.detail.llQuizApi übergeben. Bewahren Sie dieses Objekt auf und nutzen Sie es, wann immer Sie es brauchen.

window.addEventListener('ll-quiz-init', (event) => {
  const quiz = event.detail.llQuizApi;

  quiz.getBlock('firstName').setValue('Ada');
});

Ihr Skript kann vor oder nach dem Laden des Quiz ausgeführt werden. Registriert es sich spät, wird ll-quiz-init automatisch erneut an es gesendet – dieses Muster funktioniert also immer.

Jedes andere Quiz-Event trägt dieselbe llQuizApi, sodass Sie auch auf einen Schritt oder eine Antwort reagieren und direkt handeln können. Siehe Quiz-Events.

Schritte und Blöcke über den Namen

Jede Funktion, die einen Schritt oder Block entgegennimmt, akzeptiert dessen Namen oder ID. Namen sind die im Builder vergebenen Bezeichnungen – sie nutzen Sie im Normalfall. IDs werden generiert und sehen aus wie block-3f9c….

quiz.getBlock('email'); // über den Namen
quiz.getBlock('block-3f9c1a2e-…'); // über die ID, gleiches Ergebnis
quiz.getBlocksByStep('contact');

Geben Sie jedem Block und jedem Schritt im Builder einen klaren Namen. Mehr Einrichtung braucht die API nicht.

Tragen zwei Blöcke oder zwei Schritte denselben Namen, wird der erste in der Quiz-Reihenfolge verwendet.

Die Antworten auslesen

getAnswers() gibt alle bisher gegebenen Antworten zurück, einen Eintrag pro Block. getAnswersSimple() liefert dieselben Antworten als einfaches Objekt mit dem Label als Schlüssel. Ausgeblendete Blöcke und leere Antworten bleiben unberücksichtigt.

quiz.getAnswers();
// [{ id: 'firstName', label: 'First name', value: 'Ada', key: 'firstName', stepId: 'step-…', stepName: 'contact' }, …]

quiz.getAnswersSimple();
// { 'First name': 'Ada', 'Plan': 'pro' }

Das sind genau die fields und fieldsSimple, die die Events mitführen – Code, der mit dem einen umgeht, beherrscht also auch das andere.

Wissen, wo der Besucher steht

quiz.getCurrentStep(); // { id: 'step-…', name: 'contact', index: 1, total: 4 }
quiz.getCurrentStepBlocks(); // die Blöcke dieses Schritts
quiz.getSteps(); // [{ id, name, index }, …] in Quiz-Reihenfolge
quiz.getInfo(); // { quizId: 'quiz-…', isSubmitted: false }

index beginnt bei 0. isSubmitted wird true, sobald das Quiz in diesem Besuch abgesendet wurde.

Blöcke finden

Aufruf	Gibt zurück
`getBlocks()`	Jeden Block, der einen Wert enthält
`getBlock(nameOrId)`	Einen Block
`getBlocksByStep(nameOrId)`	Die Blöcke eines Schritts
`getCurrentStepBlocks()`	Die Blöcke des angezeigten Schritts

Listen enthalten nur Blöcke, die einen Wert speichern. Überschriften, Absätze, Bilder und Ähnliches erscheinen nie. getBlock() findet zusätzlich Schaltflächen (Continue, Previous, Submit, Button), sodass Sie deren Text ändern oder sie deaktivieren können.

getBlock() gibt nie undefined zurück. Passt nichts oder kann der Block keinen Wert speichern, erhalten Sie einen Platzhalter-Block: Jeder Aufruf darauf schreibt eine Warnung ins Log und bewirkt nichts, getValue() gibt "" zurück. Ihr Code stürzt nie ab – prüfen Sie aber die Konsole, wenn etwas wirkungslos bleibt.

Welche Blöcke speichern einen Wert?

Eingabefelder (Text, E-Mail, Telefon, Zahl, Textarea, Datum, Geburtsdatum, Postleitzahl, Adresse, OTP), Auswahlen (Multiple Choice, Bildauswahl, Select), Checkbox, Range Slider, Upload, Unterschrift und versteckte Felder.Alles übrige dient der Darstellung oder Navigation: Überschrift, Absatz, Bild, Video, Trenner, Liste, Loader, Countdown, Fortschritt, Accordion, Links, Custom Code, Tracking und die Schaltflächen. Ein Aufruf von getValue(), setValue(), reset() oder validate() auf einem davon löst einen Fehler aus. Container sind transparent: Die Blöcke darin werden wie jeder andere Block gelistet.

Einen Block auslesen und ändern

Jeder zurückgegebene Block ist dieselbe Art von Objekt – die folgenden Beispiele funktionieren also bei jedem Block, der den jeweiligen Aufruf unterstützt.

Wert

const name = quiz.getBlock('firstName');

name.getValue(); // 'Ada'
name.setValue('Grace');
name.reset(); // zurück auf leer

Ein über die API gesetzter Wert löst ll-quiz-value-change mit source: 'api' aus, sodass Ihre Listener ihn von einer Eingabe des Besuchers unterscheiden können.

Wertformate je Block

Checkbox: 'checked' oder 'unchecked'
Multiple Choice, Bildauswahl, Select: der Wert der Option, zum Beispiel 'pro'
Multiple Choice mit mehreren Auswahlen: die Werte, verbunden durch das im Block konfigurierte Trennzeichen
Alles übrige: der vom Besucher eingegebene Text

Label und Platzhalter

name.getLabel(); // 'First name'
name.setLabel('Given name');

name.getPlaceholder(); // 'Ada'
name.setPlaceholder('Type your first name');

quiz.getBlock('continue-1').setLabel('Next step'); // auch Schaltflächen

Labels sind reiner Text – außer bei einer Checkbox, wo HTML für Links zu den Bedingungen erlaubt ist. setLabel() und getLabel() lösen bei Blöcken ohne Label einen Fehler aus.

Optionen

Multiple-Choice-, Bildauswahl- und Select-Blöcke geben ihre Optionen preis:

quiz.getBlock('plan').getOptions();
// [{ id: 'option-…', label: 'Pro', value: 'pro', selected: true }, …]

Ein Aufruf von getOptions() auf einem anderen Block löst einen Fehler aus.

Fehler und Fokus

name.getErrors(); // ['This field is required.'] nach fehlgeschlagener Validierung, sonst []
name.focus(); // den Cursor dorthin setzen

Schaltflächen

const next = quiz.getBlock('continue-1');
next.disable();
await checkSomething(); // Ihre eigene asynchrone Arbeit
next.enable();

enable() und disable() funktionieren bei Continue-, Submit- und Button-Blöcken und lösen bei allen anderen einen Fehler aus.

Sichtbarkeit

const promo = quiz.getBlock('promoCode');

promo.visibility.hide();
promo.visibility.show();
promo.visibility.get(); // true, false oder undefined (keine Überschreibung)
promo.visibility.clear(); // Ihre Überschreibung entfernen

Ein ausgeblendeter Block wird nicht validiert, nicht mit dem Lead übertragen und nicht angezeigt. undefined bedeutet, dass Sie ihn nie geändert haben – der Block folgt dann seinen eigenen Einstellungen.

Validieren

const step = await quiz.validateStep('contact'); // { success: false }
const block = await quiz.getBlock('email').validate(); // { success: false, errors: ['Invalid email address.'] }

Die Validierung ist asynchron, weil E-Mail-, Telefon- und OTP-Felder gegen einen Server geprüft werden. Ausgeblendete Blöcke bestehen die Prüfung immer.

Schlägt ein Schritt fehl, löst das Quiz außerdem ll-quiz-validation-error mit jedem fehlerhaften Block und dessen Meldung aus, markiert mit source: 'api'. Ein einziger Listener kann damit sowohl die Versuche des Besuchers als auch Ihre eigenen behandeln. Details auf der Events-Seite.

Navigieren und absenden

await quiz.navigation.goNext();
quiz.navigation.goBack();
await quiz.navigation.goToStep('summary'); // Name oder ID
await quiz.navigation.submit();
quiz.navigation.goToUrl('https://example.com'); // mit `true` in neuem Tab öffnen

goNext(), goToStep() und submit() validieren zuerst den angezeigten Schritt. Ist er ungültig, bleiben sie stehen, schreiben eine Warnung ins Log und lösen ll-quiz-validation-error aus. goBack() validiert nie. submit() tut genau das, was die Submit-Schaltfläche des Besuchers tut: Der Lead wird gespeichert, ll-quiz-submit wird mit der Serverantwort ausgelöst, der Schutz gegen Mehrfachabsenden greift und die Nach-dem-Absenden-Aktion der Submit-Schaltfläche läuft. In einem Schritt ohne Submit-Schaltfläche sendet das Quiz ab und bleibt, wo es ist. Das zurückgegebene Promise wird aufgelöst, sobald all das abgeschlossen ist.

Rezepte

Aus der URL vorbefüllen

window.addEventListener('ll-quiz-init', (event) => {
  const quiz = event.detail.llQuizApi;
  const params = new URLSearchParams(window.location.search);

  if (params.get('email')) quiz.getBlock('email').setValue(params.get('email'));
  if (params.get('plan')) quiz.getBlock('plan').setValue(params.get('plan'));
});

Einen eigenen Fortschrittstext anzeigen

window.addEventListener('ll-quiz-step-view', (event) => {
  const { index, total } = event.detail.llQuizApi.getCurrentStep();
  document.querySelector('#progress').textContent = `Step ${index + 1} of ${total}`;
});

Zum ersten fehlerhaften Feld springen

window.addEventListener('ll-quiz-validation-error', (event) => {
  const { errors, llQuizApi } = event.detail;
  llQuizApi.getBlock(errors[0].blockId).focus();
});

Die Continue-Schaltfläche sperren, bis Ihre eigene Prüfung besteht

window.addEventListener('ll-quiz-step-view', async (event) => {
  const quiz = event.detail.llQuizApi;
  if (quiz.getCurrentStep().name !== 'eligibility') return;

  const next = quiz.getBlock('continue-eligibility');
  next.disable();
  const ok = await fetch('/api/eligible?zip=' + quiz.getBlock('zip').getValue()).then((r) => r.ok);
  if (ok) next.enable();
  else next.setLabel('Not available in your area');
});

Einen Block nur bei einer bestimmten Antwort anzeigen

window.addEventListener('ll-quiz-value-change', (event) => {
  const { blockName, value, llQuizApi } = event.detail;
  if (blockName !== 'plan') return;

  const promo = llQuizApi.getBlock('promoCode');
  value === 'premium' ? promo.visibility.show() : promo.visibility.hide();
});

Aus Ihrer eigenen Schaltfläche heraus absenden

window.addEventListener('ll-quiz-init', (event) => {
  const quiz = event.detail.llQuizApi;

  document.querySelector('#my-submit').addEventListener('click', async () => {
    await quiz.navigation.submit(); // validiert zuerst; wird nach ll-quiz-submit aufgelöst
    if (quiz.getInfo().isSubmitted) window.location.href = '/thank-you';
  });
});

Die Antworten an Ihren eigenen Endpunkt senden

window.addEventListener('ll-quiz-submit', (event) => {
  fetch('https://example.com/leads', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(event.detail.fieldsSimple),
  });
});

Alle Funktionen auf einen Blick

Funktion	Was sie tut
`getAnswers()` / `getAnswersSimple()`	Bisherige Antworten
`getCurrentStep()` / `getCurrentStepBlocks()`	Der angezeigte Schritt und seine Blöcke
`getSteps()` / `getInfo()`	Alle Schritte; Quiz-ID, abgesendet oder nicht
`getBlocks()` / `getBlock()` / `getBlocksByStep()`	Blöcke finden
`validateStep(nameOrId)`	Einen Schritt validieren
`navigation.goNext()` / `goBack()` / `goToStep()` / `submit()` / `goToUrl()`	Navigieren und absenden

Auf einem Block	Was es tut
`getValue()` / `setValue()` / `reset()`	Die Antwort
`getLabel()` / `setLabel()` / `getPlaceholder()` / `setPlaceholder()`	Texte
`getOptions()`	Optionen eines Auswahl- oder Select-Blocks
`validate()` / `getErrors()` / `focus()`	Validierung
`enable()` / `disable()`	Schaltflächen
`visibility.show()` / `hide()` / `get()` / `clear()`	Ein- oder ausblenden
`blockID` / `blockType` / `variableName`	Identität

Ältere Funktionsnamen (weiterhin unterstützt)

Frühere Versionen hatten je Abfragetyp eine eigene Funktion. Sie funktionieren unverändert weiter, sodass Sie bereits geschriebenen Code nicht anpassen müssen. Neuer Code sollte die vereinheitlichten Funktionen verwenden.

Älterer Name	Stattdessen verwenden
`getBlockByID(id)` / `getBlockByName(name)`	`getBlock()`
`getBlocksByStepID(id)` / `getBlocksByStepName(name)`	`getBlocksByStep()`
`validateStepByID(id)` / `validateStepByName(name)`	`validateStep()`

Erste Schritte

Landingpages

Visueller Editor (Canvas)

KI

Quizze (Funnels)

Workflows

Lead-Management

Domain

Mehrbenutzer

Testing und Reporting

Globale Blöcke

Integrationen

Profil

Die Quiz-API für erweiterte Anpassungen nutzen

Die API abrufen

Schritte und Blöcke über den Namen

Die Antworten auslesen

Wissen, wo der Besucher steht

Blöcke finden

Einen Block auslesen und ändern

Wert

Label und Platzhalter

Optionen

Fehler und Fokus

Schaltflächen

Sichtbarkeit

Validieren

Navigieren und absenden

Rezepte

Alle Funktionen auf einen Blick

​Die API abrufen

​Schritte und Blöcke über den Namen

​Die Antworten auslesen

​Wissen, wo der Besucher steht

​Blöcke finden

​Einen Block auslesen und ändern

​Wert

​Label und Platzhalter

​Optionen

​Fehler und Fokus

​Schaltflächen

​Sichtbarkeit

​Validieren

​Navigieren und absenden

​Rezepte

​Alle Funktionen auf einen Blick

Die API abrufen

Schritte und Blöcke über den Namen

Die Antworten auslesen

Wissen, wo der Besucher steht

Blöcke finden

Einen Block auslesen und ändern

Wert

Label und Platzhalter

Optionen

Fehler und Fokus

Schaltflächen

Sichtbarkeit

Validieren

Navigieren und absenden

Rezepte

Alle Funktionen auf einen Blick