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 das FlowSDK (Software Development Kit). Es 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.
Das FlowSDK hängt sich genau dort ein. Es 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
Das FlowSDK ist Teil unseres Heyflow-Event-Systems und über die detail-Eigenschaft des Event-Objekts erreichbar. Wir verwenden eine einfache Versionierung des FlowSDKs, um sicherzustellen, dass sich bei zukünftigen Änderungen nichts kaputtgeht:
window.addEventListener(‘heyflow-init’, (event) => {
const flowSDK = event.detail.flowSDK.v1;
});
Du kannst das FlowSDK in jedem Heyflow-Event verwenden.
FlowSDK 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.
flowSDK.additionalResponseData.set(“my-value”, “hello”);
flowSDK.additionalResponseData.set(“my-advanced-value”, { value: 3 });
flowSDK.additionalResponseData.set(“my-more-advanced-value”, { value: false, label: “test” });
flowSDK.additionalResponseData.set(“my-value”, “hello-2”);
flowSDK.additionalResponseData.get(“my-value”); // “hello-2”
flowSDK.additionalResponseData.remove(“my-value”);
flowSDK.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.
flowSDK.getCurrentScreenID(); // “screen-f0453c16”
flowSDK.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:
lowSDK.getFlowRoot(); // document in a standalone flow for example
flowSDK.getFlowRoot(); // ShadowRoot if you embedded your flow via our embed widget, which uses the shadowDOM via custom web components
flowSDK.getFlowRoot(); // document in a standalone flow for example
requestNavigation
Du kannst dich auch programmgesteuert durch deinen Flow bewegen, indem du eine Navigation anforderst:
flowSDK.navigation.goNext(); // Navigates to the next screen
flowSDK.navigation.goBack(); // Navigates to the previous screen
flowSDK.navigation.goToScreen(“screen-31d412a”); // Navigates to the given 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.
flowSDK.validateScreenByID(“screen-1ab442a”).then(console.log); // { success: boolean }
flowSDK.validateScreenByName(“start”).then(console.log); // { success: boolean }
Block Funktionen
Blöcke abrufen
Um Blöcke abzurufen, kannst du verschiedene Funktionen aus dem FlowSDK nutzen.
Mehr dazu, wie du mit den Blöcken interagieren kannst, findest du im nächsten Abschnitt.
flowSDK.getBlocks(); // Just gives you all blocks of your flow
flowSDK.getBlockByID(“mc-4124122”); // Gives you the one block you are looking for
flowSDK.getBlocksByScreenID(“screen-f0453c16”); // Gives you all the blocks of the screen you are looking for
flowSDK.getBlocksByScreenName(“start”); // Gives you all the blocks of the screen you are looking for
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 = flowSDK.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 = flowSDK.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”]);