# Anleitung

# Minimale Konfiguration

Die minimale Konfiguration eines Dienstes wird in dem folgenden Codeausschnitt dargestellt.

<!DOCTYPE html>
<html lang="de">
<head>
	<meta charset="UTF-8">
	<meta name="viewport" content="width=device-width, initial-scale=1.0">
	<title>Beispiel ABH Webauftritt</title>
	<link rel="stylesheet" href="https://api.service-digitale-verwaltung.de/embed/themes/tf-blue.css">
	<script src="https://api.service-digitale-verwaltung.de/embed/polyfill/polyfill.js" charset="UTF-8"></script>
</head>
<body style="margin-top: 4rem;">
	<dienst-name ags="ags-wert"></dienst-name>
	<script src="https://api.service-digitale-verwaltung.de/embed/dienst-name/dienst-name.js" charset="UTF-8"></script>
</body>
</html>

Wichtig: Es handelt sich um ein allgemeines Beispiel, um einen bestimmten Dienst einzubinden, muss der dienst-name und ags-wert aus dem Ausschnitt entsprechend angepasst werden.

Es stehen die folgenden Dienste zur Verfügung:

Ausländerwesen	Personenstandswesen	eWaffe
`at-ausbildung`	`pw-anmeldung-eheschliessung`	`ewaffe-anzeige-unbrauchbarmachung`
`at-erwerbstaetigkeit`	`pw-eheurkunde`	`ewaffe-anzeige-verlust`
`at-fachkraefteverfahren`	`pw-geburtsanzeige`	`ewaffe-ausnahme-mindestalter-schiessstaetten`
`at-familiennachzug`	`pw-geburtsanzeige-eltern`	`ewaffe-bescheid-widerspruch`
`at-germany-for-ukraine`	`pw-geburtsurkunde`	`ewaffe-blockiersystem-erbwaffen`
`at-nebenbestimmungen`	`pw-lebenspartnerschaftsurkunde`	`ewaffe-editing-tool`
`at-niederlassungserlaubnis`	`pw-sterbefallanzeige`	`ewaffe-eu-feuerwaffenpass-ausstellung`
`aw-aufenthaltskarte`	`pw-sterbeurkunde`	`ewaffe-eu-feuerwaffenpass-verlaengerung`
`aw-einbuergerung`		`ewaffe-gelbe-wbk-sportschuetze-erteilung`
`aw-buendelungskomponente`		`ewaffe-gruene-wbk-person-erteilung`
		`ewaffe-kleiner-waffenschein-erteilung`
		`ewaffe-mitnahme-erteilung`
		`ewaffe-mitnahme-verlaengerung`
		`ewaffe-rote-wbk-erteilung`
		`ewaffe-schiesserlaubnis-erteilung`
		`ewaffe-verbringung-erteilung`
		`ewaffe-waffenschein-erteilung`
		`ewaffe-waffenschein-verlaengerung`
		`ewaffe-wbk-austragung-ueberlassung`
		`ewaffe-wbk-eintragung-erwerb`
		`ewaffe-wbk-erbfall`
		`ewaffe-wbk-voreintrag`
		`ewaffe-wbk-vereine-erteilung`

Zulassungswesen	Wahlschein	Kita
`ikfz-service`	`ws-briefwahlantrag`	`kita-anmeldung`
`ikfz-kennzeichenreservierung`	`ws-briefwahlantrag-qr`

Fahrtenschreiberkarte	Führerscheinweisen	Einwohnerwesen
`fs-fahrerkarte`	`fw-umtausch-altfahrerlaubnis`	`ew-abmeldung-ausland`
`fs-unternehmenskarte`	`fw-internationaler-fuehrerschein`	`ew-meldebescheinigung`
`fs-werkstattkarte`	`fw-fahrerqualifizierungsnachweis`	`ew-selbstauskunft`
	`fw-fahrerlaubnis-ersterteilung`	`ew-statusabfrage-ausweis`
	`fw-fahrerlaubnis-erweiterung`	`ew-uebermittlungssperren`
	`fw-fahrerlaubnis-verlaengerung`	`ew-wohnsitzanmeldung`
		`ew-wohnungsgeberbestaetigung`

