# IFrame Einbindung

GATEWatch-Formulare in Ihre Website einbetten: Voraussetzungen, Formulartypen, Codebeispiele, Einstellungen und Hilfe bei typischen Problemen.

# Voraussetzungen

## Worum es geht

Sie können ein GATEWatch-Formular direkt in Ihre bestehende Website einbetten. Besucher öffnen Ihre Website und bearbeiten das Formular dort. GATEWatch stellt das Formular innerhalb eines **IFrames** bereit – eines eingebetteten Fensters in Ihrer Seite.

Die Einbindung besteht aus zwei Teilen: einem Platzhalter an der gewünschten Stelle der Website und einem Skript, das dort das passende Formular lädt. Sie müssen den IFrame nicht selbst anlegen.

## Was Sie vorab benötigen

Stimmen Sie die Einbindung mit Ihrer Event-Administration und der Person ab, die Ihre Website betreut.

<table id="bkmrk-voraussetzung-was-is"><thead><tr><th>Voraussetzung</th><th>Was ist zu klären?</th></tr></thead><tbody><tr><td>**Zielseite auf Ihrer Website**</td><td>Auf welcher vollständigen URL soll das Formular erscheinen, beispielsweise `https://www.example.com/anmeldung`? Teilen Sie diese Adresse Ihrer Event-Administration mit.</td></tr><tr><td>**Zugriff auf den HTML-Code**</td><td>Die Website muss ein HTML-Element und ein externes Skript zulassen. In einem Redaktionssystem benötigen Sie dafür meist einen HTML- oder Codeblock. Ein gewöhnliches Textfeld genügt nicht.</td></tr><tr><td>**Skript-URL**</td><td>Von welcher GATEWatch-Installation wird das Einbindungsskript geladen? Häufig lautet die Adresse `https://gwatch.events/iframe.js`. Verwenden Sie die von Ihrer Event-Administration genannte URL.</td></tr><tr><td>**Event-Key**</td><td>Welche Veranstaltung soll geladen werden? Übernehmen Sie den bereitgestellten Event-Key exakt.</td></tr><tr><td>**Formulartyp**</td><td>Welches Formular soll beim direkten Aufruf der Zielseite zunächst erscheinen? Wählen Sie einen der unten aufgeführten Werte.</td></tr><tr><td>**Eingerichtetes Formular**</td><td>Das gewünschte Formular muss in der betreffenden Veranstaltung eingerichtet und für den vorgesehenen Ablauf nutzbar sein.</td></tr></tbody></table>

**Skript-URL und Event-Key gehören zusammen:** Das Skript lädt die Formulare von derselben GATEWatch-Adresse, von der es selbst stammt. Verwenden Sie daher die Angaben für dieselbe Installation und Veranstaltung.

## Den passenden Formulartyp wählen

Der Wert wird später im Code unter **`data-url-partial`** eingetragen. Schreiben Sie ihn genau wie in der Tabelle, einschließlich der Kleinschreibung.

<table id="bkmrk-wert-verwendung-regi"><thead><tr><th>Wert</th><th>Verwendung</th></tr></thead><tbody><tr><td>`registration`</td><td>**Online-Registrierung:** Besucher melden sich für die Veranstaltung an.</td></tr><tr><td>`tbc`</td><td>**Teilnahmebestätigung eingeladener Gäste:** Gäste bestätigen ihre Teilnahme. Persönliche Einladungslinks können die Zugangsinformationen bereits enthalten.</td></tr><tr><td>`onl`</td><td>**Login zum Teilnahmeformular:** Gäste, die sich zuvor online registriert haben und ihre Angaben ändern möchten, melden sich hier mit den erhaltenen Zugangsdaten an.</td></tr><tr><td>`fbk`</td><td>**Feedback:** Gäste gelangen zum Login für das Feedback-Formular.</td></tr><tr><td>`sso`</td><td>**Single Sign-on:** Einstieg in den dafür eingerichteten SSO-Ablauf, beispielsweise für eine Videoübertragung.</td></tr></tbody></table>

Der eingetragene Formulartyp ist die Vorgabe für einen direkten Seitenaufruf. Ein von GATEWatch erzeugter Link kann über seine URL-Parameter einen anderen Formularaufruf vorgeben. Lassen Sie diese Parameter beim Einbinden und Weiterleiten der Links erhalten.

