Widget Einbettung - Advanced

HTML-Seitenstruktur

Minimale Seitenstruktur mit Header, optionaler Sidebar und einem Widget im Hauptbereich.

<!DOCTYPE html>
<html lang="de">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Meine Buchungsseite</title>
  <script src="https://cdn.anny.co/widget/annyComponents.umd.latest.min.js"></script>
</head>
<body>

  <header>
    <a href="/">Dein Logo</a>
    <nav><!-- Navigation --></nav>
    <a-login-button base-url="https://anny.co"></a-login-button>
    <a-cart-modal-button base-url="https://anny.co" modal-layout="drawer"></a-cart-modal-button>
  </header>

  <main>
    <aside><!-- optionale Sidebar --></aside>

    <div>
      <a-resource-booking-panel
        base-url="https://anny.co"
        resource="my-resource"
      ></a-resource-booking-panel>

      <!-- weiterer Seiteninhalt -->
    </div>
  </main>

</body>
</html>

Das Script wird einmal im <head> geladen.
a-login-button und a-cart-modal-button gehören in den Header, damit sie auf allen Seiten sichtbar bleiben.
Ersetze das Panel durch ein Seiten-Widget mit fullscreen="true" und nav-height, wenn die Buchung die gesamte Viewport-Höhe füllen soll (siehe Ganzseitige Widgets weiter unten).

Ganzseitige Widgets

Seiten-Widgets eignen sich, wenn das Widget den Hauptinhalt der Seite darstellt. Seiten-Widgets:

a-organization-page
a-organization-map
a-organization-calendar
a-resource-page
a-resource-map
a-resource-calendar
a-service-page
a-subscription-page
a-package-page
a-my-bookings

Empfohlene Integration für ganzseitige Layouts

Verwende fullscreen="true", damit das Widget die verfügbare Viewport-Höhe ausfüllt. Wenn deine Website einen festen Header hat, übergib zusätzlich nav-height, damit das Widget nicht darunter gerendert wird.

<a-resource-calendar
  base-url="https://anny.co"
  resource="my-resource"
  fullscreen="true"
  nav-height="72px"
></a-resource-calendar>

Hinweise:

fullscreen="true" entspricht height: 100vh.
nav-height ändert das auf calc(100vh - nav-height).
Wenn du height setzt, wird die automatische Größenanpassung deaktiviert und der iframe hat eine feste Höhe.
Für *-page, Map-, Kalender- und a-my-bookings-Widgets sind ganzseitige Layouts in der Regel die sauberste Integration.

Organization-Map und Organization-Kalender

Diese sind Seiten-Widgets, keine Modal-Buttons. Behandle sie wie einen vollständigen Seitenbereich.

<a-organization-map
  base-url="https://anny.co"
  organization="my-org"
  fullscreen="true"
></a-organization-map>

<a-organization-calendar
  base-url="https://anny.co"
  organization="my-org"
  calendar-view="week"
  fullscreen="true"
></a-organization-calendar>

Verwende die Organization-Map, wenn die Karte die primäre Benutzeroberfläche ist. Verwende den Organization-Kalender, wenn die Verfügbarkeitsnavigation im Vordergrund steht. Wenn du stattdessen den vollständigen Explore-Flow möchtest, nimm a-organization-page.

Panels

Booking-Panels sind bewusst kompakt gehalten und sperren die Navigation. Panel-Widgets:

a-resource-booking-panel
a-service-booking-panel

Wichtiges Verhalten:

Panels verwenden immer dynamische Höhe.
Externe height- und fullscreen-Werte werden ignoriert.
Panels sind dazu gedacht, den Buchungsfluss in dein eigenes Seitenlayout einzubetten.

<a-service-booking-panel
  base-url="https://anny.co"
  service="intro-call"
></a-service-booking-panel>