Die minimale Konfiguration eines tatsächlichen Dienstes mit AGS wird im folgenden Codeausschnitt dargestellt.

<!DOCTYPE html>
<html lang="de">
<head>
	<meta charset="UTF-8">
	<meta name="viewport" content="width=device-width, initial-scale=1.0">
	<title>Beispiel ABH Webauftritt</title>
	<link rel="stylesheet" href="https://api.service-digitale-verwaltung.de/embed/themes/tf-blue.css">
	<script src="https://api.service-digitale-verwaltung.de/embed/polyfill/polyfill.js"></script>
</head>
<body style="margin-top: 4rem;">
	<at-erwerbstaetigkeit ags="09000001"></at-erwerbstaetigkeit>
	<script src="https://api.service-digitale-verwaltung.de/embed/at-erwerbstaetigkeit/at-erwerbstaetigkeit.js" charset="UTF-8"></script>
</body>
</html>

Wichtig: In diesem Beispiel wurde der Dienst at-erwerbstaetigkeit für die Gemeinde mit dem AGS 09000001 eingebunden. Der AGS muss durch den Betreiber des Dienstes für Ihre Domain freigegeben werden.

Neben der Einbindung mit der minimalen Konfiguration eines Dienstes haben Sie noch weitere Konfigurationsmöglichkeiten (z. B. Theme, Sprache). Diese werden in den folgenden Absätzen erläutert.

# Maximale Konfiguration

Maximale Konfiguration am Beispiel at-erwerbstaetigkeit mit dem AGS 12345678.

<html lang="de">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>Antrag für einen Aufenthaltstitel zur Erwerbstätigkeit</title>
        <link rel="stylesheet" href="https://api.service-digitale-verwaltung.de/embed/themes/tf-blue.css">
        <script src="https://api.service-digitale-verwaltung.de/embed/polyfill/polyfill.js"></script>
    </head>
    <body style="margin-top: 4rem;">
        <noscript>
            Für die Verwendung dieses Dienstes ist JavaScript erforderlich.
                Bitte aktivieren Sie diese Funktion in Ihren Browsereinstellungen oder verwenden Sie einen anderen Web-Browser mit aktiviertem JavaScript.
        </noscript>
        <at-erwerbstaetigkeit
            ags="12345678"
            language-selection
            excluded-languages="ru, tr"
            hide-login="false"
            plz-check
            hide-page-nav="true"
            page-nav-position="left"
        ></at-erwerbstaetigkeit>
        <script src="https://api.service-digitale-verwaltung.de/embed/at-erwerbstaetigkeit/at-erwerbstaetigkeit.js" charset="UTF-8"></script>
    </body>
</html>

hide-login wird nur bei at-germany-for-ukraine und at-erwerbstaetigkeit (Default: true) unterstützt (s. auch Kapitel Attribute).
Wenn hide-page-nav="true", dann ist page-nav-position="left" obsolet. Es wurde trotzdem beides aufgeführt um alle Konfigurationsmöglichkeiten aufzuzeigen.
excluded-languages wird nur in Diensten des Ausländerwesens (at-*, aw-*) unterstützt. (Außer aw-einbuergerung.)

Maximale Konfiguration am Beispiel ewaffe-gruene-wbk-person-erteilung mit dem AGS 12345678.

<html lang="de">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>Erteilung grüne Waffenbesitzkarte für einzelne Person</title>
        <link rel="stylesheet" href="https://api.service-digitale-verwaltung.de/embed/themes/tf-blue.css">
        <script src="https://api.service-digitale-verwaltung.de/embed/polyfill/polyfill.js"></script>
    </head>
    <body style="margin-top: 4rem;">
        <noscript>
            Für die Verwendung dieses Dienstes ist JavaScript erforderlich.
                Bitte aktivieren Sie diese Funktion in Ihren Browsereinstellungen oder verwenden Sie einen anderen Web-Browser mit aktiviertem JavaScript.
        </noscript>
        <ewaffe-gruene-wbk-person-erteilung
            ags="12345678"
            language-selection
            hide-login="false"
            plz-check
            showSessionTimeout
            sessionTimeoutVariant="1"
            hide-page-nav="true"
            page-nav-position="left"
        ></ewaffe-gruene-wbk-person-erteilung>
        <script src="https://api.service-digitale-verwaltung.de/embed/ewaffe-gruene-wbk-person-erteilung/ewaffe-gruene-wbk-person-erteilung.js" charset="UTF-8"></script>
    </body>
</html>

# Test-Umgebung

In den Code-Beispielen wird die Produktiv-Umgebung (api.service-digitale-verwaltung.de) verwendet.

Zum Testen steht Ihnen auch unsere Pre-Produktiv-Umgebung unter api.pre-service-digitale-verwaltung.de zur Verfügung. Bitte beachten Sie hierbei jedoch, dass es sich um ein Test-System handelt, auf dem eine neuere Version also auf der Produktiv-Umgebung installiert sein kann. Außerdem kann es hier gelegentlich zu kürzeren Wartungsarbeiten kommen, währenddessen das System nicht wie gewohnt reagiert.

<!DOCTYPE html>
<html lang="de">
<head>
	<meta charset="UTF-8">
	<meta name="viewport" content="width=device-width, initial-scale=1.0">
	<title>Testumgebung - Beispiel ABH Webauftritt</title>
	<link rel="stylesheet" href="https://api.pre-service-digitale-verwaltung.de/embed/themes/tf-blue.css">
	<script src="https://api.service-digitale-verwaltung.de/embed/polyfill/polyfill.js"></script>
</head>
<body style="margin-top: 4rem;">
	<at-erwerbstaetigkeit ags="09000001"></at-erwerbstaetigkeit>
	<script src="https://api.pre-service-digitale-verwaltung.de/embed/at-erwerbstaetigkeit/at-erwerbstaetigkeit.js" charset="UTF-8"></script>
</body>
</html>

Wichtig: Dieses Beispiel zeigt, wie ein Dienst von der Pre-Produktiv-Umgebung eingebunden werden kann. Der AGS muss durch den Betreiber des Dienstes für Ihre Domain auf der Pre-Produktiv-Umgebung unabhängig von der Produktiv-Umgebung freigegeben werden.

# Themes

Ein Theme kontrolliert das Aussehen und die grafischen Eigenschaften der Seiten.

Es stehen die folgenden Themes zur Verfügung:

default.css: Die primären Farben des Layouts werden in einem grünlichen Ton gehalten
bb-red.css: Die primären Farben des Layouts werden in einem roten Ton gehalten
tf-blue.css: Die primären Farben des Layouts werden in einem blauen Ton gehalten

Für eine Anpassung des Themes muss der theme-name entsprechend geändert werden.


<link rel="stylesheet" href="https://api.service-digitale-verwaltung.de/embed/themes/theme-name.css">

Beispiel: Nutzung des bb-red.css Themes.


<link rel="stylesheet" href="https://api.service-digitale-verwaltung.de/embed/themes/bb-red.css">

# Browser-Kompatibilität

Die Datei polyfill.js lädt je nach Browser die entsprechenden Polyfills zur Erhöhung der Browser-Kompatibilität nach. Wichtig ist, dass diese Datei eingebunden wird bevor die Webkomponente geladen wird. Für den Internet Explorer 11 und den Edge Legacy ist der Dienst nicht mehr verfügbar. Stattdessen wird dem Nutzer eine entsprechende Meldung angezeigt.

Wie in obigen Code-Beispielen gezeigt, kann der Polyfill wie folgt eingebunden werden:


<script src="https://api.service-digitale-verwaltung.de/embed/polyfill/polyfill.js"></script>

# Spracheinstellung

Für die Steuerung der Sprache verwendet die Web-Komponente das lang Attribut aus dem html Element.

Steuerung der Sprache über das lang Attribut. In diesem Fall wird die englische Sprache verwendet.


<html lang="en">

Gesamtbeispiel für die Steuerung der Sprache. In diesem Beispiel wird der Dienst at-erwerbstaetigkeit unter dem AGS 09000001 in englischer Sprache verwendet.

<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="UTF-8">
	<meta name="viewport" content="width=device-width, initial-scale=1.0">
	<title>Beispiel ABH Webauftritt</title>
	<link rel="stylesheet" href="https://api.service-digitale-verwaltung.de/embed/themes/tf-blue.css">
	<script src="https://api.service-digitale-verwaltung.de/embed/polyfill/polyfill.js"></script>
</head>
<body style="margin-top: 4rem;">
	<at-erwerbstaetigkeit ags="09000001"></at-erwerbstaetigkeit>
	<script src="https://api.service-digitale-verwaltung.de/embed/at-erwerbstaetigkeit/at-erwerbstaetigkeit.js" charset="UTF-8"></script>
</body>
</html>

Sollte es nicht möglich sein, das lang Attribut auf dem html Element wie hier beschrieben zu setzen. Kann eine Sprachauswahl innerhalb des Dienstes bereitgestellt werden. Dies führt allerdings dazu, dass die Webseite und der eingebettete Dienst in unterschiedlichen Sprachen angezeigt werden und sollte deshalb vermieden werden.

Weitere Informationen dazu finden Sie im Abschnitt Attribute.

# JavaScript

Für die Einbindung und Funktionsweise der Dienste wird JavaScript benötigt.

Damit der Benutzer einen entsprechenden Hinweis bekommt, falls in seinem Browser JavaScript deaktiviert sein sollte, empfiehlt sich die Verwendung eines noscript Elementes.

Beispiel: Nutzung des noscript Elementes.

<!DOCTYPE html>
<html lang="de">
<head>
	<!-- ... -->
</head>
<body style="margin-top: 4rem;">
    <noscript>
        Für die Verwendung dieses Dienstes ist JavaScript erforderlich.
        Bitte aktivieren Sie diese Funktion in Ihren Browsereinstellungen oder verwenden Sie einen anderen Browser.
    </noscript>
    <!-- ... -->
</body>
</html>

# Seitenbreite

Damit die Komponenten auch auf Geräten mit geringer Breite (z. B. Smartphones) gut aussehen und ein positives Nutzererlebnis gewährleisten können, verhalten sich die Komponenten responsiv. Dies ist allerdings nur möglich, wenn auch die Seite sich responsiv verhält.

Steht also nur ein kleiner Container (<1080px) zur Verfügung, kann die Einbindung der Komponente mit folgenden Schritten optimiert werden:

Webseite so vorbereiten, sodass links und rechts der Komponente, wenn möglich keine anderen Elemente (z. B. Navigation, Widgets) vorhanden sind
Ausblenden der Störungsmeldung ("html.stoerungsmeldung": "$hidden")
Ausblenden der Seiten-Navigation (HTML-Attribut hide-page-nav, siehe Attribute)

# Attribute

Name	Beschreibung	Pflichtangabe	Standardwert
`ags`	Der Allgemeine Gemeindeschlüssel der Kommune	Ja
`page-nav-position`	Steuert, wo die Seitennavigation angezeigt werden soll. Mögliche Werte: `left`, `right` oder `top`. Diese Option muss bei Verwendung von `aw-einbuergerung` auf `top-progress` gesetzt werden.	Nein	`left`
`hide-page-nav`	Steuert, ob die Seitennavigation ausgeblendet werden soll. Mögliche Werte: `true` oder `false`.	Nein	`false`
`language-selection`	Steuert, ob die Sprachauswahl angezeigt werden soll. Parameter ohne Wert (Beispiel-Verwendung: `<at-erwerbstaetigkeit language-selection>`). Die Vorauswahl der Sprache kann, wie im Kapitel Spracheinstellung beschrieben, bestimmt werden. (Außer `aw-einbuergerung`.)	Nein	Sprachauswahl ausgeblendet
`excluded-languages`	Steuert, welche Sprachen in der Sprachauswahl nicht angezeigt werden sollen. Beispiel-Verwendung: `<at-erwerbstaetigkeit excluded-languages="ru,tr" />`.	Nein	Keine Sprache ist ausgeschlossen
`plz-check`	Steuert, ob der Verfügbarkeitscheck angezeigt werden soll. Parameter ohne Wert (Beispiel-Verwendung: `<at-erwerbstaetigkeit plz-check>`).	Nein	Verfügbarkeitscheck ausgeblendet
`hide-login`	Steuert, ob die Anmelde-Funktion angezeigt wird, falls der Dienst diese unterstützt. Diese Option ist derzeit nur bei den Diensten `at-germany-for-ukraine` und `at-erwerbstaetigkeit` verfügbar. Bei `at-erwerbstaetigkeit` wird die Anmelde-Funktion nur dann angezeigt wenn `hide-login="false"` angegeben wurde.	Nein	`at-erwerbstaetigkeit`: Anmelde-Funktion ausgeschaltet
`kommunalportal`	Steuert, ob der Dienst innerhalb des Kommunalportals betrieben wird. Bei dem Wert `auto` wird geprüft, ob die Domain der einbindenden Seite auf `.kommunalportal.nrw` endet. Mögliche Werte: `true`, `false` oder `auto`. Diese Option ist derzeit nur beim Dienst `aw-einbuergerung` verfügbar.	Nein	`auto`
`feature-set`	Steuert, ob zukünftige Funktionen aktiviert werden sollen. Mögliche Werte: `stable` (Nur veröffentlichte funktionen), `next` (Änderungen die für einen der nächsten Releases vorgesehen sind) oder `future` (Änderungen, die zeitlich noch nicht eingeplant sind). Diese Option muss bei Verwendung von `aw-einbuergerung` außerhalb des Kommunalportals auf `next` gesetzt werden.	Nein	`stable`

