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.

Voraussetzung Was ist zu klären?
Zielseite auf Ihrer Website Auf welcher vollständigen URL soll das Formular erscheinen, beispielsweise https://www.example.com/anmeldung? Teilen Sie diese Adresse Ihrer Event-Administration mit.
Zugriff auf den HTML-Code 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.
Skript-URL 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.
Event-Key Welche Veranstaltung soll geladen werden? Übernehmen Sie den bereitgestellten Event-Key exakt.
Formulartyp Welches Formular soll beim direkten Aufruf der Zielseite zunächst erscheinen? Wählen Sie einen der unten aufgeführten Werte.
Eingerichtetes Formular Das gewünschte Formular muss in der betreffenden Veranstaltung eingerichtet und für den vorgesehenen Ablauf nutzbar sein.

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.

Wert Verwendung
registration Online-Registrierung: Besucher melden sich für die Veranstaltung an.
tbc Teilnahmebestätigung eingeladener Gäste: Gäste bestätigen ihre Teilnahme. Persönliche Einladungslinks können die Zugangsinformationen bereits enthalten.
onl 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.
fbk Feedback: Gäste gelangen zum Login für das Feedback-Formular.
sso Single Sign-on: Einstieg in den dafür eingerichteten SSO-Ablauf, beispielsweise für eine Videoübertragung.

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:

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

Weiter: Das Formular einbinden und prüfen.

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.

<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.

Angabe Was gehört hinein?
src Die Skript-URL, beispielsweise https://gwatch.events/iframe.js.
data-event-key Der Event-Key der Veranstaltung.
data-url-partial Einer der Werte registration, tbc, onl, fbk oder sso.

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

<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.

Einstellung Vorgabe Wirkung und Beispiel
data-target gwatch-iframe 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.
data-height 100dvh Höhe des IFrames als CSS-Wert, zum Beispiel data-height="900px".
data-scroll-offset 0 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.

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

<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.

Parameter Verwendung
url-partial Bestimmt den Formulartyp für diesen Aufruf und kann die Vorgabe aus data-url-partial ersetzen.
type Ergänzt den konkreten Aufruf, beispielsweise bei einem persönlichen Gastlink.
key Übergibt den Schlüssel des persönlichen Formularaufrufs.
locale Wird als Sprachangabe an das Formular weitergereicht.
GUEST_… Entsprechend benannte Parameter werden an das Formular weitergereicht. Ihre Verwendung hängt vom jeweiligen Formular ab.

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

Beobachtung Was Sie prüfen sollten
Es erscheint kein Formular. Steht das <div> vor dem Skript? Stimmen seine ID und data-target überein? Sind Skript-URL, Event-Key und Formulartyp vollständig eingesetzt?
Der Code wird als Text angezeigt. Verwenden Sie einen HTML- oder Codeblock, der Skripte ausführen darf, statt eines gewöhnlichen Textfelds.
Das Skript wird entfernt oder blockiert. Lassen Sie die Website-Betreuung prüfen, ob das Redaktionssystem, ein Einwilligungsdialog oder die Sicherheitsrichtlinien der Website das externe Skript beziehungsweise den IFrame blockieren.
Die falsche Veranstaltung erscheint. Vergleichen Sie Event-Key und Skript-URL mit den Angaben der Event-Administration.
Es erscheint ein anderer Formulartyp als eingetragen. Prüfen Sie, ob die Seitenadresse einen Parameter url-partial enthält. Dieser kann die Vorgabe ersetzen.
Ein persönlicher Link führt nur zum allgemeinen Einstieg. 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.
Das Formular ist zu schmal oder die Höhe passt nicht. 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.
Nach dem Absenden wird nicht nach oben gescrollt. 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.
Der Formularanfang verschwindet unter der Kopfzeile. Erhöhen Sie data-scroll-offset passend zur Höhe der feststehenden Kopfzeile.

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.