Wenn Kund:innen im eingebetteten Checkout eine Zahlungsmethode wählen, die anny verlässt (PayPal, iDEAL, giropay, Sofort, Bancontact, EPS, Przelewy24, TWINT), öffnet das Widget die Zahlungsseite in einem zentrierten Popup. Karte und SEPA bleiben im Widget (Stripe-Overlay). Der Hinweis im Checkout lautet: Deine Buchung muss online bezahlt werden. Dafür wird sich ein neues Fenster öffnen in dem du die Bezahlung durchführen kannst. Danach wird sich das Fenster automatisch schließen. Blockiert der Browser das Popup, läuft die Zahlung im Widget weiter. Das Host-Dokument der Website wird nicht navigiert. Diese zwei Komponenten werden unter Organisation → Einstellungen → Buchungsseite → Globale Komponenten konfiguriert. Sie sind als gemeinsame Steuerelemente gedacht, die sich in der Regel im Site-Header oder in einer fixen Navigationsleiste befinden. Verwende a-login-button, wenn du ein gemeinsames Login/Logout-Element benötigst, das mit der Widget-Session synchron bleibt.

<a-login-button
  base-url="https://anny.co"
  locale="de"
  idp-uuid="your-idp-uuid"
></a-login-button>

Verhalten:

Lädt einen eigenen Login-iframe.
Wechselt automatisch in den eingeloggten Avatar-Zustand.
Sendet Auth-Änderungen weiter, damit benachbarte Widgets ihren Authentifizierungszustand aktualisieren.

Gute Platzierungen:

Haupt-Site-Header
Mobile Navigation Drawer
Obere Leiste auf Buchungs-Landingpages

Warenkorb-Button

Verwende a-cart-modal-button, wenn Nutzer Artikel aus Booking-Widgets hinzufügen und später auschecken sollen.

<a-cart-modal-button
  base-url="https://anny.co"
  modal-layout="drawer"
  label="Warenkorb"
></a-cart-modal-button>

Verhalten:

Zeigt eine Live-Badge mit der Artikelanzahl.
Bleibt mit benachbarten Widgets auf derselben Seite synchron.
Öffnet den Checkout in einem Modal-Overlay.

Häufige Kombinationen:

a-resource-booking-panel zusammen mit a-cart-modal-button
Mehrere Booking-Widgets auf einer Seite mit einem gemeinsamen Warenkorb-Button

Events und Tracking

Die meisten Embed-Widgets leiten Buchungs-Lifecycle-Events als DOM Custom Events weiter. Trifft für alles aus den Login-Button zu. Unterstützte Event-Namen:

view-page
add-to-cart
start-checkout
complete-checkout

Häufige Felder im Event-Payload:

event_name
value
gross_value
tax
currency
transaction_id
items

Beispiel:

<a-resource-page
  id="booking-widget"
  base-url="https://anny.co"
  resource="my-resource"
></a-resource-page>

<script>
  const widget = document.getElementById('booking-widget')

  widget.addEventListener('complete-checkout', (event) => {
    const data = event.detail
    console.log('Checkout abgeschlossen', data.transaction_id, data.gross_value, data.currency)
  })
</script>

GA4-Beispiel:

<script>
  const widget = document.getElementById('booking-widget')

  widget.addEventListener('complete-checkout', (event) => {
    const data = event.detail

    gtag('event', 'purchase', {
      currency: data.currency,
      value: data.gross_value ?? data.value,
      transaction_id: data.transaction_id,
      items: (data.items || []).map((item) => ({
        item_id: item.id,
        item_name: item.name,
        quantity: item.quantity,
        price: item.price,
      })),
    })
  })
</script>

Hinweise:

a-login-button und a-cart-modal-button sind Hilfs-Widgets und senden keine Buchungs-Events.
Seiten-Widgets, Maps, Kalender, Booking-Panels und checkout-orientierte Seiten senden Buchungs-Events.
Subscription- und Package-Widgets senden checkout-fokussierte Events. In der Praxis sind view-page, start-checkout und complete-checkout die relevantesten.

UTM-Parameter und Click-IDs

Für Attribution musst du nichts weiter tun. Wenn ein Widget lädt, liest es den Query-String der übergeordneten Seiten-URL aus und leitet diese Parameter automatisch in den eingebetteten iframe weiter:

Parameter	Plattform
`utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`	Alle (Google Analytics u. a.)
`gclid`	Google Ads
`fbclid`	Meta / Facebook Ads
`ttclid`	TikTok Ads
`li_fat_id`	LinkedIn Ads