# Bündelungskomponente (aw-buendelungskomponente)

Die Bündelungskomponente ist eine Übersichtsseite mit mehreren Diensten, auf der der Benutzer den gewünschten Dienst auswählt. Sie erleichtert das Einbinden für Kommunen, da nicht mehr jeder Dienst einzeln eingebunden werden muss. Stattdessen wird nur die Bündelungskomponente eingebunden und dabei konfiguriert, welche Dienste sichtbar sind.
Die Bündelungskomponente unterstützt zurzeit nur die Dienste des Ausländerwesens (at-*, aw-*).

Normalerweise wird ein Dienst direkt über die Bündelungskomponte eingebunden
Es ist aber auch möglich, jedoch nicht notwendig, den gleichen Dienst einmal direkt und einmal über die Bündelungskomponente einzubinden.

Hinweis zur Migration: Kommunen die schon einen oder mehrere Dienste eingebunden haben, können die Seiten parallel betreiben. Es ist aber auch möglich die bisherigen Seiten komplett durch die Bündelungskomponenten zu ersetzen. Die Texte der Dienste bleiben bestehen und sind bei jeder Variante gleich.

# Standard-Dienste

Folgende Dienste werden automatisch eingebunden (sofern nicht anders konfiguriert, s. Attribut hide-services):

at-ausbildung
at-erwerbstaetigkeit
at-familiennachzug
at-nebenbestimmungen

# Sprachen & Texte

Es stehen alle Sprachen zur Verfügung, die auch für die Standard-Dienste zur Verfügung stehen.

Die Texte der Bündelungskomponente selbst können wie gewohnt über das "OZG Service Management" gepflegt werden.

# Attribute (Bündelungskomponente)

Neben den Standardatttributen hat die Bündelungskomponente einige spezielle Attribute:

Name	Beschreibung	Pflichtangabe	Standardwert
`ags`	S. Kapitel Attribute	s.o.	s.o.
`hide-services`	Steuert, welche der Standard-Dienste nicht angezeigt werden. Mögliche Werte (Standard-Dienste): `at-ausbildung`, `at-erwerbstaetigkeit`, `at-familiennachzug`, `at-nebenbestimmungen`	Nein	Alle Standard-Dienste werden angezeigt
`add-services`	Steuert, welche Dienste zusätzlich zu den Standard-Diensten angezeigt werden. Bsp.: `aw-aufenthaltskarte,at-fachkraefteverfahren,...`	Nein	Keine Zusatz-Dienste werden angezeigt
`hide-login-services`	Steuert, bei welchen Diensten die Anmeldung nicht möglich ist. Bsp.: `at-familiennachzug,at-nebenbestimmungen,...`	Nein	In allen Diensten ist die Login-Funktion verfügbar
`language-selection-services`	Steuert, für welche Dienste die Sprachauswahl angezeigt wird. Bsp.: `at-ausbildung,at-nebenbestimmungen,...`	Nein	Keine Dienste können Sprachen auswählen
`language-selection`	Steuert, ob die Sprachauswahl in der Bündelungskomponente angezeigt wird.	s.o.	s.o.
`excluded-languages`	Steuert, welche Sprachen in der Sprachauswahl nicht angezeigt werden sollen. Beispiel-Verwendung: `<at-erwerbstaetigkeit excluded-languages="ru, tr" />`.	Nein	Keine Sprache ist ausgeschlossen
`hide-page-nav-services`	Steuert, für welche der verfügbaren Dienste die Seitennavigation nicht angezeigt wird. Bsp.: `at-ausbildung,at-erwerbstaetigkeit,...`	Nein	In allen Diensten wird die Navigation angezeigt
`page-nav-position-services`	Steuert, pro Dienst, an welcher Position die Seitennavigation angezeigt wird. Bsp.: `at-ausbildung:right,at-erwerbstaetigkeit:top,...`.	Nein	`left` für alle Dienste
`plz-check-services`	Steuert, für welche Dienste der Verfügbarkeitscheck angezeigt wird. Bsp.: `at-ausbildung,at-nebenbestimmungen,...`	Nein	Verfügbarkeitscheck ausgeblendet für alle Dienste

# Beispiel Einbindung

...
    
<aw-buendelungskomponente 
    hide-services=""
    hide-login-services=""
    language-selection-services="at-ausbildung,at-erwerbstaetigkeit,at-fachkraefteverfahren,at-familiennachzug,at-germany-for-ukraine,at-nebenbestimmungen,at-niederlassungserlaubnis,aw-aufenthaltskarte,aw-beschaeftigungserlaubnis"
    hide-page-nav-services=""
    add-services="aw-aufenthaltskarte"
    page-nav-position-services="at-ausbildung:right"
    plz-check-services="at-ausbildung,at-erwerbstaetigkeit"
    ags="..."
    language-selection
    excluded-languages="ru, tr"
></aw-buendelungskomponente>

...

# Sicherheit

Sie können folgende Header auf der Website verwenden, in die Sie Webkomponenten einbetten. Ersetzen Sie digitale-verwaltung-as-a-service.de durch Ihren tatsächlichen Domainnamen.

Name	Wert
`Referrer-Policy`	`strict-origin-when-cross-origin`
`X-Content-Type-Options`	`nosniff`
`X-Frame-Options`	`sameorigin`
`X-XSS-Protection`	`1; mode=block`
`Content-Security-Policy`	default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval' digitale-verwaltung-as-a-service.de api.pre-service-digitale-verwaltung.de api.service-digitale-verwaltung.de; style-src 'self' 'unsafe-inline' digitale-verwaltung-as-a-service.de api.pre-service-digitale-verwaltung.de api.service-digitale-verwaltung.de; img-src 'self' blob: digitale-verwaltung-as-a-service.de data: digitale-verwaltung-as-a-service.de api.pre-service-digitale-verwaltung.de api.service-digitale-verwaltung.de; form-action *; connect-src 'self' blob: digitale-verwaltung-as-a-service.de api.pre-service-digitale-verwaltung.de api.service-digitale-verwaltung.de; upgrade-insecure-requests; block-all-mixed-content
`Feature-Policy`	`accelerometer 'none'; battery 'none'; display-capture 'none'; geolocation 'none'; gyroscope 'none'; microphone 'none'; web-share 'none'; payment 'self'`
`Permissions-Policy`	`accelerometer 'none'; battery 'none'; display-capture 'none'; geolocation 'none'; gyroscope 'none'; microphone 'none'; web-share 'none'; payment 'self'`

Jeder Dienst kann zusätzliche Anforderungen an die Security-Header haben, die über dieses empfohlene Minimum hinausgehen. Es ist anzumerken, dass die Anforderungen jedes erforderlichen Dienstes die Sicherheitsanforderungen stark verändern können.

# Kontakt

Bei Fragen, Problemen oder Rückmeldungen wenden Sie sich bitte an den folgenden Kontakt:

Für das Themenfeld Ein- und Auswanderung: rollout-dv@akdb.de
Für das OZG-Umsetzungsprojekt waffenrechtliche Erlaubnisse: eWaffeService@akdb.de
Für das OZG-Umsetzungsprojekt Fahrtenschreiber: rollout-fs@akdb.de