# DfAddressAutocomplete — Adress-Autovervollständigung für Shopware 6

> Überblick DfAddressAutocomplete fügt den Adressformularen von Shopware 6 eine Sofortsuche hinzu: im Checkout, im Adressbuch des Kundenkontos und bei der Registrierung. Der Kunde tippt den Anfang seiner Adresse, wählt einen…

- Seite: <https://www.datafirefly.com/de/documentation/dfaddressautocomplete-shopware/>
- Sprache: de
- Aktualisiert am: 2026-07-01
- Weitere Sprachen: [fr](https://www.datafirefly.com/documentation/dfaddressautocomplete-shopware/index.md), [en](https://www.datafirefly.com/en/documentation/dfaddressautocomplete-shopware/index.md), [es](https://www.datafirefly.com/es/documentation/dfaddressautocomplete-shopware/index.md), [it](https://www.datafirefly.com/it/documentation/dfaddressautocomplete-shopware/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfaddressautocomplete-shopware/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfaddressautocomplete-shopware/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfaddressautocomplete-shopware/index.md)
- Index: <https://www.datafirefly.com/de/documentation/llms.txt>

## Überblick

DfAddressAutocomplete fügt den Adressformularen von Shopware 6 eine Sofortsuche hinzu: im Checkout, im Adressbuch des Kundenkontos und bei der Registrierung. Der Kunde tippt den Anfang seiner Adresse, wählt einen Vorschlag und alle Felder füllen sich automatisch — Straße, Zusatz, Postleitzahl, Stadt und Land.

Zwei Anbieter sind enthalten: **BAN** (Base Adresse Nationale, kostenlos, Frankreich) und **Google Places (New)** (kostenpflichtig, weltweit). Die Architektur ist erweiterbar: Jede Adress-API kann über ein PHP-Interface angebunden werden.

## Voraussetzungen

- Shopware 6.6 oder 6.7
- PHP 8.2 oder höher
- Für Google Places: ein Google-Cloud-API-Schlüssel mit aktivierter **Places API (New)** (nicht die alte Places API)

## Installation

1. Laden Sie das ZIP in `custom/plugins/` hoch oder über die Shopware-Administration (Erweiterungen → Meine Erweiterungen → Erweiterung hochladen).
2. Führen Sie folgende Befehle aus:

```
bin/console plugin:refresh
bin/console plugin:install --activate DfAddressAutocomplete
bin/console cache:clear
```

1. Kompilieren Sie die Storefront, damit JavaScript und CSS eingebunden werden:

```
./bin/build-storefront.sh
```

In Umgebungen ohne Build-Skript nutzen Sie `bin/console theme:compile`, nachdem die Assets einmal kompiliert wurden.

## Konfiguration

Gehen Sie zu **Erweiterungen → Meine Erweiterungen → DfAddressAutocomplete → Konfigurieren**. Alle Einstellungen sind pro Sales Channel scopebar.

### Anbieter

- **Autovervollständigungsanbieter**: BAN (Standard) oder Google Places.
- **Google Places API-Schlüssel**: nur erforderlich, wenn Google ausgewählt ist. Der Schlüssel bleibt serverseitig und wird nie an den Browser gesendet.
- **Länderbeschränkung**: kommagetrennte ISO-3166-1-alpha-2-Codes (z. B. `FR,BE,LU,CH`). Leer = keine Einschränkung. Gilt nur für Google (BAN ist naturgemäß auf Frankreich beschränkt).

### Aktivierungsseiten

Drei unabhängige Schalter: **Checkout**, **Kundenkonto** (Adressbuch) und **Registrierung**. Jeder lässt sich einzeln aktivieren oder deaktivieren.

### Verhalten

- **Mindestzeichen** (Standard 3): keine Suche unterhalb dieser Schwelle.
- **Entprell-Verzögerung** (Standard 250 ms): Wartezeit nach dem letzten Tastendruck, bevor die API abgefragt wird.
- **Maximale Vorschläge** (Standard 5).
- **Serverseitiger Cache** (standardmäßig aktiviert): 5 Minuten bei Suchen, 15 Minuten bei Details. Senkt Google-Kosten und Latenz.

## Google Places einrichten

1. Erstellen oder wählen Sie in der [Google Cloud Console](https://console.cloud.google.com/) ein Projekt.
2. Aktivieren Sie die **Places API (New)** — Achtung, nicht die alte „Places API".
3. Erstellen Sie einen API-Schlüssel und beschränken Sie ihn **per Server-IP-Adresse** (die IP Ihres Shopware-Hostings). Beschränken Sie ihn nicht per HTTP-Referrer: Der Traffic läuft Server-zu-Server.
4. Fügen Sie den Schlüssel in die Plugin-Konfiguration ein.

Die Places API (New) wird nutzungsbasiert abgerechnet. Der serverseitige Cache des Plugins und das Debouncing begrenzen die Zahl der Aufrufe, behalten Sie Ihren Verbrauch aber in der Google-Konsole im Blick.

## Funktionsweise im Frontend

Über dem Standard-Adressformular erscheint ein Suchfeld. Die Tastaturnavigation ist vollständig: Pfeiltasten zum Durchblättern der Vorschläge, Enter zum Auswählen, Escape zum Schließen. Bei der Auswahl werden die Shopware-Standardfelder gefüllt und das Land automatisch im Dropdown ausgewählt.

## Einen eigenen Anbieter hinzufügen

Implementieren Sie das Interface `AutocompleteProviderInterface` (Namespace `DataFirefly\DfAddressAutocomplete\Provider`) in Ihrem eigenen Plugin:

```
final class MapboxProvider implements AutocompleteProviderInterface
{
    public function getKey(): string { return 'mapbox'; }

    public function search(string $query, int $limit, string $salesChannelId, array $countryCodes = []): array
    {
        // Fragen Sie Ihre API ab und geben Sie ein Array von AddressSuggestion zurueck
    }

    public function details(string $id, string $salesChannelId): ?AddressDetails
    {
        // Loesen Sie die id in ein vollstaendiges AddressDetails auf
    }
}
```

Taggen Sie anschließend den Service in Ihrer services.xml (Service-ID = vollqualifizierte Klasse Ihres Anbieters):

```
<service id="My\Plugin\MapboxProvider">
    <tag name="df_address_autocomplete.provider"/>
</service>
```

Jeder Vorschlag trägt das Präfix seines Anbieters in seiner ID (z. B. `mapbox:abc123`): Detailaufrufe werden automatisch geroutet.

## Individuelle Themes

Das Plugin erweitert die Standardkomponente `component_address_form` und erkennt Felder anhand ihres Namens (`*AddressStreet`, `*AddressZipcode`, `*AddressCity`, `*AddressCountry`). Falls Ihr Theme diese Felder umbenennt, überschreiben Sie die Methode `_cacheTargetFields` des JavaScript-Plugins mit den neuen Namen.

## Fehlerbehebung

- **Das Suchfeld erscheint nicht**: Stellen Sie sicher, dass die Storefront nach der Aktivierung neu kompiliert wurde und die betroffene Seite in der Konfiguration aktiviert ist.
- **Keine Vorschläge mit Google**: Prüfen Sie, ob die Places API (New) im Projekt aktiviert ist, der Schlüssel gültig ist und die IP-Beschränkung zur IP Ihres Servers passt.
- **Das Land wird nicht ausgewählt**: Das Plugin vergleicht den ISO-Code mit dem Attribut `data-country-iso` der Dropdown-Optionen, dann mit deren sichtbarem Text. Stellt Ihr Theme keines von beiden bereit, bleibt das aktuelle Land erhalten.

## Datenschutz (DSGVO)

Das Plugin speichert keinerlei personenbezogene Daten. Nutzereingaben laufen über Ihren Shopware-Server zum gewählten Anbieter. Bei BAN werden die Daten von einem französischen öffentlichen Dienst (DINUM) verarbeitet. Bei Google unterliegen sie den Google-Cloud-Bedingungen — erwähnen Sie dies gegebenenfalls in Ihrer Datenschutzerklärung.