Live Demo: Teste alle Plugins für OXID eShop und Shopware von Markus Michalski live — ohne Installation, ohne Risiko. demo.markus-michalski.net
¶ Inhaltsverzeichnis
- Überblick
- Features
- Anforderungen
- Installation
- Update
- Konfiguration
- Unterstützte Formulare
- Praxis-Beispiele
- Fehlerbehebung
- Technische Details
- FAQ
- Lizenz und Support
¶ Überblick
Das SmartMaps Address Autocomplete Plugin integriert den SmartMaps Autocomplete Service in Shopware 6. Während Kunden eine Adresse eingeben, werden in Echtzeit passende Adressvorschläge angezeigt. Nach Auswahl eines Vorschlags werden alle Adressfelder automatisch ausgefüllt - Straße, Hausnummer, PLZ, Stadt, Land und Bundesland.
Hinweis: Dieses Plugin wird von Markus Michalski entwickelt und vertrieben. Es besteht keine geschäftliche Verbindung zur YellowMap AG (Betreiberin von SmartMaps). Die YellowMap AG kann für dieses Plugin keinen Support leisten. Bei Fragen zum Plugin wende dich bitte ausschließlich an den Plugin-Entwickler (siehe Support-Sektion).
Weniger Tippfehler, schnellerer Checkout: Durch automatisches Ausfüllen von Adressfeldern werden Eingabefehler reduziert und der Bestellvorgang beschleunigt.
¶ Features
| Feature | Beschreibung |
|---|---|
| Echtzeit-Autovervollständigung | Adressvorschläge während der Eingabe im Straßenfeld |
| Automatische Feldausfüllung | Straße, Hausnummer, PLZ, Stadt, Land und Bundesland |
| Multi-Sales-Channel | Individuelle Konfiguration pro Sales Channel |
| Länderfilter | Einschränkung auf bestimmte Länder (z.B. DE, AT, CH) |
| Bundesland-Erkennung | Automatische Auswahl des Bundeslandes nach Länderwechsel |
| Fehlertoleranz | Plugin bricht bei Fehlern nie die Seite ab |
¶ Anforderungen
| Anforderung | Version | Hinweise |
|---|---|---|
| Shopware | 6.7.x | Ältere Versionen werden nicht unterstützt |
| PHP | >= 8.2 | Readonly Properties, Match Expressions |
| SmartMaps API Key | - | Kostenlos registrieren: SmartMaps Registration |
- Plugin im Shopware Store suchen und Lizenz erwerben
- Im Admin unter Erweiterungen > Meine Erweiterungen installieren
- Plugin aktivieren
- Cache leeren
Hinweis: Die Repository-Zugangsdaten werden nach dem Lizenzkauf bereitgestellt. Private Repositories werden über Packeton verwaltet.
# 1. Private Repository hinzufuegen (einmalig)
composer config repositories.mmd composer https://packeton.markus-michalski.net
# 2. Plugin installieren
composer require mmd/smart-maps-integration
# 3. Plugin aktivieren
bin/console plugin:refresh
bin/console plugin:install --activate MmdSmartMapsIntegration
bin/console cache:clear
¶ Update
composer update mmd/smart-maps-integration
bin/console plugin:update MmdSmartMapsIntegration
bin/console cache:clear
Bei Installation über den Shopware Store: Update direkt über Erweiterungen > Meine Erweiterungen.
¶ Konfiguration
Die Plugin-Konfiguration findest du unter Einstellungen > System > Plugins > SmartMaps Address Autocomplete.
| Einstellung | Typ | Standard | Beschreibung |
|---|---|---|---|
| API Key | Passwort | - | Dein SmartMaps API-Schlüssel. Kostenlos registrieren unter auth.smartmaps.app |
| Aktiviert | Boolean | true |
Autocomplete ein-/ausschalten |
| Länderfilter | Text | Leer | Komma-getrennte ISO-Codes, z.B. DE,AT,CH für DACH-Region. Leer = alle Länder |
Tipp: Jeder Sales Channel kann seine eigene Konfiguration haben. Wähle im Admin oben den gewünschten Sales Channel aus, um individuelle Einstellungen vorzunehmen.
¶ API Key besorgen
- Besuche https://auth.smartmaps.app/Account/Register
- Erstelle einen kostenlosen Account
- Kopiere deinen API Key aus dem Dashboard
- Trage den Key in der Plugin-Konfiguration ein
¶ Unterstützte Formulare
Das Plugin funktioniert automatisch in allen Standard-Adressformularen:
- Checkout - Rechnungsadresse
- Checkout - Lieferadresse
- Kundenregistrierung
- Mein Konto - Adressverwaltung
Kompatibilität: Das Plugin nutzt Standard-Shopware-Selektoren (
input[name$="[street]"], etc.). Custom Themes, die diese Selektoren ändern, benötigen möglicherweise Anpassungen.
¶ Praxis-Beispiele
¶ Beispiel 1: DACH-Region (Deutschland, Österreich, Schweiz)
Konfiguration:
- API Key:
dein-api-key - Aktiviert:
Ja - Länderfilter:
DE,AT,CH
Ergebnis: Nur Adressen aus Deutschland, Österreich und der Schweiz werden vorgeschlagen.
¶ Beispiel 2: Internationaler Shop ohne Einschränkung
Konfiguration:
- API Key:
dein-api-key - Aktiviert:
Ja - Länderfilter: (leer lassen)
Ergebnis: Adressvorschläge aus allen verfügbaren Ländern.
¶ Beispiel 3: Multi-Channel mit unterschiedlichen Regionen
Global-Konfiguration:
- API Key:
dein-api-key - Aktiviert:
Ja - Länderfilter:
DE
Sales Channel "Österreich-Shop":
- Länderfilter:
AT(überschreibt Global)
Ergebnis: Hauptshop zeigt nur deutsche Adressen, der Österreich-Channel nur österreichische.
¶ Fehlerbehebung
¶ Autocomplete funktioniert nicht
Symptom: Keine Vorschläge beim Tippen im Straßenfeld.
Prüfen:
- Plugin aktiviert? (Admin > Erweiterungen)
- API Key korrekt eingetragen?
- Browser-Konsole auf Fehler prüfen (F12)
- SmartMaps CDN erreichbar? (
cdn.smartmaps.cloud)
Lösung:
- API Key prüfen und ggf. neu eingeben
- Cache leeren:
bin/console cache:clear - Browser-Cache leeren (Strg+Shift+R)
¶ Bundesland wird nicht automatisch gesetzt
Symptom: Straße, PLZ und Stadt werden gefüllt, aber das Bundesland-Dropdown bleibt leer.
Prüfen:
- Ist das Bundesland-Feld im Adressformular sichtbar?
- Sind Bundesländer für das gewählte Land in Shopware konfiguriert?
Lösung:
- Unter Einstellungen > Shop > Länder das betreffende Land öffnen und Bundesländer aktivieren
- Das Plugin nutzt eine Retry-Logik (bis zu 10 Versuche), da das Bundesland-Dropdown asynchron geladen wird
¶ CORS-Fehler in der Browser-Konsole
Symptom: Fehler wie Access-Control-Allow-Origin in der Konsole.
Prüfen:
- Domain korrekt bei SmartMaps registriert?
Lösung:
- Im SmartMaps Dashboard die Shop-Domain als erlaubte Origin eintragen
¶ Technische Details
¶ Architektur
¶ Storefront-Flow
¶ Plugin-Struktur
src/
├── MmdSmartMapsIntegration.php # Plugin-Hauptklasse
├── Service/
│ ├── SmartMapsConfigServiceInterface.php
│ └── SmartMapsConfigService.php # Config aus SystemConfig
├── Struct/
│ └── SmartMapsConfig.php # Immutable Value Object
├── Subscriber/
│ └── StorefrontSubscriber.php # Event-Listener
└── Resources/
├── config/
│ ├── config.xml # Admin-Konfiguration
│ └── services.xml # DI-Container
├── views/storefront/
│ ├── base.html.twig # CDN Script/CSS
│ └── component/address/
│ └── address-form.html.twig # Form-Wrapper
└── app/storefront/src/
├── main.js # Plugin-Registry
└── plugin/smartmaps-autocomplete/
└── smartmaps-autocomplete.plugin.js
¶ Feld-Mapping
| SmartMaps Property | Shopware Feld | Beschreibung |
|---|---|---|
street + houseNo |
address[street] |
Straße und Hausnummer kombiniert |
zip |
address[zipcode] |
Postleitzahl |
city |
address[city] |
Stadt |
country |
address[countryId] |
Land (ISO-Code zu Shopware-ID) |
state |
address[countryStateId] |
Bundesland (Name-Matching) |
¶ Sicherheit
- Der API Key wird nicht im JavaScript-Quellcode eingebettet
- Übertragung via
data-smartmaps-apikeyAttribute am Script-Tag - Config-Validierung: API Key muss mindestens 10 Zeichen lang sein (alphanumerisch +
_-) - Fehler im Subscriber werden gefangen - das Plugin bricht nie die Storefront ab
¶ FAQ
¶ Allgemein
Was ist SmartMaps?
SmartMaps ist ein Geocoding- und Adress-Autocomplete-Service der YellowMap AG. Mehr Infos unter smartmaps.net.
Ist der SmartMaps API Key kostenlos?
Ja, du kannst dich kostenlos registrieren unter auth.smartmaps.app/Account/Register. Je nach Nutzungsumfang können Kosten anfallen - prüfe die aktuellen Tarife bei SmartMaps.
Wer entwickelt dieses Plugin?
Dieses Plugin wird von Markus Michalski entwickelt und vertrieben. Es besteht keine geschäftliche Verbindung zur YellowMap AG. Die YellowMap AG leistet keinen Support für dieses Plugin.
¶ Konfiguration
Kann ich verschiedene API Keys pro Sales Channel verwenden?
Ja. Wähle im Admin den gewünschten Sales Channel aus und trage dort einen eigenen API Key ein.
Welche Ländercodes kann ich im Filter verwenden?
Standard ISO 3166-1 Alpha-2 Codes, z.B. DE (Deutschland), AT (Österreich), CH (Schweiz), NL (Niederlande), FR (Frankreich).
¶ Kompatibilität
Funktioniert das Plugin mit Custom Themes?
Ja, solange das Theme die Standard-Shopware-Adressformular-Selektoren beibehält. Bei stark angepassten Themes kann eine Anpassung nötig sein.
Welche Shopware-Versionen werden unterstützt?
Aktuell wird Shopware 6.7.x unterstützt. Ältere Versionen (6.5, 6.6) sind nicht kompatibel.
¶ Lizenz und Support
Lizenz: Proprietär (Einzelinstallations-Lizenz)
Support:
- E-Mail: support@markus-michalski.net
- Dokumentation: Diese Wiki-Seite
Wichtig: Die YellowMap AG (Betreiberin von SmartMaps) kann für dieses Plugin keinen Support leisten. Bitte wende dich ausschließlich an den Plugin-Entwickler.
¶ Changelog
Änderungshistorie siehe CHANGELOG.md im Repository.