# DfAddressAutocomplete — Completamento automatico indirizzi per Shopware 6

> 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…

- Pagina: <https://www.datafirefly.com/it/documentation/dfaddressautocomplete-shopware/>
- Lingua: it
- Aggiornato il: 2026-07-01
- Altre lingue: [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), [de](https://www.datafirefly.com/de/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)
- Indice: <https://www.datafirefly.com/it/documentation/llms.txt>

## 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](https://console.cloud.google.com/), 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.