Wenn ein Nutzer also über ?utm_campaign=fruehling&gclid=abc123 auf deine Seite kommt, trägt das Widget diese Werte durch den gesamten Buchungsfluss – Conversion-Tracking funktioniert ohne zusätzliche Konfiguration. Es ist kein HTML-Attribut erforderlich – die Weiterleitung erfolgt automatisch bei jedem Widget-Ladevorgang.

Start- und Enddatum

Die meisten Widgets akzeptieren start (und manchmal end), um Kalender oder Karte auf einen bestimmten Datumsbereich vorzunavigieren. ISO-8601-Datumsstring – exaktes Datum:

<a-resource-page
  base-url="https://anny.co"
  resource="my-resource"
  start="2025-06-15"
></a-resource-page>

Relativer Schlüsselwert – wird zum Render-Zeitpunkt aufgelöst:

Wert	Bedeutung
`today`	Aktueller Tag
`tomorrow`	Nächster Tag
`this_week`	Beginn der aktuellen Woche
`next_week`	Beginn der nächsten Woche
`this_month`	Beginn des aktuellen Monats
`next_month`	Beginn des nächsten Monats

<a-resource-booking-panel
  base-url="https://anny.co"
  resource="my-resource"
  start="tomorrow"
></a-resource-booking-panel>

Relative Werte werden überall unterstützt – außer bei a-resource-calendar und a-organization-calendar, die ISO 8601 erfordern. end erwartet immer einen ISO-8601-Datumsstring. Dieser Abschnitt dokumentiert die öffentlichen HTML-Attribute. Admin-generierte Snippets decken in der Regel die wichtigsten davon bereits ab.

Gemeinsame Attribute für Embed-Widgets

Gilt für Seiten-Widgets und Panel-Widgets. Nicht anwendbar auf Button-Widgets.

Attribut	Zweck
`base-url`	Erforderlich. anny-Basis-URL, z. B. `https://anny.co`
`locale`	Widget-Sprache erzwingen. Wird es weggelassen, wird die Browser-Sprache verwendet
`height`	Feste iframe-Höhe, z. B. `700px` oder `80vh`. Deaktiviert die automatische Größenanpassung. Nicht für Button-Widgets.
`fullscreen`	Viewport-Höhe füllen (`100vh`). Nicht für Button-Widgets.
`nav-height`	Abstand vom Viewport-Rand bei `fullscreen`, z. B. `64px`
`should-login`	Login vor der Buchung erforderlich
`idp-uuid`	UUID des SSO-Identity-Providers
`logo-url`	Eigenes Logo für die Lade-Animation

Alle Embed-Widgets akzeptieren zusätzlich die Design-Attribute aus WIDGET_DESIGNING.md.

Organization-Widgets

`a-organization-page`

Attribut	Zweck
`organization`	Erforderlicher Organization-Slug
`default-list`	Initialer Tab: `resources`, `services`, `subscriptions` oder `packages`
`view`	`grid`, `list` oder `calendar`
`calendar-view`	`day`, `week`, `month` oder `list`
`start`	Initiales Startdatum (siehe Start- und Enddatum)
`end`	Initiales Enddatum
`default-category`	Ressourcenkategorie vorauswählen
`hide-resource-header`	Ressource-Header ausblenden
`hide-organization-header`	Organization-Header ausblenden
`hide-organization-filters`	Filterleiste ausblenden
`hide-organization-map`	Karten-Umschalter ausblenden

Hinweis:

Die Option „Kalender-Board” im Admin entspricht calendar-view="list".

`a-organization-calendar`

Attribut	Zweck
`organization`	Erforderlicher Organization-Slug
`calendar-view`	`day`, `week`, `month` oder `list`
`category`	Kategorie-Slug
`start`	Initiales Startdatum (nur ISO 8601)
`end`	Initiales Enddatum

`a-organization-map`

Attribut	Zweck
`organization`	Erforderlicher Organization-Slug
`start`	Initiales Startdatum (siehe Start- und Enddatum)
`end`	Initiales Enddatum
`hide-resource-header`	Ressource-Header ausblenden
`hide-organization-header`	Organization-Header ausblenden

Ressource-Widgets

`a-resource-page`

