DfAddressAutocomplete — Autocompletado de direcciones para Shopware 6

Presentación

DfAddressAutocomplete añade una búsqueda instantánea de direcciones a los formularios de dirección de Shopware 6: checkout, libreta de direcciones de la cuenta de cliente y registro. El cliente escribe el inicio de su dirección, elige una sugerencia y todos los campos se rellenan automáticamente: calle, complemento, código postal, ciudad y país.

Se incluyen dos proveedores: BAN (Base Adresse Nationale, gratuito, Francia) y Google Places (New) (de pago, mundial). La arquitectura es extensible: cualquier API de direcciones puede conectarse mediante una interfaz PHP.

Requisitos

• Shopware 6.6 o 6.7
• PHP 8.2 o superior
• Para Google Places: una clave API de Google Cloud con la Places API (New) activada (no la Places API antigua)

Instalación

1. Suba el ZIP a custom/plugins/ o mediante la administración de Shopware (Extensiones → Mis extensiones → Subir extensión).
2. Ejecute los siguientes comandos:

bin/console plugin:refresh
bin/console plugin:install --activate DfAddressAutocomplete
bin/console cache:clear

3. Compile el storefront para que el JavaScript y el CSS queden integrados:

./bin/build-storefront.sh

Configuración

Vaya a Extensiones → Mis extensiones → DfAddressAutocomplete → Configurar. Todos los ajustes admiten alcance por sales channel.

Proveedor

• Proveedor de autocompletado: BAN (por defecto) o Google Places.
• Clave API de Google Places: solo necesaria si se selecciona Google. La clave permanece en el servidor y nunca se envía al navegador.
• Restricción de países: códigos ISO 3166-1 alpha-2 separados por comas (ej. FR,BE,LU,CH). Vacío = sin restricción. Solo se aplica a Google (BAN es exclusivamente francés por naturaleza).

Páginas de activación

Tres interruptores independientes: checkout, cuenta de cliente (libreta de direcciones) y registro. Cada uno se activa o desactiva por separado.

Comportamiento

• Caracteres mínimos (por defecto 3): ninguna búsqueda por debajo de este umbral.
• Retraso de antirrebote (por defecto 250 ms): tiempo de espera tras la última pulsación antes de consultar la API.
• Sugerencias máximas (por defecto 5).
• Caché de servidor (activada por defecto): 5 minutos en búsquedas, 15 minutos en detalles. Reduce la facturación de Google y la latencia.

Configurar Google Places

1. En la Google Cloud Console, cree o seleccione un proyecto.
2. Active la Places API (New) — cuidado, no la antigua «Places API».
3. Cree una clave API y restrínjala por dirección IP de servidor (la de su alojamiento Shopware). No la restrinja por referente HTTP: el tráfico es de servidor a servidor.
4. Pegue la clave en la configuración del plugin.

Funcionamiento en el lado del cliente

Un campo de búsqueda aparece encima del formulario de dirección estándar. La navegación por teclado es completa: flechas arriba/abajo para recorrer las sugerencias, Intro para seleccionar, Escape para cerrar. Al seleccionar, los campos estándar de Shopware se rellenan y el país se selecciona automáticamente en el desplegable.

Añadir un proveedor personalizado

Implemente la interfaz AutocompleteProviderInterface (namespace DataFirefly\DfAddressAutocomplete\Provider) en su propio plugin:

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

    public function search(string $query, int $limit, string $salesChannelId, array $countryCodes = []): array
    {
        // Consulte su API y devuelva un array de AddressSuggestion
    }

    public function details(string $id, string $salesChannelId): ?AddressDetails
    {
        // Resuelva el id en un AddressDetails completo
    }
}

Después etiquete el servicio en su services.xml (id del servicio = clase completa de su proveedor):

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

Cada sugerencia lleva el prefijo de su proveedor en su id (ej. mapbox:abc123): las llamadas de detalle se enrutan automáticamente.

Temas personalizados

El plugin extiende el componente estándar component_address_form y detecta los campos por su nombre (*AddressStreet, *AddressZipcode, *AddressCity, *AddressCountry). Si su tema renombra estos campos, sobrescriba el método _cacheTargetFields del plugin JavaScript para indicarle los nuevos nombres.

Solución de problemas

• El campo de búsqueda no aparece: compruebe que el storefront se recompiló tras la activación y que la página en cuestión está activada en la configuración.
• Sin sugerencias con Google: compruebe que la Places API (New) está activada en el proyecto, que la clave es válida y que su restricción de IP corresponde a la IP de su servidor.
• El país no se selecciona: el plugin compara el código ISO con el atributo data-country-iso de las opciones del desplegable y después con su texto visible. Si su tema no expone ninguno de los dos, se conserva el país actual.

Privacidad (RGPD)

El plugin no almacena ningún dato personal. Lo que escribe el usuario pasa por su servidor Shopware hacia el proveedor elegido. Con BAN, los datos los trata un servicio público francés (DINUM). Con Google, quedan sujetos a las condiciones de Google Cloud: menciónelo en su política de privacidad si procede.