> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloud.anex.is/llms.txt
> Use this file to discover all available pages before exploring further.

# VOUCHER! Widget in die Website einbetten

> Anleitung zum Einbetten des VOUCHER! Widgets auf deiner Website, inklusive Sprachauswahl und mehrfacher Einbindung.

Diese Anleitung beschreibt, wie du das VOUCHER! (der Online-Gutscheinverkauf) Widget auf deiner Website einbettest, in welcher Sprache es geladen wird und wie du es mehrfach auf einer Seite verwendest.

## Voraussetzungen

* [Modul VOUCHER!](/de/mandants/modules/voucher) ist aktiviert
* Das VOUCHER! Widget ist eingerichtet und gespeichert (siehe [VOUCHER! Widget einrichten](./setup-voucher))
* Der Einbettungscode ist im Widget unter **Einbettungscode** pro Sprache verfügbar

## Schritte

1. Öffne das VOUCHER! Widget im Mandant-Dashboard unter **Widgets**.
2. Scrolle zum Abschnitt **Einbettungscode**.
3. Wähle über die Sprachauswahl die gewünschte Sprache aus (Deutsch, Italienisch, Englisch).
4. Kopiere den angezeigten HTML-Code.
5. Füge den kopierten Code in den HTML-Quellcode deiner Website ein.

Der Code besteht aus zwei Teilen:

```html theme={null}
<script
  defer
  src="https://widgets.cloud.anex.is/mandant-voucher/script.js"
></script>
<anexis-cloud-voucher language="de" externalid="..."></anexis-cloud-voucher>
```

Das `<script>`-Tag lädt das Widget einmal pro Seite. Das `<anexis-cloud-voucher>`-Tag bindet das eigentliche Widget an dieser Stelle ein.

## Attribute

| Attribut       | Pflicht | Hinweise                                                                                                                    |
| -------------- | ------- | --------------------------------------------------------------------------------------------------------------------------- |
| **language**   | Ja      | Sprachcode (ISO-Kürzel). Bestimmt die Sprache des Widgets. Mögliche Werte: `de`, `it`, `en`.                                |
| **externalid** | Ja      | Externe ID des Widgets aus dem Mandant-Dashboard. Wird beim Erstellen automatisch generiert und kann nicht geändert werden. |
| **id**         | Nein    | Eindeutige ID, falls das Widget mehrfach auf derselben Seite eingebettet wird.                                              |

## Mehrere Sprachen auf derselben Website

Du kannst pro Sprache eine eigene Unterseite erstellen und jeweils den Einbettungscode mit dem passenden `language`-Attribut einfügen. Die `externalid` bleibt für alle Sprachen identisch -- sie kennzeichnet das Widget, nicht die Sprache.

## URL-Parameter

Du kannst das Widget vorausfüllen, indem du die folgenden Query-Parameter an die URL der Webseite anhängst, auf der das Widget eingebettet ist.

### voucher\_id

Die ID eines bestimmten Gutscheins. Wenn der Parameter gesetzt ist, springt das Widget direkt zur Konfiguration dieses Gutscheins. Der Gutschein muss mindestens einer Kategorie zugeordnet sein, sonst wird er ignoriert.

### voucher\_category\_id

Die ID einer Gutscheinkategorie. Wenn der Parameter gesetzt ist (und `voucher_id` nicht), springt das Widget direkt zur Gutscheinauswahl innerhalb dieser Kategorie.

### form\_fields

Ein JSON-Objekt mit Key-Value-Paaren zum Vorausfüllen der Käuferdaten und der Zusatzfelder. Der Key muss der Data-ID des Formularfeldes in Snake-Case entsprechen (z. B. `FirstName` wird zu `first_name`). Ungültiges JSON wird stillschweigend ignoriert.

### Beispiel-URLs

Direkter Aufruf eines bestimmten Gutscheins mit vorausgefüllten Käuferdaten:

```
/?voucher_id=123&form_fields={"first_name":"Maxime","email_address":"maxime@example.com"}
```

Direkter Aufruf einer Gutscheinkategorie:

```
/?voucher_category_id=42
```

Für Verlinkungen müssen Anführungszeichen innerhalb eines `href`-Attributs URL-codiert werden:

```html theme={null}
<a
  class="button primary"
  href="/gutscheine/?voucher_id=123&form_fields=%7B%22first_name%22%3A%22Maxime%22%7D"
>
  Gutschein kaufen
</a>
```

## Data-Attribute

Alle Parameter, die per URL-Query-String übergeben werden können, lassen sich auch als Data-Attribut direkt auf dem `<anexis-cloud-voucher>`-Tag setzen. Die übergebenen Daten müssen stets gültiges JSON enthalten (mit doppelten Anführungszeichen). Bei gleichzeitig gesetztem URL-Parameter und Data-Attribut hat der URL-Parameter Vorrang.

```html theme={null}
<anexis-cloud-voucher
  language="de"
  externalid="..."
  data-voucher_id="123"
  data-form_fields='{"first_name":"Maxime","email_address":"maxime@example.com"}'
></anexis-cloud-voucher>
```

## Mehrfaches Einbinden des Widgets

Wenn du VOUCHER! mehrmals auf derselben Seite einbindest, vergib pro Instanz eine eindeutige **id**:

```html theme={null}
<anexis-cloud-voucher
  id="voucher-widget-1"
  language="de"
  externalid="..."
></anexis-cloud-voucher>

<anexis-cloud-voucher
  id="voucher-widget-2"
  language="de"
  externalid="..."
></anexis-cloud-voucher>
```

Ohne eindeutige `id` werden bei mehrfacher Einbindung Daten zwischen den Widgets vermischt.

## Tipps

* Binde das `<script>`-Tag nur einmal pro Seite ein, auch wenn du mehrere Widget-Instanzen verwendest.
* Teste die Einbettung auf einer Vorschau-Seite, bevor du sie auf der Live-Website veröffentlichst.
* Wenn das Widget nicht erscheint, prüfe die Browser-Konsole auf JavaScript-Fehler und stelle sicher, dass das Modul VOUCHER!, die Komponente und das Widget aktiv sind.

## Verwandte Artikel

* [VOUCHER! Widget einrichten](./setup-voucher) -- Ersteinrichtung des Widgets
* [VOUCHER! Widget Seitenreferenz](./voucher) -- alle Einstellungen und Felder im Detail
* [VOUCHER! einrichten](/de/mandants/components/setup-voucher) -- Komponente einrichten