Attribut	Zweck
`resource`	Erforderlicher Ressource-Slug
`service`	Service vorauswählen
`start`	Initiales Startdatum (siehe Start- und Enddatum)
`end`	Initiales Enddatum
`hide-resource-header`	Ressource-Header ausblenden
`hide-organization-header`	Organization-Header ausblenden
`hide-calendar`	Kalender ausblenden

`a-resource-calendar`

Attribut	Zweck
`resource`	Erforderlicher Ressource-Slug
`service`	Service vorauswählen
`calendar-view`	`day`, `week`, `month` oder `list`
`start`	Initiales Startdatum (nur ISO 8601)
`end`	Initiales Enddatum
`hide-resource-header`	Ressource-Header ausblenden
`hide-organization-header`	Organization-Header ausblenden

`a-resource-map`

Attribut	Zweck
`resource`	Erforderlicher Ressource-Slug
`service`	Service vorauswählen
`start`	Initiales Startdatum (siehe Start- und Enddatum)
`end`	Initiales Enddatum
`hide-resource-header`	Ressource-Header ausblenden
`hide-organization-header`	Organization-Header ausblenden

`a-resource-booking-panel`

Attribut	Zweck
`resource`	Erforderlicher Ressource-Slug
`service`	Service vorauswählen
`start`	Initiales Startdatum (siehe Start- und Enddatum)
`end`	Initiales Enddatum

Service-Widgets

`a-service-page`

Attribut	Zweck
`service`	Erforderlicher Service-Slug
`resource`	Optionale Ressource vorauswählen

`a-service-booking-panel`

Attribut	Zweck
`service`	Erforderlicher Service-Slug
`resource`	Optionale Ressource vorauswählen
`start`	Initiales Startdatum (siehe Start- und Enddatum)
`end`	Initiales Enddatum

Subscription- und Package-Widgets

`a-subscription-page`

Attribut	Zweck
`plan`	Erforderlicher Plan-Slug

`a-subscription-button`

Attribut	Zweck
`plan`	Erforderlicher Plan-Slug
`label`	Beschriftung des Trigger-Buttons

`a-package-page`

Attribut	Zweck
`package`	Erforderlicher Package-Slug

`a-package-button`

Attribut	Zweck
`package`	Erforderlicher Package-Slug
`label`	Beschriftung des Trigger-Buttons

Button-Widgets

Gilt für:

a-organization-button
a-resource-button
a-service-button
a-subscription-button
a-package-button
a-modal-button
a-cart-modal-button

Attribut	Zweck
`modal-layout`	`dialog`, `drawer` oder `fullscreen`
`modal-size`	`sm`, `md` oder `lg` für Dialog-Layout
`modal-width`	Benutzerdefinierte Dialog-Breite, z. B. `80vw`
`modal-title`	Titel im Modal-Header
`close-on-backdrop`	Schließen per Klick außerhalb erlauben
`show-close-button`	Schließen-Button anzeigen
`aria-label`	Barrierefreies Label für den Modal-Dialog

Trigger-Attribute für Entity-Buttons

Gilt für:

a-organization-button
a-resource-button
a-service-button
a-subscription-button
a-package-button

Attribut	Zweck
`label`	Standard-Beschriftung des Buttons
`button-width`	Breite des Triggers
`button-background`	Hintergrundfarbe des Triggers
`button-text`	Textfarbe des Triggers

a-modal-button ist anders:

kein label-Prop
keine eingebauten Trigger-Styling-Props
verwende ein eigenes Element im Slot als Trigger

Eigener Trigger (Slot)

Alle Button-Widgets akzeptieren einen Standard-Slot, der den eingebauten Trigger ersetzt. Nutze das, wenn du den Trigger selbst gestalten oder ein anderes Element als Button verwenden möchtest.

<!-- Eigener Button als Trigger -->
<a-resource-button
  base-url="https://anny.co"
  resource="my-resource"
>
  <button class="my-cta-button">Schreibtisch buchen</button>
</a-resource-button>

<!-- Link als Trigger -->
<a-organization-button
  base-url="https://anny.co"
  organization="my-org"
>
  <a href="#">Verfügbarkeit ansehen</a>
</a-organization-button>

<!-- a-modal-button erfordert immer einen Slot-Trigger -->
<a-modal-button
  base-url="https://anny.co"
  resource="my-resource"
