SW Shopware 6 Shopware Iniciante

DfAddressAutocomplete: preenchimento automático de moradas para Shopware 6

Instalar, configurar e estender o preenchimento automático de moradas multifornecedor (BAN, Google Places) no Shopware 6.6/6.7.

Atualizado Versão do módulo 1.0.0

Apresentação

O DfAddressAutocomplete acrescenta uma pesquisa instantânea de moradas aos formulários de morada do Shopware 6: checkout, livro de moradas da conta de cliente e registo. O cliente escreve o início da morada, seleciona uma sugestão e todos os campos se preenchem automaticamente: rua, complemento, código postal, localidade e país.

Estão incluídos dois fornecedores: BAN (Base Adresse Nationale, gratuita, França) e Google Places (New) (pago, mundial). A arquitetura é extensível: qualquer API de moradas pode ser ligada através de uma interface PHP.

A BAN cobre apenas as moradas francesas. Para uma loja que venda em Portugal, o fornecedor a configurar é o Google Places, com a restrição de país PT.

Pré-requisitos

  • Shopware 6.6 ou 6.7
  • PHP 8.2 no mínimo
  • Para o Google Places: uma chave de API Google Cloud com a Places API (New) ativada (não a antiga Places API)

Instalação

  1. Carregue o ZIP para custom/plugins/ ou pela administração do Shopware (Extensões → As minhas extensões → Carregar uma extensão).
  2. Execute os seguintes comandos:
bin/console plugin:refresh
bin/console plugin:install --activate DfAddressAutocomplete
bin/console cache:clear
  1. Compile o storefront para que o JavaScript e o CSS sejam integrados:
./bin/build-storefront.sh

Nos ambientes sem script de build, use bin/console theme:compile depois de ter compilado os recursos uma primeira vez.

Configuração

Vá a Extensões → As minhas extensões → DfAddressAutocomplete → Configurar. Todas as definições podem ter âmbito por sales channel.

Fornecedor

  • Fornecedor de preenchimento automático: BAN (por predefinição) ou Google Places.
  • Chave de API Google Places: necessária apenas se o Google estiver selecionado. A chave fica do lado do servidor e nunca é enviada ao navegador.
  • Restrição de país: códigos ISO 3166-1 alpha-2 separados por vírgulas (por exemplo PT,ES,FR). Vazio = sem restrição. A restrição só se aplica ao Google (a BAN é, por natureza, apenas França).

Páginas de ativação

Três interruptores independentes: checkout, conta de cliente (livro de moradas) e registo. Cada um ativa-se ou desativa-se em separado.

Comportamento

  • Caracteres mínimos (predefinição 3): nenhuma pesquisa abaixo deste limiar.
  • Atraso antirressalto (predefinição 250 ms): tempo de espera após a última tecla antes de consultar a API.
  • Sugestões máximas (predefinição 5).
  • Cache de servidor (ativa por predefinição): 5 minutos nas pesquisas, 15 minutos nos detalhes. Reduz a faturação da Google e a latência.

Configurar o Google Places

  1. Na Google Cloud Console, crie ou selecione um projeto.
  2. Ative a Places API (New); atenção, não a antiga «Places API».
  3. Crie uma chave de API e restrinja-a por endereço IP de servidor (o do seu alojamento Shopware). Não a restrinja por referrer HTTP: o tráfego é de servidor para servidor.
  4. Cole a chave na configuração da extensão.

A API Places (New) é faturada à utilização. A cache de servidor da extensão e o antirressalto limitam o número de chamadas, mas vigie o seu consumo na consola da Google.

Funcionamento do lado do cliente

Aparece um campo de pesquisa acima do formulário de morada normal. A navegação por teclado é completa: setas para cima e para baixo para percorrer as sugestões, Enter para selecionar, Esc para fechar. Na seleção, os campos normais do Shopware são preenchidos e o país é selecionado automaticamente na lista pendente.

Acrescentar um fornecedor personalizado

Implemente a interface AutocompleteProviderInterface (namespace DataFirefly\DfAddressAutocomplete\Provider) na sua própria extensão:

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

    public function search(string $query, int $limit, string $salesChannelId, array $countryCodes = []): array
    {
        // Consulte a sua API e devolva um array de AddressSuggestion
    }

    public function details(string $id, string $salesChannelId): ?AddressDetails
    {
        // Resolva o id num AddressDetails completo
    }
}

Depois marque o serviço no seu services.xml (id do serviço = classe completa do seu fornecedor):

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

Cada sugestão transporta o prefixo do seu fornecedor no id (por exemplo mapbox:abc123): o encaminhamento das chamadas de detalhe é automático.

Temas personalizados

A extensão estende o componente normal component_address_form e deteta os campos pelo nome (*AddressStreet, *AddressZipcode, *AddressCity, *AddressCountry). Se o seu tema renomear estes campos, sobreponha o método _cacheTargetFields da extensão JavaScript para lhe indicar os novos nomes.

Resolução de problemas

  • O campo de pesquisa não aparece: verifique que o storefront foi mesmo recompilado depois da ativação, e que a página em causa está ativa na configuração.
  • Nenhuma sugestão com o Google: verifique que a Places API (New) está ativada no projeto, que a chave é válida e que a sua restrição de IP corresponde ao IP do seu servidor.
  • O país não fica selecionado: a extensão compara o código ISO com o atributo data-country-iso das opções da lista pendente, e depois com o respetivo texto visível. Se o seu tema não expuser nem um nem outro, o país atual é mantido.

Privacidade (RGPD)

A extensão não guarda qualquer dado pessoal. As introduções do utilizador passam pelo seu servidor Shopware até ao fornecedor escolhido. Com a BAN, os dados são tratados por um serviço público francês (DINUM). Com o Google, ficam sujeitos às condições da Google Cloud; mencione-o na sua política de privacidade se for necessário.

Esta página foi útil?

Ainda com dúvidas? Contacte o suporte