# 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
undags-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-beschaeftigungserlaubnis | ewaffe-gelbe-wbk-sportschuetze-erteilung | |
aw-einbuergerung | ewaffe-gruene-wbk-person-erteilung | |
aw-buendelungskomponente | 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 | |
zw-online-auskunft-fahrzeugbriefe |
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 |
Finanzwesen |
---|
fin-wasserzaehlerablesung |
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 AGS09000001
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 beiat-germany-for-ukraine
undat-erwerbstaetigkeit
(Default: true) unterstützt (s. auch Kapitel Attribute).- Wenn
hide-page-nav="true"
, dann istpage-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ßeraw-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
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 gehaltenbb-red.css
: Die primären Farben des Layouts werden in einem roten Ton gehaltentf-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 demhtml
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