>
  <button>Buchung öffnen</button>
</a-modal-button>

Wenn ein Slot verwendet wird, werden label, button-background, button-text und button-width ignoriert. Klick- und Tastatursteuerung werden weiterhin vom Widget-Wrapper übernommen.

`a-resource-button`

Attribut	Zweck
`resource`	Erforderlicher Ressource-Slug
`service`	Optionaler Service
`start`	Initiales Startdatum (siehe Start- und Enddatum)
`hide-resource-header`	Ressource-Header ausblenden
`hide-organization-header`	Organization-Header ausblenden

`a-service-button`

Attribut	Zweck
`service`	Erforderlicher Service-Slug
`resource`	Optionale Ressource vorauswählen

`a-organization-button`

Attribut	Zweck
`organization`	Erforderlicher Organization-Slug
`default-list`	Initialer Organization-Tab
`view`	`grid`, `list` oder `calendar`
`calendar-view`	`day`, `week`, `month` oder `list`
`hide-resource-header`	Ressource-Header ausblenden
`hide-organization-header`	Organization-Header ausblenden

Verwende diesen Button, wenn du einen eigenen Modal-Trigger ohne entity-spezifische Button-Komponente benötigst.

Attribut	Zweck
`resource`	Ressource-Buchungsseite öffnen
`service`	Service vorauswählen (zusammen mit `resource`)
`organization`	Organization-Explore-Seite öffnen
`default-list`	Initialer Organization-Tab
`view`	Initiale Organization-Ansicht
`calendar-view`	Initiale Organization-Kalenderansicht
`hide-resource-header`	Ressource-Header ausblenden
`hide-organization-header`	Organization-Header ausblenden

Hilfs-Widgets

Attribut	Zweck
`label`	Button-Beschriftung
`aria-label`	Barrierefreies Dialog-Label
`modal-layout`	`dialog`, `drawer` oder `fullscreen`
`modal-size`	Dialog-Größen-Preset
`modal-width`	Benutzerdefinierte Dialog-Breite
`modal-title`	Titel im Modal-Header
`close-on-backdrop`	Schließen per Klick außerhalb
`show-close-button`	Schließen-Button anzeigen
`button-width`	Trigger-Breite
`button-height`	Trigger-Höhe
`button-background`	Trigger-Hintergrund
`button-text`	Trigger-Text-/Icon-Farbe
`show-icon`	Icon ein-/ausblenden

Attribut	Zweck
`locale`	Sprache des Login-Buttons
`idp-uuid`	UUID des SSO-Providers
`button-width`	Trigger-Breite
`button-height`	Trigger-Höhe
`button-background`	Trigger-Hintergrund
`button-text`	Trigger-Text-/Icon-Farbe
`small-border-radius`	Trigger-Eckenradius
`show-icon`	Icon ein-/ausblenden

`a-my-bookings`

Attribut	Zweck
`base-url`	Erforderlich
`locale`	Optionale Sprache
`height`	Feste Höhe
`fullscreen`	Viewport-Höhe füllen
`nav-height`	Header-Abstand für Fullscreen
`idp-uuid`	UUID des SSO-Providers

Hinweis:

a-my-bookings erfordert immer eine Authentifizierung. should-login ist nicht verfügbar, da Login obligatorisch ist.

Externe Zahlung im eingebetteten Checkout

Wenn Kund:innen im Widget mit einer externen Zahlungsmethode bezahlen (zum Beispiel PayPal, iDEAL, Giropay, Sofort, Bancontact, EPS, Przelewy24 oder TWINT), öffnet anny die Zahlungsseite in einem eigenen, zentrierten Fenster. Deine Website und das Widget bleiben geöffnet, der Checkout behält die eingegebenen Daten. Karten- und SEPA-Zahlungen bleiben im Widget. Wird das Zahlungsfenster vom Browser blockiert, läuft die Zahlung stattdessen im Widget selbst weiter. Schließt jemand das Fenster, bevor die Zahlung fertig ist, erscheint der Hinweis, dass die Zahlung nicht durchgeführt werden konnte.

Empfehlungen