## Einladungslinks auf Ihre Website führen

Das Einbetten allein ändert noch nicht die Links, die GATEWatch erzeugt. Wenn auch Links aus Einladungen oder anderen Platzhaltern auf Ihre Website führen sollen, hinterlegt die Event-Administration in den allgemeinen Veranstaltungseinstellungen die **Alternative URL für Formulare**.

Teilen Sie Ihrer Event-Administration die vollständige Adresse der Seite mit, auf der das Formular eingebettet ist, zum Beispiel:

```text
https://www.example.com/anmeldung

```

Die Event-Administration trägt diese Adresse in GATEWatch ein und übernimmt spätere Änderungen. Als verantwortliche Person für die Website müssen Sie diese Veranstaltungseinstellung nicht selbst bearbeiten. Die Adresse darf **keine URL-Parameter** enthalten, also keinen Zusatz wie `?formular=anmeldung`. GATEWatch ergänzt die für den jeweiligen Aufruf erforderlichen Parameter selbst.

Ab diesem Zeitpunkt verwenden die entsprechend erzeugten Formularlinks diese Zieladresse. Bereits verschickte Nachrichten ändern sich dadurch nicht. Prüfen Sie vor dem Versand einen neu erzeugten Link aus dem tatsächlich vorgesehenen Ablauf.

## Vor dem Einbau bereitlegen

- Die genaue Zieladresse Ihrer Website.
- Die von der Event-Administration bestätigte Skript-URL.
- Den Event-Key und den gewünschten Formulartyp.
- Eine Möglichkeit, HTML und Skripte auf der Zielseite einzufügen.
- Einen passenden Formular- beziehungsweise Einladungslink für die abschließende Funktionskontrolle.

