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.
<!-- Ihr Formular-Embed -->
<div data-fc-id="mein-formular"></div>
<!-- Ihr Tracking-Script (MUSS vor dem Wrapper-Script stehen, ohne defer!) -->
<script>
window.addEventListener('formcentric:loaded', () => {
console.log('Formcentric Event API ist bereit!')
// Event-Listener registrieren
window.formcentric.on('form:init:complete', event => {
console.log('Formular geladen:', event.formName)
})
})
</script>
<!-- Formcentric Wrapper-Script (kann defer verwenden) -->
<script defer src="https://form.formcentric.com/form/formcentric.js" defer></script>
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:
window.addEventListener('formcentric:loaded', () => {
// Alle Events einer Kategorie ausgeben
window.formcentric.on('validation:*', event => {
console.log('[Form Event]', event.eventType, event)
})
// Alle Events ausgeben (wird nicht in Produktivumgebungen empfohlen)
window.formcentric.on('*', event => {
console.log('[Form Event]', event.eventType, event)
})
})
Vollständiges Setup für Matomo-Tracking:
<!-- Matomo Tracking Code -->
<script>
var _paq = window._paq = window._paq || []
_paq.push(['trackPageView'])
_paq.push(['enableLinkTracking'])
;(function() {
var u = '//ihre-matomo-domain.com/'
_paq.push(['setTrackerUrl', u + 'matomo.php'])
_paq.push(['setSiteId', '1'])
var d = document, g = d.createElement('script'),
s = d.getElementsByTagName('script')[0]
g.async = true
g.src = u + 'matomo.js'
s.parentNode.insertBefore(g, s)
})()
</script>
<!-- Formcentric Event Tracking -->
<script>
window.addEventListener('formcentric:loaded', () => {
// Formular-Start
window.formcentric.on('form:init:complete', event => {
_paq.push(['trackEvent', 'Formular', 'Gestartet',
event.formName, event.pageCount])
})
// Navigation & Übermittlung
window.formcentric.on('page:change:start', event => {
const aktion = event.isSubmit ? 'Submit Gestartet' : 'Seitenwechsel'
_paq.push(['trackEvent', 'Formular', aktion,
`${event.fromPage} → ${event.toPage}`, event.toPage])
})
window.formcentric.on('page:change:success', event => {
if (event.isSubmit) {
_paq.push(['trackEvent', 'Formular', 'Übermittelt',
event.formName, event.submissionTime])
_paq.push(['trackGoal', 1]) // Ihre Goal-ID
}
})
// Validierungsfehler
window.formcentric.on('validation:error', event => {
_paq.push(['trackEvent', 'Formular', 'Validierungsfehler',
`${event.fieldLabel}: ${event.errorCode}`,
event.currentPage])
})
// Formular-Abbruch tracken
let formularGestartet = false
let formularUebermittelt = false
window.formcentric.on('form:init:complete', () => {
formularGestartet = true
})
window.formcentric.on('page:change:success', event => {
if (event.isSubmit) {
formularUebermittelt = true
}
})
window.addEventListener('beforeunload', () => {
if (formularGestartet && !formularUebermittelt) {
_paq.push(['trackEvent', 'Formular', 'Abgebrochen',
document.title])
}
})
})
</script>
Vollständiges Setup für Google Analytics 4 Tracking:
<!-- Google Analytics 4 -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"></script>
<script>
window.dataLayer = window.dataLayer || []
function gtag(){dataLayer.push(arguments)}
gtag('js', new Date())
gtag('config', 'G-XXXXXXXXXX')
</script>
<!-- Formcentric Event Tracking -->
<script>
window.addEventListener('formcentric:loaded', () => {
window.formcentric.on('form:init:complete', event => {
gtag('event', 'form_start', {
form_id: event.formId,
form_name: event.formName,
page_count: event.pageCount
})
})
window.formcentric.on('page:change:success', event => {
if (event.isSubmit) {
gtag('event', 'form_submit', {
form_id: event.formId,
submission_time_ms: event.submissionTime
})
// Als Conversion markieren
gtag('event', 'conversion', {
send_to: 'G-XXXXXXXXXX/ihre-conversion-id',
transaction_id: event.embedId
})
}
})
})
</script>
Senden Sie Events an Ihre eigene API:
window.addEventListener('formcentric:loaded', () => {
const ANALYTICS_ENDPOINT = 'https://ihre-api.com/events'
window.formcentric.on('*', async event => {
try {
await fetch(ANALYTICS_ENDPOINT, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
event_type: event.eventType,
form_id: event.formId,
timestamp: event.timestamp,
...event
})
})
} catch (error) {
console.error('Analytics-Fehler:', error)
}
})
})
Während der Entwicklung können Sie alle Events zur Fehlersuche in der Konsole ausgeben:
// Nur in Entwicklungsumgebung!
if (window.location.hostname === 'localhost') {
window.addEventListener('formcentric:loaded', () => {
window.formcentric.on('*', event => {
console.log('[Formcentric Event]', event.eventType, event)
})
})
}
