Eigener JavaScript-Code in einem Flow kann manchmal ganz schön knifflig sein – vor allem, weil du die Struktur des Flows nicht komplett selbst in der Hand hast. Sie wird von Heyflow aufgebaut und kann sich mit der Zeit ändern.
Damit das Ganze stabiler und einfacher wird, gibt es die Flow API. Diese gibt dir kontrollierten Zugriff auf verschiedene Mechanismen und Daten deines Flows – und zwar zur Laufzeit.
Wenn jemand einen Flow öffnet, passiert im Hintergrund eine ganze Menge: Blöcke werden initialisiert und gerendert, Events registriert und ausgelöst, externe Integrationen gestartet – und noch einiges mehr.
Die Flow API hängt sich genau dort ein. Sie stellt dir Funktionen zur Verfügung, mit denen du Daten lesen, verändern oder ausführen kannst – und zwar so, wie das System es erwartet. Ganz ohne wilde Hacks oder Workarounds.
🔎 Lerne mehr über individuelles JavaScript hier.
Heyflow Events
Die Flow API ist Teil unseres Heyflow-Event-Systems und über die detail-Eigenschaft des Event-Objekts erreichbar. Wir verwenden eine einfache Versionierung der Flow API, um sicherzustellen, dass sich bei zukünftigen Änderungen nichts kaputtgeht:
window.addEventListener(‘heyflow-init’, (event) => {
const flowAPI = event.detail.flowAPI.v1;
});
Du kannst die Flow API in jedem Heyflow-Event verwenden.
Flow API Funktionen
additionalResponseData
Mit diesem Objekt kannst du zusätzliche Antwortdaten hinzufügen, bearbeiten oder entfernen, die beim Absenden des Flows mitgeschickt werden. Ein typischer Anwendungsfall: Du möchtest versteckte Felder ergänzen – zum Beispiel UTM-Parameter oder andere Tracking-Infos.
flowAPI.additionalResponseData.set(“my-value”, “hello”);
flowAPI.additionalResponseData.set(“my-advanced-value”, { value: 3 });
flowAPI.additionalResponseData.set(“my-more-advanced-value”, { value: false, label: “test” });
flowAPI.additionalResponseData.set(“my-value”, “hello-2”);
flowAPI.additionalResponseData.get(“my-value”); // “hello-2”
flowAPI.additionalResponseData.remove(“my-value”);
flowAPI.additionalResponseData.getAll(); // { “my-advanced-value”: { value: 3}, “my-more-advanced-value”: { value: false, label: “test” } }
getCurrentScreenID und getCurrentScreenName
Mit diesen Funktionen kannst du herausfinden, welchen Screen der Nutzer oder die Nutzerin gerade sieht.
flowAPI.getCurrentScreenID(); // “screen-f0453c16”
flowAPI.getCurrentScreenName(); // “start”
getFlowRoot
Je nachdem, wie du deinen Flow eingebunden hast, kann es manchmal schwierig sein, das Root-Element (also den Ursprung) des Flows zu finden. Dieses wird aber oft gebraucht, z.B. um Event Listener hinzuzufügen oder gezielt im DOM zu suchen.
Diese Funktion hilft dir genau dabei:
flowAPI.getFlowRoot(); // Dokument in einem eigenständigen Flow zum Beispiel
flowAPI.getFlowRoot(); // ShadowRoot, wenn Sie Ihren Flow über unser Einbettungs-Widget eingebettet haben, das die shadowDOM über benutzerdefinierte Webkomponenten verwendet
requestNavigation
Du kannst dich auch programmgesteuert durch deinen Flow bewegen, indem du eine Navigation anforderst:
flowAPI.navigation.goNext(); // Navigiert zum nächsten Screen
flowAPI.navigation.goBack(); // Navigates to the previous screen
flowAPI.navigation.goToScreen(“screen-31d412a”); // Navigiert zu dem angegebenen ScreenID
❗ Wichtig: Beim Vorwärtsnavigieren wird der aktuelle Screen überprüft (validiert). Ist der Screen ungültig, wird das Weitergehen verhindert. Deshalb kannst du eine Navigation nur anfragen, aber nicht direkt erzwingen.
validateScreen
Du kannst einen Screen validieren, indem du diese Funktion aufrufst. Die Validierung läuft asynchron ab – das solltest du im Hinterkopf behalten. Als Ergebnis bekommst du einen Boolean-Wert, der dir zeigt, ob der Screen gültig ist oder nicht.
flowAPI.validateScreenByID(“screen-1ab442a”).then(console.log); // { success: boolean }
flowAPI.validateScreenByName(“start”).then(console.log); // { success: boolean }
Block Funktionen
Blöcke abrufen
Um Blöcke abzurufen, kannst du verschiedene Funktionen aus der Flow API nutzen.
Mehr dazu, wie du mit den Blöcken interagieren kannst, findest du im nächsten Abschnitt.
flowAPI.getBlocks(); // Gibt dir einfach alle Blöcke deines Flows.
flowAPI.getBlockByID(“mc-4124122”); // Gibt Ihnen nur den Block, nach dem Sie suchen
flowAPI.getBlocksByScreenID(“screen-f0453c16”); // Gibt Ihnen alle Blöcke des gesuchten Bildschirms
flowAPI.getBlocksByScreenName(“start”); //Gibt Ihnen alle Blöcke des gesuchten Bildschirms
getValue and setValue
Fast alle unsere Blöcke, die Nutzerdaten enthalten, unterstützen diese Funktionen, mit denen du den aktuellen Zustand eines Blocks einfach ändern kannst.
Blöcke, die in Version 1 diese Funktionen noch nicht unterstützen, sind:
Adressen-Block inkl. Google Maps
Calendly
Unterschrift
Stripe Checkout
Hochladen
Der Telefonnummer-Block unterstützt in Version 1 nur das Setzen einer Telefonnummer, nicht aber das Ändern des Landes.
const block = flowAPI.getBlockByID(“input-4124122”); // A input block
const value = block.getValue(); // “hello”
block.setValue(`${value} my-name`);
block.getValue(); // “hello my-name”
Manchmal verwendet ein Block für seine Werte kein einfaches String-Format, sondern andere Formate. Hier eine Übersicht:
Checkbox:
boolean(wahr oder falsch)Multiple Choice:
string[](eine Liste von optionIDs, weil dieser Block mehrere Optionen haben kann)Select:
string|null(die optionID der ausgewählten Option oder null, wenn nichts ausgewählt ist)
validate
Mit dieser Funktion kannst du die Validierung eines Blocks starten. Stell dir vor, du erwartest, dass der Nutzer Daten über dein eigenes JavaScript eingibt, und möchtest danach prüfen, ob der Flow oder Screen noch gültig ist.
block.validate().then(console.log); // { success: boolean }
❗ Wichtig: Je nach Block kann die Validierung auch Module nutzen – zum Beispiel eine Netzwerk-Validierung beim Telefon-Block. Deshalb läuft diese Methode tatsächlich asynchron ab.
reset
Diese Funktion setzt den Block in den Anfangszustand zurück – also so, als würdest du ein Formular leeren:
block.reset();
Sichtbarkeitsverwaltung
Steuere die Sichtbarkeit eines Blocks:
show() - Zeigt den Block an
hide() - Versteckt den Block
get() - Gibt den Sichtbarkeitsstatus zurück:
true(angezeigt)false(versteckt)undefined(Standardzustand)
clear() - Setzt den Sichtbarkeitsstatus zurück auf den Standard
const block = flowAPI.getBlockByID('input-4124122');
block.visibility.show();
block.visibility.hide();
const state = block.visibility.get(); // true | false | undefined
block.visibility.clear();
Individuelle Methoden
Für einige Blöcke haben wir spezielle Methoden bereitgestellt, die dir nützlich sein könnten.
Checkbox
Du kannst die Beschriftung der Checkbox programmatisch anpassen. Wichtig: Du kannst hier auch HTML verwenden.
block.setLabel(“<p>My own label</p>”);
Auswahl
Du kannst die Optionen eines Auswahl-Blocks programmatisch auslesen und ändern.
const options = block.getOptions();
// [
// {
// id: “option-124191”,
// label: “My label”,
// systemLabel: “my-option”
// }
// ]
block.setOptions([...options, {
id: “option-124191”,
label: “My label”
});
Eingabefeld
Du kannst die Auto-Complete-Optionen eines Eingabefeld-Blocks programmatisch auslesen und ändern.
const autoCompleteOptions = block.getAutoCompleteOptions(); // [ “option1” ]
block.setAutoCompleteOptions([“option2”]);