Zuletzt geändert am:
Mit der Formcentric Event API können Sie sehen, wann bestimmte Aktionen in Ihren Formularen stattfinden – zum Beispiel ein Absenden oder ein Fehler. Diese Ereignisse können automatisch an Tracking-Dienste wie Matomo, Google Analytics oder andere Analyse-Tools weitergeleitet werden.
Die API bietet eine einheitliche Schnittstelle, über die Sie relevante Ereignisse abonnieren und in Ihren eigenen Tracking-Lösungen verwenden können.
Die Event API steht automatisch zur Verfügung, sobald das Formcentric-Script geladen ist. Um Event-Listener zuverlässig zu registrieren, verwenden Sie das formcentric:loaded Custom Event.
Jedes Event folgt einer einheitlichen Struktur mit folgenden Basis-Eigenschaften:
Eigenschaft |
Typ |
Beschreibung |
eventType |
string | Event-Bezeichner (z.B. 'form:init:complete') |
timestamp |
number | Unix-Zeitstempel in Millisekunden |
embedId |
string | Eindeutige ID der Formular-Instanz |
formId |
string (optional) | Formular-UID (verfügbar nach Initialisierung) |
formName |
string (optional) | Formularname (über data-fc-name gesetzt oder in Formcentric Editor gewählter Formularname, falls vorhanden) |
Die Formcentric Event API stellt verschiedene Kategorien von Events bereit, um Nutzerinteraktionen, Validierung und Formular-Lebenszyklen zu tracken:
Diese Events verfolgen den Lebenszyklus einer Formular-Instanz.
Event |
Beschreibung |
Verfügbare Properties |
form:init:start |
Wrapper beginnt mit der Formular-Initialisierung | eventType, embedId, timestamp |
form:init:complete |
Formular vollständig geladen und gerendert | eventType, embedId, formId, formName, pageCount, timestamp |
form:stop |
Formapp-Instanz wurde gestoppt | eventType, embedId, reason ('user', 'error', 'navigation', 'system'), timestamp |
form:unmount |
Formapp-Instanz aus DOM entfernt | eventType, embedId, timestamp |
form:reload |
Formular wurde neu geladen | eventType, embedId, trigger, timestamp |
form:cancel |
Formular wurde abgebrochen | eventType, embedId, formId, formName, currentPage, timestamp |
form:submitted |
Formular wurde erfolgreich abgeschickt | eventType, embedId, formId, formName, fromPage, view, submissionTime, timestamp |
Diese Events verfolgen die Navigation zwischen Formularseiten und die Formularübermittlung.
Event |
Beschreibung |
Verfügbare Properties |
page:change:start |
Seitenwechsel oder Übermittlung gestartet |
eventType, embedId, formId, formName, fromPage, toPage, direction ('forward', 'backward'), isSubmit, timestamp |
page:change:success |
Seitenwechsel oder Übermittlung erfolgreich |
eventType, embedId, formId, formName, fromPage, toPage, direction, isSubmit, submissionTime (nur bei Submit), timestamp |
page:change:failed |
Seitenwechsel oder Übermittlung fehlgeschlagen |
eventType, embedId, formId, formName, fromPage, toPage, direction, isSubmit, reason ('validation', 'server', 'network', 'timeout'), errorMessage (optional), timestamp |
Diese Events erfassen die Interaktion mit einzelnen Formularfeldern.
Event |
Beschreibung |
Verfügbare Properties |
field:input |
Nutzer:in gibt Daten in Feld ein |
eventType, embedId, formId, formName, currentPage, fieldName, fieldLabel, fieldType, valueLength, timestamp |
field:focus |
Feld erhält Fokus |
eventType, embedId, formId, formName, currentPage, fieldName, fieldLabel, fieldType, timestamp |
field:blur |
Feld verliert Fokus |
eventType, embedId, formId, formName, currentPage, fieldName, fieldLabel, fieldType, timestamp |
Diese Events melden Validierungsergebnisse für einzelne Formularfelder.
Event |
Beschreibung |
Verfügbare Properties |
validation:success |
Feld erfolgreich validiert |
eventType, embedId, formId, formName, currentPage, fieldName, fieldLabel, timestamp |
validation:error |
Validierungsfehler aufgetreten |
eventType, embedId, formId, formName, currentPage, fieldName, fieldLabel, errorCode, errorMessage, timestamp |
validation:cleared |
Validierungsfehler behoben |
eventType, embedId, formId, formName, currentPage, fieldName, fieldLabel, timestamp |
Diese Events erfassen spezifisches Nutzerverhalten zur Analyse der Nutzererfahrung.
Event |
Beschreibung |
Verfügbare Properties |
user:hint:opened |
Hinweis/Tooltip geöffnet |
eventType, embedId, formId, formName, currentPage, fieldName, fieldLabel, timestamp |
user:hint:closed |
Hinweis/Tooltip geschlossen |
eventType, embedId, formId, formName, currentPage, fieldName, fieldLabel, timestamp |
Mit Wildcards können Sie mehrere Events mit einem einzigen Handler abfangen:
Vollständiges Setup für Matomo-Tracking:
Vollständiges Setup für Google Analytics 4 Tracking:
Senden Sie Events an Ihre eigene API:
Während der Entwicklung können Sie alle Events zur Fehlersuche in der Konsole ausgeben:
