Angepasste Formularblöcke auf Landing-Pages erstellen

Formularblöcke auf Braze Landing-Pages erfassen Standardeingaben wie Textfelder, Checkboxen und Dropdowns. Angepasste Formularblöcke erweitern die Möglichkeiten, indem Sie eigene interaktive Elemente erstellen können – zum Beispiel eine Sternebewertung, eine Emoji-Stimmungsauswahl oder eine Rubbelkarte.

Wenn Besucher:innen das angepasste Formular absenden, wird der ausgewählte Wert validiert und zusammen mit Ihren Standardfeldern gespeichert und dann als angepasstes Attribut an Braze gesendet. So können Sie reichhaltigere, ansprechendere Eingaben erfassen, ohne den Landing-Page-Editor verlassen zu müssen.

Angepasste Formularblöcke erstellen Sie mit einem einzigen JavaScript-Helfer, window.brazeHelpers.forms.registerFormInput, den Sie aus einem Custom Code-Block auf der Landing-Page aufrufen.

Hinweis

Umfragen und In-App Messages haben eigene Formularblöcke, aber registerFormInput – die JavaScript-API zur Verbindung einer selbst programmierten UI mit einem Formularblock – ist nur auf Landing-Pages verfügbar.

Funktionsweise

Ein benutzerdefiniertes Formulareingabefeld ist ein beliebiges Element auf Ihrer Landing-Page, dessen Wert Sie erfassen und mit dem Formular übermitteln möchten. Sie verbinden dieses Element mit dem Braze-Formularsystem, indem Sie es registrieren. Die Registrierung teilt Braze mit, welches Element überwacht werden soll, wie der aktuelle Wert ausgelesen wird und was mit diesem Wert geschehen soll, wenn das Formular abgesendet wird.

1. Erstellen Sie Ihre benutzerdefinierte Benutzeroberfläche in einem Custom Code-Block auf der Landing-Page und weisen Sie ihm einen stabilen CSS-Selektor zu, beispielsweise eine id.
2. Registrieren Sie das Element, indem Sie window.brazeHelpers.forms.registerFormInput mit einem Konfigurationsobjekt aufrufen.
3. Braze ruft Ihre getValue-Funktion auf, um den aktuellen Wert auszulesen, wenn er benötigt wird.
4. Wenn das Feld erforderlich ist oder Sie eine onValidate-Funktion bereitstellen, blockiert Braze die Übermittlung, bis der Wert die Prüfung besteht, und kennzeichnet ein ungültiges Element mit einer CSS-Klasse, die Sie gestalten können. Siehe Validierung und Pflichtfelder.
5. Wenn das Formular abgesendet wird und die Validierung bestanden ist, ruft Braze Ihre onSubmit-Funktion auf, in der Sie das Braze SDK nutzen können, um Informationen wie ein angepasstes Attribut zu protokollieren.

Da Sie die Funktionen zum Auslesen, Validieren und Übermitteln des Werts selbst bereitstellen, funktioniert dieser Ansatz mit nahezu jedem benutzerdefinierten Formularelement – Sie sind also nicht auf die Standardfeldtypen im Editor beschränkt.

Grundlegendes Framework

Die einfachste Registrierung zielt auf ein Element ab, behandelt es als erforderlich, liest seinen Wert aus einem Datenattribut und schreibt diesen Wert beim Absenden des Formulars in ein angepasstes Attribut. Umschließen Sie den Aufruf mit einem DOMContentLoaded-Listener, wie in den Beispielen auf dieser Seite, damit das Element existiert, bevor registerFormInput ausgeführt wird:

1
2
3
4
5
6
7
8
9
10

document.addEventListener("DOMContentLoaded", () => {
  window.brazeHelpers.forms.registerFormInput({
    selector: "#my-custom-input",
    isRequired: true,
    getValue: (element) => element.dataset.value ?? null,
    onSubmit: (value) => {
      window.brazeBridge.getUser().setCustomUserAttribute("my_attribute", value);
    },
  });
});

Rufen Sie registerFormInput einmal für jede angepasste Eingabe auf der Seite auf. Standardmäßige Formularfelder, die über den Landing-Page-Editor platziert werden, müssen nicht registriert werden; die Registrierung ist nur für die angepassten Eingaben erforderlich, die Sie in einem Custom Code-Block erstellen.

Konfigurationsreferenz

registerFormInput akzeptiert ein einzelnes Konfigurationsobjekt. Als Funktionssignatur ausgedrückt sieht die vollständige Struktur so aus:

1
2
3
4
5
6
7
8
9

window.brazeHelpers.forms.registerFormInput({
  // Provide exactly one of `selector` or `element` to identify the input.
  selector?: string,
  element?: HTMLElement,
  isRequired?: boolean | Promise<boolean>,
  getValue: (element: HTMLElement) => value,
  onValidate?: (value, element: HTMLElement) => boolean | Promise<boolean>,
  onSubmit?: (value, element: HTMLElement) => void | Promise<void>,
});

Mindestens müssen Sie eine Möglichkeit angeben, das Element zu lokalisieren (selector oder element), sowie eine getValue-Funktion. Alles andere ist optional.

Auf den Wert in onSubmit reagieren

onSubmit ist ein einfacher JavaScript-Callback, sodass Sie mit dem erfassten Wert so verfahren können, wie es Ihre Integration erfordert. Da onSubmit als Teil der Formularübermittlung ausgeführt wird, funktionieren darin getätigte brazeBridge-Aufrufe wie erwartet – selbst für Besucher:innen, die die Landing-Page anonym geöffnet haben. Unter Bridge-Verfügbarkeit finden Sie weitere Situationen, in denen Bridge-Aufrufe funktionieren.

Das gängigste Muster ist das Schreiben des erfassten Werts in das Nutzerprofil mit der Braze JavaScript Bridge, die auf Landing-Pages verfügbar ist:

1

window.brazeBridge.getUser().setCustomUserAttribute("attribute_name", value);

Verwenden Sie einen Namen für ein angepasstes Attribut, der bereits in Ihrem Workspace existiert oder den Sie erstellen möchten. Der übergebene Wert wird im Profil der Nutzer:innen gespeichert und kann dann für Segmentierung, Personalisierung und das Triggern von Folgenachrichten verwendet werden.

Sie sind nicht auf angepasste Attribute beschränkt. Aus demselben Callback heraus können Sie jede brazeBridge.getUser()-Methode aufrufen. Zum Beispiel, um Nutzer:innen einer Abo-Gruppe hinzuzufügen, ein Standardattribut zu setzen, ein angepasstes Event zu protokollieren oder den Wert an Ihren eigenen API-Endpunkt zu senden.

Hinweis

Sie müssen requestImmediateDataFlush nicht innerhalb von onSubmit aufrufen. Der Formularübermittlungsprozess überträgt automatisch alle Daten an Braze, nachdem Ihr onSubmit-Callback abgeschlossen ist.

Beispiele

Die folgenden Beispiele sind vollständig und eigenständig. Jedes Beispiel ist ein einzelner Block, der Markup, ein <script>-Tag und ein <style>-Tag enthält, die Sie in einen einzelnen Custom Code (HTML)-Block auf Ihrer Landing-Page einfügen. Der registerFormInput-Aufruf am Ende jedes Skripts verbindet die benutzerdefinierte Eingabe mit dem Braze-Formular. Fahren Sie mit der Maus über ein Codebeispiel und wählen Sie das Kopiersymbol aus, um es zu kopieren.

Wichtig

Diese Beispiele laufen vollständig im Browser der Besucher:innen. Beim Rubbellos-Beispiel wird der „Gewinn“ durch JavaScript im Browser der Besucher:innen ausgewählt, sodass technisch versierte Besucher:innen den Code so verändern könnten, dass sie ein beliebiges Ergebnis erhalten. Verlassen Sie sich bei Prämien, Rabatten oder anderen Ergebnissen, die eine strikte Durchsetzung pro Besucher:in erfordern, nicht auf dieses Muster. Validieren Sie stattdessen alles, was sicherheits- oder umsatzrelevant ist, auf Ihren eigenen Servern.

• stimmungsauswahl
• rubbellos
• campaign-attribution

Ziel: Die Besucher:innen wählen ein fröhliches oder ein unglückliches Gesicht aus, und ihre Wahl wird in ein angepasstes String-Attribut mit dem Namen feedback_sentiment geschrieben.

Fügen Sie Folgendes in einen einzelnen Custom Code (HTML)-Block ein:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

<div id="sentiment-picker" class="sentiment-picker">
  <button type="button" data-sentiment="positive" aria-label="Happy">🙂</button>
  <button type="button" data-sentiment="negative" aria-label="Unhappy">🙁</button>
</div>

<script>
  document.addEventListener("DOMContentLoaded", () => {
    const picker = document.getElementById("sentiment-picker");

    picker.querySelectorAll("button").forEach((button) => {
      button.addEventListener("click", () => {
        picker.dataset.sentiment = button.dataset.sentiment;
        picker.querySelectorAll("button").forEach((b) => b.classList.remove("selected"));
        button.classList.add("selected");
      });
    });

    window.brazeHelpers.forms.registerFormInput({
      selector: "#sentiment-picker",
      isRequired: true,
      getValue: (element) => element.dataset.sentiment ?? null,
      onSubmit: (value) => {
        window.brazeBridge.getUser().setCustomUserAttribute("feedback_sentiment", value);
      },
    });
  });
</script>

<style>
  .sentiment-picker {
    display: flex;
    gap: 16px;
    justify-content: center;
    font-size: 40px;
  }

  .sentiment-picker button {
    background: none;
    border: 2px solid transparent;
    border-radius: 12px;
    cursor: pointer;
    line-height: 1;
    padding: 8px;
  }

  .sentiment-picker button.selected {
    border-color: #1f2933;
  }

  /* Braze adds this class to the registered element when validation fails. */
  .sentiment-picker.bz-validation-error {
    outline: 3px solid #f94144;
    outline-offset: 4px;
    border-radius: 12px;
  }
</style>

So funktioniert es: Wenn ein Button ausgewählt wird, wird dessen data-sentiment-Wert im Container-Element gespeichert. getValue liest diesen Wert aus dem Container-Element zurück, das Braze übergibt. Da isRequired auf true gesetzt ist, wird das Formular erst abgesendet, wenn die Besucher:innen ein Gesicht ausgewählt haben, und der Container erhält die Klasse bz-validation-error, solange er leer ist. Beim Absenden wird der gewählte Wert ("positive" oder "negative") in feedback_sentiment geschrieben.

Ziel: Die Besucher:innen rubbeln eine Karte frei, um einen von drei Rabatten (10 % Rabatt, 20 % Rabatt oder 25 % Rabatt) zu enthüllen, und der Rabatt wird in ein angepasstes String-Attribut mit dem Namen scratch_off_reward geschrieben.

Dieses Beispiel zeichnet eine Rubbelkarte auf einem HTML-Canvas. Beim Laden der Seite wird zufällig ein Gewinn ausgewählt und unter einer undurchsichtigen Schicht verborgen, die die Besucher:innen wegkratzen. Sie können den Canvas-Ansatz durch ein beliebiges Rubbel-Widget Ihrer Wahl ersetzen; nur der registerFormInput-Aufruf verbindet es mit Braze. Fügen Sie Folgendes in einen einzelnen Custom Code (HTML)-Block ein:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90

<div id="scratch-card" class="scratch-card" data-reward="">
  <span class="scratch-card__reward"></span>
  <canvas class="scratch-card__surface" width="300" height="150"></canvas>
</div>

<script>
  document.addEventListener("DOMContentLoaded", () => {
    const rewards = ["10% Off", "20% Off", "25% Off"];

    const card = document.getElementById("scratch-card");
    const label = card.querySelector(".scratch-card__reward");
    const canvas = card.querySelector(".scratch-card__surface");
    const ctx = canvas.getContext("2d");

    // Randomly assign which reward this visitor will reveal.
    const reward = rewards[Math.floor(Math.random() * rewards.length)];
    label.textContent = reward;

    // Paint the opaque scratch layer over the reward.
    ctx.fillStyle = "#b3b3b3";
    ctx.fillRect(0, 0, canvas.width, canvas.height);
    ctx.globalCompositeOperation = "destination-out";

    let isScratching = false;

    function scratchAt(event) {
      const rect = canvas.getBoundingClientRect();
      ctx.beginPath();
      ctx.arc(event.clientX - rect.left, event.clientY - rect.top, 18, 0, Math.PI * 2);
      ctx.fill();
    }

    canvas.addEventListener("pointerdown", () => { isScratching = true; });
    canvas.addEventListener("pointermove", (event) => {
      if (isScratching) scratchAt(event);
    });
    canvas.addEventListener("pointerup", () => {
      isScratching = false;
      // The visitor has scratched the card, so record the revealed reward.
      card.dataset.reward = reward;
    });

    window.brazeHelpers.forms.registerFormInput({
      selector: "#scratch-card",
      isRequired: true,
      getValue: (element) => element.dataset.reward || null,
      onValidate: (value) => rewards.includes(value),
      onSubmit: (value) => {
        window.brazeBridge.getUser().setCustomUserAttribute("scratch_off_reward", value);
      },
    });
  });
</script>

<style>
  .scratch-card {
    position: relative;
    width: 300px;
    height: 150px;
    margin: 0 auto;
    font-family: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
  }

  /* The reward sits underneath and is revealed as the canvas is scratched away. */
  .scratch-card__reward {
    position: absolute;
    inset: 0;
    display: flex;
    align-items: center;
    justify-content: center;
    font-size: 32px;
    font-weight: 700;
    color: #1f2933;
  }

  .scratch-card__surface {
    position: absolute;
    inset: 0;
    border-radius: 12px;
    cursor: pointer;
    touch-action: none;
  }

  /* Braze adds this class to the registered element when validation fails. */
  .scratch-card.bz-validation-error {
    outline: 3px solid #f94144;
    outline-offset: 4px;
    border-radius: 12px;
  }
</style>

So funktioniert es: Beim Laden der Seite wählt das Skript zufällig einen der drei Gewinne aus und malt eine undurchsichtige Schicht darüber auf dem Canvas. Wenn die Besucher:innen über den Canvas ziehen, löscht der Kompositmodus "destination-out" diese Schicht und enthüllt den darunter liegenden Gewinn. Beim pointerup wird der enthüllte Gewinn in das data-reward-Attribut der Karte geschrieben. getValue liest ihn von dort zurück, onValidate bestätigt, dass es sich um einen der drei definierten Gewinne handelt, und isRequired verhindert das Absenden, bis die Karte freigerubbelt wurde. Beim Absenden wird der enthüllte Rabatt (z. B. "20% Off") in scratch_off_reward geschrieben.

Ziel: Die Campaign erfassen, die die Besucher:innen auf die Landing-Page geleitet hat, und sie als angepasste Event-Eigenschaft für nachgelagerte Berichte und Attribution protokollieren.

Dieses Beispiel zeigt, wie Sie eine Landing-Page-Formularübermittlung einer bestimmten Campaign zuordnen. Indem Sie eine Liquid-Variable wie {{campaign.${api_id}}} zu Ihrer Landing-Page-URL in E-Mail-, SMS- oder WhatsApp-Nachrichten hinzufügen, können Sie den Campaign-Bezeichner an die Landing-Page übergeben. Der benutzerdefinierte Formularblock liest dann diesen Parameter aus der URL und protokolliert ihn als angepasstes Event mit der Campaign-API-ID als Event-Eigenschaft, wodurch sich leichter nachverfolgen lässt, welche Campaigns Formularübermittlungen auslösen.

Fügen Sie Folgendes in einen einzelnen Custom Code (HTML)-Block ein:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

<input type="hidden" id="campaign-attribution" value="" />

<script>
  document.addEventListener("DOMContentLoaded", () => {
    const hiddenInput = document.getElementById("campaign-attribution");
    const campaignApiId = new URLSearchParams(window.location.search).get("campaign_api_id");

    if (campaignApiId) {
      hiddenInput.value = campaignApiId;
    }

    window.brazeHelpers.forms.registerFormInput({
      selector: "#campaign-attribution",
      isRequired: false,
      getValue: (element) => element.value || null,
      onSubmit: async (value) => {
        if (!value) {
          return;
        }

        await window.brazeBridge.logCustomEvent("landing_page_form_submitted", {
          campaign_api_id: value,
        });
      },
    });
  });
</script>

So funktioniert es: Wenn Sie eine E-Mail-, SMS- oder WhatsApp-Nachricht erstellen, die auf Ihre Landing-Page verlinkt, hängen Sie den Campaign-Bezeichner mithilfe von Liquid-Templating an die URL an: https://your-landing-page.com?campaign_api_id={{campaign.${api_id}}}. Wenn Besucher:innen über diese Nachricht auf der Landing-Page ankommen, liest das Skript den campaign_api_id-Parameter aus der URL und speichert ihn in einem versteckten Eingabefeld. Beim Absenden des Formulars protokolliert der onSubmit-Callback, sofern eine Campaign-ID vorhanden ist, ein angepasstes Event namens landing_page_form_submitted mit der Campaign-API-ID als Event-Eigenschaft. Dieses Event erscheint in Currents und kann für Berichte, Segmentierung und Attributionsanalysen verwendet werden.

Tipp

Sie können dieses Muster erweitern, um zusätzliche URL-Parameter wie Nachrichtenvariante, Canvas-Schritt oder andere Liquid-Variablen zu erfassen, die Sie zu Attributionszwecken an die Landing-Page übergeben möchten.

Validierung und Pflichtfelder

Eine Eingabe muss alle auf sie zutreffenden der folgenden Prüfebenen bestehen, bevor das Formular gesendet werden kann:

1. isRequired blockiert das Absenden, wenn kein nicht-leerer Wert vorhanden ist. Geben Sie null von getValue zurück, wenn die Eingabe noch keinen Wert hat, damit Braze erkennen kann, dass sie leer ist. Leere Strings (einschließlich Strings, die nur aus Leerzeichen bestehen) und leere Arrays werden ebenfalls als leer behandelt, während 0 und false als vorhandene Werte gelten. isRequired kann ein boolescher Wert oder ein Promise sein, das zu einem solchen aufgelöst wird, und wird jedes Mal neu ausgewertet, wenn die Eingabe validiert wird.
2. Native Constraint-Validierung. Wenn das zugeordnete Element die Standard-HTML-API checkValidity() unterstützt, beispielsweise ein natives <input> mit required, pattern, min oder max, führt Braze diese aus und blockiert das Absenden, wenn sie fehlschlägt. Bei vollständig angepassten, nicht-nativen Elementen (einem div, einem canvas usw.) besteht diese Prüfung immer, sodass sie nie mit Ihrer eigenen Logik kollidiert.
3. onValidate blockiert das Absenden basierend auf Ihren eigenen Regeln. Die Funktion erhält den aktuellen Wert und das zugeordnete Element und muss boolean \| Promise<boolean> zurückgeben – denselben Rückgabetyp wie isRequired – wobei true bedeutet, dass der Wert gültig ist, und false, dass er es nicht ist. Verwenden Sie sie für Prüfungen zulässiger Werte, Formatprüfungen, Bereiche oder jede Logik, die Sie in JavaScript ausdrücken können.

Fehlerstile

Wenn eine Eingabe die Validierung nicht besteht, fügt Braze die CSS-Klasse bz-validation-error zum Element hinzu, das durch Ihren selector oder Ihr element zugeordnet ist, und entfernt die Klasse, wenn die Eingabe wieder gültig wird. Gestalten Sie den ungültigen Zustand nach Belieben, beispielsweise mit einer Umrandung oder einem Rahmen, der die Aufmerksamkeit auf die betroffene Eingabe lenkt, indem Sie eine Regel hinzufügen, die Ihr Element in Kombination mit der Klasse bz-validation-error anspricht:

1
2
3
4

#my-custom-input.bz-validation-error {
  outline: 3px solid #f94144;
  outline-offset: 4px;
}

Das Styling des Fehlerzustands ist optional, wird aber empfohlen, damit Besucher:innen sehen können, welche angepasste Eingabe das Absenden blockiert. Jedes Beispiel auf dieser Seite enthält eine bz-validation-error-Regel.

Best Practices

• Verwenden Sie einen stabilen, eindeutigen SELEKTOR. Eine id ist die sicherste Wahl. Vermeiden Sie Selektoren, die auf mehr als ein Element zutreffen könnten.
• Geben Sie null zurück, nicht einen leeren String oder undefined, wenn kein Wert vorhanden ist, damit Pflichtfeldprüfungen vorhersehbar funktionieren. Leere Strings und leere Arrays werden ebenfalls als leer behandelt, aber null ist das klarste Signal für „kein Wert“.
• Halten Sie getValue günstig und synchron. Braze kann die Funktion mehrfach aufrufen, daher sollte sie den aktuellen Wert lesen und zurückgeben, anstatt aufwändige Operationen auszuführen.
• Gestalten Sie den bz-validation-error-Zustand so, dass Besucher:innen erkennen können, welches angepasste Eingabefeld die Übermittlung blockiert.
• Legen Sie die Namen Ihrer angepassten Attribute im Voraus fest und halten Sie sie konsistent, damit Sie die Daten später zuverlässig segmentieren können.
• Testen Sie die vollständige Übermittlung. Bestätigen Sie, dass das Attribut nach dem Absenden im Kundenprofil erscheint und dass Pflichtfeld- und Validierungsregeln die Übermittlung wie erwartet blockieren.

Fehlerbehebung

Das Formular wird abgesendet, obwohl nichts ausgewählt wurde

Stellen Sie sicher, dass isRequired auf true gesetzt ist. Braze behandelt null, undefined, leere Strings (einschließlich Strings, die nur aus Leerzeichen bestehen) und leere Arrays als fehlenden Wert. Wenn getValue etwas anderes zurückgibt (zum Beispiel einen nicht leeren Standard- oder Platzhalterwert), obwohl nichts ausgewählt wurde, greift die Pflichtfeldprüfung nicht.

Der Wert erscheint nicht im Profil

Vergewissern Sie sich, dass onSubmit die Methode window.brazeBridge.getUser().setCustomUserAttribute mit dem korrekten Attributnamen aufruft und dass der Custom Code-Block sich auf derselben Landing-Page wie das Formular befindet.

Die Registrierung scheint nichts zu bewirken

Prüfen Sie, ob der Selektor ein Element im DOM anspricht, das zum Zeitpunkt der Ausführung von registerFormInput existiert, und ob das Skript erst nach dem Rendern dieses Elements ausgeführt wird. Öffnen Sie dann die Entwicklungskonsole Ihres Browsers: registerFormInput validiert die Konfiguration und ignoriert die Registrierung, wenn etwas nicht stimmt (zum Beispiel ein fehlendes getValue, ein Selektor, der kein gültiger CSS-Selektor ist, oder eine Eigenschaft vom falschen Typ). In diesem Fall wird eine Warnung mit dem Präfix [brazeHelpers.forms.registerFormInput] protokolliert, die beschreibt, was ungültig war.

Verwandte Inhalte

• JavaScript-Bridge für Landing-PagesVollständige brazeBridge-Referenz für onSubmit.
• Landing-Pages erstellen