Nutze zuerst das Admin-generierte Snippet und verfeinere es manuell nur wenn nötig.
Verwende Seiten-Widgets für dedizierte Buchungsseiten.
Verwende Panels für redaktionelle Seiten rund um den Buchungsfluss.
Verwende Button-Widgets, wenn die Buchung erst nach einem Klick sichtbar sein soll.
Platziere a-login-button und a-cart-modal-button an stabilen, gut sichtbaren Stellen im UI.
Bevorzuge drawer für Desktop-seitige Checkout-Flows und fullscreen für mobile Erlebnisse.

Widget Einbettung - Advanced

HTML-Seitenstruktur

Ganzseitige Widgets

Empfohlene Integration für ganzseitige Layouts

Organization-Map und Organization-Kalender

Panels

Externe Zahlungen im Widget

Warenkorb-Button

Events und Tracking

UTM-Parameter und Click-IDs

Start- und Enddatum

Anpassungsoptionen nach Widget-Typ

Gemeinsame Attribute für Embed-Widgets

Organization-Widgets

`a-organization-page`

`a-organization-calendar`

`a-organization-map`

Ressource-Widgets

`a-resource-page`

`a-resource-calendar`

`a-resource-map`

`a-resource-booking-panel`

Service-Widgets

`a-service-page`

`a-service-booking-panel`

Subscription- und Package-Widgets

`a-subscription-page`

`a-subscription-button`

`a-package-page`

`a-package-button`

Button-Widgets

Trigger-Attribute für Entity-Buttons

Eigener Trigger (Slot)

`a-resource-button`

`a-service-button`

`a-organization-button`

Hilfs-Widgets

`a-my-bookings`

Externe Zahlung im eingebetteten Checkout

Empfehlungen

​HTML-Seitenstruktur

​Ganzseitige Widgets

​Empfohlene Integration für ganzseitige Layouts

​Organization-Map und Organization-Kalender

​Panels

​Externe Zahlungen im Widget

​Login-Button und Warenkorb-Button

​Login-Button

​Warenkorb-Button

​Events und Tracking

​UTM-Parameter und Click-IDs

​Start- und Enddatum

​Anpassungsoptionen nach Widget-Typ

​Gemeinsame Attribute für Embed-Widgets

​Organization-Widgets

​a-organization-page

​a-organization-calendar

​a-organization-map

​Ressource-Widgets

​a-resource-page

​a-resource-calendar

​a-resource-map

​a-resource-booking-panel

​Service-Widgets

​a-service-page

​a-service-booking-panel

​Subscription- und Package-Widgets

​a-subscription-page

​a-subscription-button

​a-package-page

​a-package-button

​Button-Widgets

​Gemeinsame Modal-Attribute

​Trigger-Attribute für Entity-Buttons

​Eigener Trigger (Slot)

​a-resource-button

​a-service-button

​a-organization-button

​a-modal-button

​Hilfs-Widgets

​a-cart-modal-button

​a-login-button

​a-my-bookings

​Externe Zahlung im eingebetteten Checkout

​Empfehlungen

HTML-Seitenstruktur

Ganzseitige Widgets

Empfohlene Integration für ganzseitige Layouts

Organization-Map und Organization-Kalender

Panels

Externe Zahlungen im Widget

Login-Button und Warenkorb-Button

Login-Button

Warenkorb-Button

Events und Tracking

UTM-Parameter und Click-IDs

Start- und Enddatum

Anpassungsoptionen nach Widget-Typ

Gemeinsame Attribute für Embed-Widgets

Organization-Widgets

`a-organization-page`

`a-organization-calendar`

`a-organization-map`

Ressource-Widgets

`a-resource-page`

`a-resource-calendar`

`a-resource-map`

`a-resource-booking-panel`

Service-Widgets

`a-service-page`

`a-service-booking-panel`

Subscription- und Package-Widgets

`a-subscription-page`

`a-subscription-button`

`a-package-page`

`a-package-button`

Button-Widgets

Gemeinsame Modal-Attribute

Trigger-Attribute für Entity-Buttons

Eigener Trigger (Slot)

`a-resource-button`

`a-service-button`

`a-organization-button`

`a-modal-button`

Hilfs-Widgets

`a-cart-modal-button`

`a-login-button`

`a-my-bookings`

Externe Zahlung im eingebetteten Checkout

Empfehlungen