SW Shopware 6 Shopware Principiante

DfAddressAutocomplete — Completamento automatico indirizzi per Shopware 6

Installare, configurare ed estendere il completamento automatico degli indirizzi multi-provider (BAN, Google Places) su Shopware 6.6/6.7.

Aggiornato Versione del modulo 1.0.0

Panoramica

DfAddressAutocomplete aggiunge una ricerca istantanea degli indirizzi ai moduli indirizzo di Shopware 6: checkout, rubrica dell’account cliente e registrazione. Il cliente digita l’inizio del suo indirizzo, sceglie un suggerimento e tutti i campi si riempiono automaticamente: via, complemento, codice postale, città e paese.

Due provider sono inclusi: BAN (Base Adresse Nationale, gratuito, Francia) e Google Places (New) (a pagamento, mondiale). L’architettura è estensibile: qualsiasi API di indirizzi può essere collegata tramite un’interfaccia PHP.

Requisiti

  • Shopware 6.6 o 6.7
  • PHP 8.2 o superiore
  • Per Google Places: una chiave API Google Cloud con la Places API (New) attivata (non la vecchia Places API)

Installazione

  1. Caricate lo ZIP in custom/plugins/ o tramite l’amministrazione Shopware (Estensioni → Le mie estensioni → Carica estensione).
  2. Eseguite i seguenti comandi:
bin/console plugin:refresh
bin/console plugin:install --activate DfAddressAutocomplete
bin/console cache:clear
  1. Compilate lo storefront affinché JavaScript e CSS vengano integrati:
./bin/build-storefront.sh

Negli ambienti senza script di build, usate bin/console theme:compile dopo aver compilato gli asset una prima volta.

Configurazione

Andate in Estensioni → Le mie estensioni → DfAddressAutocomplete → Configura. Tutte le impostazioni supportano lo scope per sales channel.

Provider

  • Provider di completamento automatico: BAN (predefinito) o Google Places.
  • Chiave API Google Places: necessaria solo se Google è selezionato. La chiave resta lato server e non viene mai inviata al browser.
  • Restrizione paesi: codici ISO 3166-1 alpha-2 separati da virgola (es. FR,BE,LU,CH). Vuoto = nessuna restrizione. Si applica solo a Google (BAN è per natura limitato alla Francia).

Pagine di attivazione

Tre interruttori indipendenti: checkout, account cliente (rubrica) e registrazione. Ognuno si attiva o disattiva separatamente.

Comportamento

  • Caratteri minimi (predefinito 3): nessuna ricerca sotto questa soglia.
  • Ritardo debounce (predefinito 250 ms): tempo di attesa dopo l’ultimo tasto prima di interrogare l’API.
  • Suggerimenti massimi (predefinito 5).
  • Cache server (attivata di default): 5 minuti sulle ricerche, 15 minuti sui dettagli. Riduce la fatturazione Google e la latenza.

Configurare Google Places

  1. Nella Google Cloud Console, create o selezionate un progetto.
  2. Attivate la Places API (New) — attenzione, non la vecchia «Places API».
  3. Create una chiave API e limitatela per indirizzo IP del server (quello del vostro hosting Shopware). Non limitatela per referrer HTTP: il traffico è server-to-server.
  4. Incollate la chiave nella configurazione del plugin.

La Places API (New) è fatturata a consumo. La cache server del plugin e il debounce limitano il numero di chiamate, ma monitorate il consumo nella console Google.

Funzionamento lato cliente

Un campo di ricerca appare sopra il modulo indirizzo standard. La navigazione da tastiera è completa: frecce su/giù per scorrere i suggerimenti, Invio per selezionare, Esc per chiudere. Alla selezione, i campi standard di Shopware vengono riempiti e il paese viene selezionato automaticamente nel menu a tendina.

Aggiungere un provider personalizzato

Implementate l’interfaccia AutocompleteProviderInterface (namespace DataFirefly\DfAddressAutocomplete\Provider) nel vostro plugin:

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

    public function search(string $query, int $limit, string $salesChannelId, array $countryCodes = []): array
    {
        // Interrogate la vostra API e restituite un array di AddressSuggestion
    }

    public function details(string $id, string $salesChannelId): ?AddressDetails
    {
        // Risolvete l'id in un AddressDetails completo
    }
}

Poi taggate il servizio nel vostro services.xml (id del servizio = classe completa del vostro provider):

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

Ogni suggerimento porta il prefisso del suo provider nel suo id (es. mapbox:abc123): le chiamate di dettaglio vengono instradate automaticamente.

Temi personalizzati

Il plugin estende il componente standard component_address_form e rileva i campi dal loro nome (*AddressStreet, *AddressZipcode, *AddressCity, *AddressCountry). Se il vostro tema rinomina questi campi, sovrascrivete il metodo _cacheTargetFields del plugin JavaScript per indicargli i nuovi nomi.

Risoluzione dei problemi

  • Il campo di ricerca non appare: verificate che lo storefront sia stato ricompilato dopo l’attivazione e che la pagina interessata sia attivata nella configurazione.
  • Nessun suggerimento con Google: verificate che la Places API (New) sia attivata sul progetto, che la chiave sia valida e che la sua restrizione IP corrisponda all’IP del vostro server.
  • Il paese non viene selezionato: il plugin confronta il codice ISO con l’attributo data-country-iso delle opzioni del menu a tendina, poi con il loro testo visibile. Se il vostro tema non espone né l’uno né l’altro, il paese corrente viene mantenuto.

Privacy (GDPR)

Il plugin non memorizza alcun dato personale. Ciò che digita l’utente passa dal vostro server Shopware verso il provider scelto. Con BAN, i dati sono trattati da un servizio pubblico francese (DINUM). Con Google, sono soggetti alle condizioni di Google Cloud: menzionatelo nella vostra informativa sulla privacy se necessario.

Questa pagina ti è stata utile?

Ancora bloccato? Contatta l'assistenza