**Weiter:** [Das Formular einbinden und prüfen](https://doc.gwatch.events/books/iframe-einbindung/page/die-einbindung).

# Die Einbindung

## Das Formular in die Website einsetzen

Fügen Sie den folgenden Code an der Stelle Ihrer Website ein, an der das Formular erscheinen soll. Verwenden Sie dafür den HTML-Bereich beziehungsweise einen geeigneten Codeblock Ihres Redaktionssystems.

```html
<div id="gwatch-iframe"></div>
<script
    src="[SCRIPT-URL]"
    data-event-key="[EVENT-KEY]"
    data-url-partial="[FORMULAR-TYP]">
</script>

```

Ersetzen Sie die drei Angaben in eckigen Klammern vollständig durch die Werte Ihrer Event-Administration. Die Anführungszeichen bleiben erhalten.

<table id="bkmrk-angabe-was-geh%C3%B6rt-hi"><thead><tr><th>Angabe</th><th>Was gehört hinein?</th></tr></thead><tbody><tr><td>`src`</td><td>Die Skript-URL, beispielsweise `https://gwatch.events/iframe.js`.</td></tr><tr><td>`data-event-key`</td><td>Der Event-Key der Veranstaltung.</td></tr><tr><td>`data-url-partial`</td><td>Einer der Werte `registration`, `tbc`, `onl`, `fbk` oder `sso`.</td></tr></tbody></table>

**Die Reihenfolge ist wichtig:** Das `<div>` muss bereits vorhanden sein, wenn das Skript ausgeführt wird. Platzieren Sie es deshalb wie im Beispiel **vor dem `<script>`**.

Das Skript erzeugt den IFrame innerhalb dieses Elements. Lassen Sie den Platzhalter leer: Bereits enthaltene Texte oder andere Elemente werden beim Laden des Formulars ersetzt. Die gewählte ID darf auf der Seite nur einmal vorkommen.

## Beispiel für eine Online-Registrierung

```html
<div id="gwatch-iframe"></div>
<script
    src="https://gwatch.events/iframe.js"
    data-event-key="[EVENT-KEY]"
    data-url-partial="registration">
</script>

```

Hier ist die **Online-Registrierung** voreingestellt. Ersetzen Sie `[EVENT-KEY]` und verwenden Sie gegebenenfalls die abweichende Skript-URL Ihrer Installation. Öffnen Sie anschließend die veröffentlichte Website, um die Einbindung zu prüfen; manche Redaktionssysteme führen Skripte in ihrer Bearbeitungsvorschau nicht aus.

## Breite und Höhe des Formularfensters

Der IFrame nutzt **100 % der Breite seines übergeordneten Elements**. Ist die Spalte Ihrer Website schmal, bleibt auch das Formularfenster entsprechend schmal. Passen Sie in diesem Fall das Layout der Zielseite an.

Die voreingestellte Höhe beträgt **`100dvh`**. Das entspricht der aktuellen Höhe des sichtbaren Browserbereichs. Die Höhe wird nicht automatisch an die Länge des Formularinhalts angepasst. Bei langen Formularen kann deshalb im Formularfenster gescrollt werden müssen.

Mit `data-height` können Sie eine andere CSS-Höhe vorgeben, beispielsweise **`900px`**. Eine Zahl ohne Einheit, etwa `900`, ist dafür nicht geeignet.

## Einstellungen im Überblick

Die folgenden Angaben sind optional und werden am `<script>` ergänzt.

<table id="bkmrk-einstellung-vorgabe-"><thead><tr><th>Einstellung</th><th>Vorgabe</th><th>Wirkung und Beispiel</th></tr></thead><tbody><tr><td>`data-target`</td><td>`gwatch-iframe`</td><td>ID des Elements, in das das Formular geladen wird. Bei `data-target="veranstaltungsformular"` muss das Element `<div id="veranstaltungsformular"></div>` heißen. Geben Sie die ID ohne `#` an.</td></tr><tr><td>`data-height`</td><td>`100dvh`</td><td>Höhe des IFrames als CSS-Wert, zum Beispiel `data-height="900px"`.</td></tr><tr><td>`data-scroll-offset`</td><td>`0`</td><td>Abstand in Pixeln oberhalb des Formulars beim automatischen Zurückscrollen, zum Beispiel `data-scroll-offset="80"` für eine feststehende Kopfzeile. Hier wird nur eine ganze Zahl ohne `px` eingetragen.</td></tr></tbody></table>

## Beispiel mit eigener ID, Höhe und Scroll-Abstand

```html
<div id="veranstaltungsformular"></div>
<script
    src="https://gwatch.events/iframe.js"
    data-event-key="[EVENT-KEY]"
    data-url-partial="registration"
    data-target="veranstaltungsformular"
    data-height="900px"
    data-scroll-offset="80">
</script>

```

In diesem Beispiel wird das Formular im Element **veranstaltungsformular** angezeigt. Das Fenster ist **900 Pixel hoch**. Beim automatischen Zurückscrollen bleiben **80 Pixel Abstand** zum oberen Fensterrand, damit eine feststehende Kopfzeile den Formularanfang nicht verdeckt.

## Was nach dem Absenden passiert

Wenn das GATEWatch-Formular nach einer erfolgreichen Übermittlung ausgeblendet wird und den Abschluss meldet, scrollt die umgebende Website zurück zum Anfang des eingebetteten Formulars. So wird der dort angezeigte Abschluss wieder sichtbar.

Dieses Verhalten hängt von der Erfolgseinstellung des jeweiligen Formulars ab. Es wird nicht durch jeden Klick oder jede Fehlermeldung ausgelöst. `data-scroll-offset` verändert nur die Zielposition dieses Scrollens, nicht die Höhe des Formulars.

Prüfen Sie den Abstand auf Ihrer Website mit ihrer tatsächlichen Kopfzeile. Ein positiver Wert lässt oberhalb des Formulars entsprechend mehr Platz.

## Persönliche Links und URL-Parameter erhalten

GATEWatch-Links können zusätzliche Angaben hinter einem `?` enthalten. Das Skript liest bestimmte Parameter der umgebenden Website und verwendet sie für den Formularaufruf.

<table id="bkmrk-parameter-verwendung"><thead><tr><th>Parameter</th><th>Verwendung</th></tr></thead><tbody><tr><td>`url-partial`</td><td>Bestimmt den Formulartyp für diesen Aufruf und kann die Vorgabe aus `data-url-partial` ersetzen.</td></tr><tr><td>`type`</td><td>Ergänzt den konkreten Aufruf, beispielsweise bei einem persönlichen Gastlink.</td></tr><tr><td>`key`</td><td>Übergibt den Schlüssel des persönlichen Formularaufrufs.</td></tr><tr><td>`locale`</td><td>Wird als Sprachangabe an das Formular weitergereicht.</td></tr><tr><td>`GUEST_…`</td><td>Entsprechend benannte Parameter werden an das Formular weitergereicht. Ihre Verwendung hängt vom jeweiligen Formular ab.</td></tr></tbody></table>

Sie müssen diese Parameter für gewöhnliche Einladungen nicht selbst zusammensetzen. Verwenden Sie die von GATEWatch erzeugten Links vollständig. Weiterleitungen, Linkverkürzungen oder die Website dürfen die benötigten Parameter nicht entfernen. Andere Parameter werden durch dieses Skript nicht automatisch weitergereicht.

## Die Einbindung prüfen

1. **Direkter Aufruf:** Öffnen Sie die Zielseite ohne zusätzliche Parameter. Erscheint das vorgesehene Formular der richtigen Veranstaltung?
2. **Darstellung:** Prüfen Sie eine breite und eine schmale Bildschirmansicht. Sind alle Felder und Schaltflächen erreichbar?
3. **Einladungslink:** Öffnen Sie einen neu erzeugten Link aus dem vorgesehenen Einladungsablauf. Stimmen Formular und Zugang?
4. **Übermittlung:** Führen Sie den vorgesehenen Ablauf vollständig aus. Prüfen Sie die Rückmeldung und, sofern eingerichtet, das Zurückscrollen zum Formularanfang.
5. **Kopfzeile:** Verdeckt eine feststehende Navigation den Formularanfang? Passen Sie gegebenenfalls `data-scroll-offset` an.

## Häufige Probleme

<table id="bkmrk-beobachtung-was-sie-"><thead><tr><th>Beobachtung</th><th>Was Sie prüfen sollten</th></tr></thead><tbody><tr><td>**Es erscheint kein Formular.**</td><td>Steht das `<div>` vor dem Skript? Stimmen seine ID und `data-target` überein? Sind Skript-URL, Event-Key und Formulartyp vollständig eingesetzt?</td></tr><tr><td>**Der Code wird als Text angezeigt.**</td><td>Verwenden Sie einen HTML- oder Codeblock, der Skripte ausführen darf, statt eines gewöhnlichen Textfelds.</td></tr><tr><td>**Das Skript wird entfernt oder blockiert.**</td><td>Lassen Sie die Website-Betreuung prüfen, ob das Redaktionssystem, ein Einwilligungsdialog oder die Sicherheitsrichtlinien der Website das externe Skript beziehungsweise den IFrame blockieren.</td></tr><tr><td>**Die falsche Veranstaltung erscheint.**</td><td>Vergleichen Sie Event-Key und Skript-URL mit den Angaben der Event-Administration.</td></tr><tr><td>**Es erscheint ein anderer Formulartyp als eingetragen.**</td><td>Prüfen Sie, ob die Seitenadresse einen Parameter `url-partial` enthält. Dieser kann die Vorgabe ersetzen.</td></tr><tr><td>**Ein persönlicher Link führt nur zum allgemeinen Einstieg.**</td><td>Kontrollieren Sie, ob die vollständigen URL-Parameter nach einer Weiterleitung noch vorhanden sind. Vergleichen Sie außerdem die hinterlegte alternative Formular-URL mit der tatsächlichen Zielseite.</td></tr><tr><td>**Das Formular ist zu schmal oder die Höhe passt nicht.**</td><td>Prüfen Sie die Breite des umgebenden Website-Elements und den Wert von `data-height`. Die Fensterhöhe wächst nicht automatisch mit dem Formularinhalt.</td></tr><tr><td>**Nach dem Absenden wird nicht nach oben gescrollt.**</td><td>Prüfen Sie zunächst, ob die Übermittlung erfolgreich war und das Formular für das Ausblenden im Erfolgsfall eingerichtet ist. Erst danach den Scroll-Abstand anpassen.</td></tr><tr><td>**Der Formularanfang verschwindet unter der Kopfzeile.**</td><td>Erhöhen Sie `data-scroll-offset` passend zur Höhe der feststehenden Kopfzeile.</td></tr></tbody></table>

**Für die Website-Betreuung:** Das Skript meldet fehlende oder ungültige Pflichtangaben sowie ein nicht gefundenes Zielelement in der Browserkonsole mit **„GWatch error:“**. Diese Meldung hilft, die Ursache einzugrenzen.

**Zur Vorbereitung:** [Voraussetzungen und Formulartypen](https://doc.gwatch.events/books/iframe-einbindung/page/voraussetzungen).