SW Shopware 6 Shopware Beginner

DfAddressAutocomplete: adresaanvulling voor Shopware 6

De adresaanvulling met meerdere providers (BAN, Google Places) installeren, configureren en uitbreiden op Shopware 6.6/6.7.

Bijgewerkt Moduleversie 1.0.0

Overzicht

DfAddressAutocomplete voegt een directe adreszoekfunctie toe aan de adresformulieren van Shopware 6: checkout, adresboek van het klantaccount en registratie. De klant typt het begin van zijn adres, kiest een suggestie en alle velden worden automatisch ingevuld: straat, toevoeging, postcode, plaats en land.

Er worden twee providers meegeleverd: BAN (Base Adresse Nationale, gratis, Frankrijk) en Google Places (New) (betaald, wereldwijd). De architectuur is uitbreidbaar: elke adres-API kan via een PHP-interface worden aangesloten.

Vereisten

  • Shopware 6.6 of 6.7
  • PHP 8.2 minimaal
  • Voor Google Places: een Google Cloud API-sleutel met de Places API (New) geactiveerd (niet de oude Places API)

Installatie

  1. Upload de ZIP naar custom/plugins/ of via de Shopware-admin (Extensies → Mijn extensies → Extensie uploaden).
  2. Voer de volgende commando’s uit:
bin/console plugin:refresh
bin/console plugin:install --activate DfAddressAutocomplete
bin/console cache:clear
  1. Compileer de storefront zodat de JavaScript en de CSS worden meegenomen:
./bin/build-storefront.sh

Gebruik op omgevingen zonder buildscript bin/console theme:compile nadat u de assets een eerste keer hebt gecompileerd.

Configuratie

Ga naar Extensies → Mijn extensies → DfAddressAutocomplete → Configureren. Alle instellingen zijn per sales channel in te stellen.

Provider

  • Provider voor adresaanvulling: BAN (standaard) of Google Places.
  • Google Places API-sleutel: alleen nodig wanneer Google is geselecteerd. De sleutel blijft aan serverzijde en wordt nooit naar de browser gestuurd.
  • Landbeperking: ISO 3166-1 alpha-2 codes gescheiden door komma’s (bijvoorbeeld NL,BE,LU,DE). Leeg = geen beperking. De beperking geldt alleen voor Google (BAN is van nature uitsluitend Frankrijk).

Pagina’s waarop de functie actief is

Drie onafhankelijke schakelaars: checkout, klantaccount (adresboek) en registratie. Elke schakelaar is apart in of uit te schakelen.

Gedrag

  • Minimaal aantal tekens (standaard 3): onder deze drempel wordt niet gezocht.
  • Debounce-vertraging (standaard 250 ms): wachttijd na de laatste toetsaanslag voordat de API wordt bevraagd.
  • Maximum aantal suggesties (standaard 5).
  • Servercache (standaard ingeschakeld): 5 minuten op de zoekopdrachten, 15 minuten op de details. Beperkt de facturatie bij Google en de latentie.

Google Places instellen

  1. Maak of selecteer in de Google Cloud Console een project.
  2. Activeer de Places API (New), let op: niet de oude “Places API”.
  3. Maak een API-sleutel aan en beperk hem op het IP-adres van de server (dat van uw Shopware-hosting). Beperk hem niet op HTTP-referrer: het verkeer verloopt van server naar server.
  4. Plak de sleutel in de configuratie van de plugin.

De Places API (New) wordt per gebruik gefactureerd. De servercache van de plugin en de debounce beperken het aantal aanroepen, maar houd uw verbruik in de Google-console in de gaten.

Werking aan klantzijde

Boven het standaard adresformulier verschijnt een zoekveld. De toetsenbordnavigatie is volledig: pijltjes omhoog en omlaag om door de suggesties te lopen, Enter om te selecteren, Escape om te sluiten. Bij selectie worden de standaardvelden van Shopware ingevuld en wordt het land automatisch in de keuzelijst geselecteerd.

Een eigen provider toevoegen

Implementeer de interface AutocompleteProviderInterface (namespace DataFirefly\DfAddressAutocomplete\Provider) in uw eigen plugin:

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

    public function search(string $query, int $limit, string $salesChannelId, array $countryCodes = []): array
    {
        // Bevraag uw API en geef een array van AddressSuggestion terug
    }

    public function details(string $id, string $salesChannelId): ?AddressDetails
    {
        // Zet de id om in een volledige AddressDetails
    }
}

Tag daarna de service in uw services.xml (service-id = de volledige klasse van uw provider):

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

Elke suggestie draagt het voorvoegsel van haar provider in haar id (bijvoorbeeld mapbox:abc123): het routeren van de detailaanroepen gaat automatisch.

Aangepaste thema’s

De plugin breidt het standaardcomponent component_address_form uit en herkent de velden aan hun naam (*AddressStreet, *AddressZipcode, *AddressCity, *AddressCountry). Als uw thema deze velden hernoemt, overschrijf dan de methode _cacheTargetFields van de JavaScript-plugin om de nieuwe namen door te geven.

Probleemoplossing

  • Het zoekveld verschijnt niet: controleer of de storefront na de activering daadwerkelijk opnieuw is gecompileerd en of de betreffende pagina in de configuratie geactiveerd is.
  • Geen suggesties met Google: controleer of de Places API (New) op het project geactiveerd is, of de sleutel geldig is en of de IP-beperking overeenkomt met het IP van uw server.
  • Het land wordt niet geselecteerd: de plugin vergelijkt de ISO-code met het attribuut data-country-iso van de opties in de keuzelijst, en daarna met de zichtbare tekst ervan. Als uw thema geen van beide beschikbaar stelt, blijft het huidige land staan.

Privacy (AVG)

De plugin slaat geen persoonsgegevens op. De invoer van de gebruiker gaat via uw Shopware-server naar de gekozen provider. Bij BAN worden de gegevens verwerkt door een Franse overheidsdienst (DINUM). Bij Google gelden de voorwaarden van Google Cloud, vermeld dit zo nodig in uw privacyverklaring.

Was deze pagina nuttig?

Loopt u nog vast? Neem contact op met support