Zum Hauptinhalt springen

Flow API

Vor über einer Woche aktualisiert

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

blockID, blockType und variableName

Wir stellen drei Eigenschaften bereit, mit denen du die Block-Verarbeitung einfacher oder effizienter gestalten kannst, wenn du sie brauchst.

const block = flowAPI.getBlockByID(“input-4124122”); // A input block
block.blockID; // The unique identifier of the block you can use for methods like getBlockByID etc.
block.blockType; // The type of the block (button, input etc.)
block.variableName; // (optional) the variable you assigned to your block in the builder

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.

Eingabefeld

setAutocompleteOptionsFn

Du kannst eine eigene Fetch-Funktion verwenden, um dynamische Autocomplete-Optionen zu laden.

block.setAutocompleteOptionsFn(async (text) => {
 const lowercasedText = text.toLowerCase();

const url = `https://restcountries.com/v3.1/name/${lowercasedText}`;
 try {
  const response = await fetch(url);
  if (!response.ok) {
   throw new Error(`Response status: ${response.status}`);
 }
 const json = await response.json();
 return json.map(country => {
  return {label: country.name.common}
 })
 } catch (error) {
  console.error(error.message);
 }
 });

setCustomValidationFn

Du kannst eine (optional asynchrone) eigene Validierungsfunktion hinterlegen, die zusätzlich zur Standard-Validierung ausgeführt wird.

block.setCustomValidationFn(async (code) => {
  if (!code || code.length < 4) return false;
  try {
    const response = await fetch(`/api/promo-codes/${code}/validate`, {
      method: 'GET',
      headers: { Authorization: `Bearer TOKEN` },
    });
    if (!response.ok) return false;
    const promoCode = await response.json();
    return promoCode.isActive;
  } catch (error) {
    return false;
  }
});

Mehrfachauswahl

Wir ermöglichen es, die Optionen at runtime auszulesen und zu verändern.

getOptions()

Gibt die aktuelle Optionen-Konfiguration zurück.

const currentOptions = block.getOptions(); 
// [ 
// { 
// id: "option1", 
// label: "First Option" 
// isSelected: true, 
// ... 
// }, 
// { 
// id: "option2", 
// label: "Second Option" 
// isSelected: false, 
// ... 
// } 
// ]

setOptions(options)

Ersetzt die Optionen des Blocks durch einen neuen Satz von Optionen. Diese Methode:

  • behält Nutzerauswahlen bei, sofern die Option weiterhin existiert (identifiziert über id und label)

  • setzt Auswahlen zurück, wenn sich das label geändert hat

  • entfernt Auswahlen für Optionen, die nicht mehr existieren

Parameters:

  • options - Ein Array von Options-Konfigurationsobjekten

block.setOptions([ 
{ id: "option1", 
label: "First Option", 
}, 
{ 
id: "option2", 
label: "Second Option", 
svg: "<svg>...</svg>", 
}, 
]);

Options-Eigenschaften

Jedes Options-Objekt kann die folgenden Eigenschaften enthalten:

Eigenschaft

Typ

Beschreibung

id

string

Pflichtfeld. Eindeutige Kennung der Option

label

string

Pflichtfeld. Der angezeigte Text der Option

systemLabel

string

Wird in der Antwort angezeigt (sonst wird label verwendet)

svg

string

SVG-Markup für ein Icon (mit currentColor für stroke/fill)

image

string

URL zu einem Bild

emoji

string

Emoji, das angezeigt wird

hasInput

boolean

Ob die Option ein Textfeld enthält

eventName

string

Custom Event Name für Tracking

Beispiel

document.addEventListener("heyflow-init", (event) => {
  const block = event.detail.flowAPI.v1.getBlockByID("id-6be446a9");  
  
  // Get current options  
  const currentOptions = block.getOptions();  
  
  // Add custom options while keeping the current ones  
  block.setOptions([
    ...currentOptions,    
    {
      id: "custom1",      
      label: "Custom option",      
      svg: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M23.25,7.311,12.53,18.03a.749.749,0,0,1-1.06,0L.75,7.311" style="fill: none; stroke: currentColor; stroke-linecap: round; stroke-linejoin: round; stroke-width: 1.5px; fill-rule: evenodd;"></path></svg>',    
		},
		{
      id: "custom2",
      label: "Custom option with an image",
      image: "https://heyflow.com/example.png",
    },  
	]);
});

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”
});

Schieberegler

Wir ermöglichen es, den Wertebereich und die Schrittweite während der Laufzeit anzupassen.

setRange()

Setzt die Mindest- und/oder Höchstwerte des Schieberegels. Es ist möglich, nur einen der beiden Werte zu ändern; der andere fällt dann auf die ursprüngliche Konfiguration zurück. Wenn der aktuelle Wert des Schiebereglers unterhalb bzw. oberhalb des neuen Bereichs liegt, wird er entsprechend auf den Mindest- oder Höchstwert angepasst.

block.setRange({ min: 0, max: 100 }); 
block.setRange({ min: 0 }); 
block.setRange({ max: 100 });

setStep()

Legt die Schrittweite des Schiebereglers fest. Diese bestimmt, in welchen Inkrementen er sich innerhalb des Bereichs bewegt. Muss eine Zahl sein.

block.setStep(5);
Verwandte Artikel
Heyflow Events API
DataLayer Events und Payloads
Größenlimitierungen von Flows
Intro: Flow Navigation
Webhook-Anpassungen (Fortgeschritten)
Hat dies deine Frage beantwortet?