Live Demo: Try all OXID eShop and Shopware plugins by Markus Michalski live — no installation, no risk. demo.markus-michalski.net
¶ Table of Contents
- Overview
- Features
- Requirements
- Installation
- Update
- Configuration
- Supported Forms
- Practical Examples
- Troubleshooting
- Technical Details
- FAQ
- License and Support
¶ Overview
The SmartMaps Address Autocomplete plugin integrates the SmartMaps Autocomplete Service into Shopware 6. As customers type an address, real-time suggestions are displayed. After selecting a suggestion, all address fields are automatically filled in - street, house number, zip code, city, country, and state.
Note: This plugin is developed and distributed by Markus Michalski. There is no business affiliation with YellowMap AG (the operator of SmartMaps). YellowMap AG cannot provide support for this plugin. For plugin-related questions, please contact the plugin developer exclusively (see Support section).
Fewer typos, faster checkout: By automatically filling address fields, input errors are reduced and the ordering process is accelerated.
¶ Features
| Feature | Description |
|---|---|
| Real-time autocomplete | Address suggestions while typing in the street field |
| Automatic field population | Street, house number, zip code, city, country, and state |
| Multi-sales-channel | Individual configuration per sales channel |
| Country filter | Restrict suggestions to specific countries (e.g., DE, AT, CH) |
| State detection | Automatic state selection after country change |
| Fault tolerance | Plugin never breaks the page on errors |
¶ Requirements
| Requirement | Version | Notes |
|---|---|---|
| Shopware | 6.7.x | Older versions are not supported |
| PHP | >= 8.2 | Readonly properties, match expressions |
| SmartMaps API Key | - | Free registration: SmartMaps Registration |
- Find the plugin in the Shopware Store and purchase a license
- Install via Admin under Extensions > My Extensions
- Activate the plugin
- Clear cache
Note: Repository credentials are provided after license purchase. Private repositories are managed via Packeton.
# 1. Add private repository (one-time)
composer config repositories.mmd composer https://packeton.markus-michalski.net
# 2. Install plugin
composer require mmd/smart-maps-integration
# 3. Activate plugin
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
For Shopware Store installations: Update directly via Extensions > My Extensions.
¶ Configuration
Plugin settings are located under Settings > System > Plugins > SmartMaps Address Autocomplete.
| Setting | Type | Default | Description |
|---|---|---|---|
| API Key | Password | - | Your SmartMaps API key. Register for free at auth.smartmaps.app |
| Enabled | Boolean | true |
Enable/disable autocomplete |
| Country Filter | Text | Empty | Comma-separated ISO codes, e.g., DE,AT,CH for DACH region. Empty = all countries |
Tip: Each sales channel can have its own configuration. Select the desired sales channel in the admin header to set individual values.
¶ Getting an API Key
- Visit https://auth.smartmaps.app/Account/Register
- Create a free account
- Copy your API key from the dashboard
- Enter the key in the plugin configuration
¶ Supported Forms
The plugin works automatically in all standard address forms:
- Checkout - Billing address
- Checkout - Shipping address
- Customer registration
- My Account - Address management
Compatibility: The plugin uses standard Shopware selectors (
input[name$="[street]"], etc.). Custom themes that modify these selectors may require adjustments.
¶ Practical Examples
¶ Example 1: DACH Region (Germany, Austria, Switzerland)
Configuration:
- API Key:
your-api-key - Enabled:
Yes - Country Filter:
DE,AT,CH
Result: Only addresses from Germany, Austria, and Switzerland are suggested.
¶ Example 2: International Shop Without Restrictions
Configuration:
- API Key:
your-api-key - Enabled:
Yes - Country Filter: (leave empty)
Result: Address suggestions from all available countries.
¶ Example 3: Multi-Channel with Different Regions
Global Configuration:
- API Key:
your-api-key - Enabled:
Yes - Country Filter:
DE
Sales Channel "Austria Shop":
- Country Filter:
AT(overrides global)
Result: Main shop shows only German addresses, the Austria channel only Austrian ones.
¶ Troubleshooting
¶ Autocomplete Not Working
Symptom: No suggestions when typing in the street field.
Check:
- Plugin activated? (Admin > Extensions)
- API key entered correctly?
- Check browser console for errors (F12)
- SmartMaps CDN reachable? (
cdn.smartmaps.cloud)
Solution:
- Verify API key and re-enter if necessary
- Clear cache:
bin/console cache:clear - Clear browser cache (Ctrl+Shift+R)
¶ State Not Automatically Selected
Symptom: Street, zip code, and city are filled, but the state dropdown remains empty.
Check:
- Is the state field visible in the address form?
- Are states configured for the selected country in Shopware?
Solution:
- Under Settings > Shop > Countries, open the relevant country and enable states
- The plugin uses retry logic (up to 10 attempts) since the state dropdown loads asynchronously
¶ CORS Errors in Browser Console
Symptom: Errors like Access-Control-Allow-Origin in the console.
Check:
- Domain correctly registered with SmartMaps?
Solution:
- Add your shop domain as an allowed origin in the SmartMaps dashboard
¶ Technical Details
¶ Architecture
¶ Storefront Flow
¶ Plugin Structure
src/
├── MmdSmartMapsIntegration.php # Main plugin class
├── Service/
│ ├── SmartMapsConfigServiceInterface.php
│ └── SmartMapsConfigService.php # Config from SystemConfig
├── Struct/
│ └── SmartMapsConfig.php # Immutable value object
├── Subscriber/
│ └── StorefrontSubscriber.php # Event listener
└── Resources/
├── config/
│ ├── config.xml # Admin configuration
│ └── 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
¶ Field Mapping
| SmartMaps Property | Shopware Field | Description |
|---|---|---|
street + houseNo |
address[street] |
Street and house number combined |
zip |
address[zipcode] |
Zip code |
city |
address[city] |
City |
country |
address[countryId] |
Country (ISO code to Shopware ID) |
state |
address[countryStateId] |
State (name matching) |
¶ Security
- The API key is not embedded in JavaScript source code
- Transmitted via
data-smartmaps-apikeyattribute on the script tag - Config validation: API key must be at least 10 characters (alphanumeric +
_-) - Errors in the subscriber are caught - the plugin never breaks the storefront
¶ FAQ
¶ General
What is SmartMaps?
SmartMaps is a geocoding and address autocomplete service by YellowMap AG. More info at smartmaps.net.
Is the SmartMaps API key free?
Yes, you can register for free at auth.smartmaps.app/Account/Register. Depending on usage volume, costs may apply - check current pricing at SmartMaps.
Who develops this plugin?
This plugin is developed and distributed by Markus Michalski. There is no business affiliation with YellowMap AG. YellowMap AG does not provide support for this plugin.
¶ Configuration
Can I use different API keys per sales channel?
Yes. Select the desired sales channel in the admin and enter a separate API key there.
Which country codes can I use in the filter?
Standard ISO 3166-1 Alpha-2 codes, e.g., DE (Germany), AT (Austria), CH (Switzerland), NL (Netherlands), FR (France).
¶ Compatibility
Does the plugin work with custom themes?
Yes, as long as the theme keeps the standard Shopware address form selectors. Heavily customized themes may require adjustments.
Which Shopware versions are supported?
Currently Shopware 6.7.x is supported. Older versions (6.5, 6.6) are not compatible.
¶ License and Support
License: Proprietary (single-installation license)
Support:
- Email: support@markus-michalski.net
- Documentation: This wiki page
Important: YellowMap AG (the operator of SmartMaps) cannot provide support for this plugin. Please contact the plugin developer exclusively.
¶ Changelog
For change history, see CHANGELOG.md in the repository.