Indicativo Telefónico Internacional (dfphoneintl)

Apresentação

O DataFirefly International Phone Input (dfphoneintl) acrescenta um seletor de indicativo telefónico com bandeira aos campos Telefone e Telemóvel do PrestaShop, e uniformiza os números no formato internacional E.164 na base de dados. O módulo atua a dois níveis: do lado do navegador para a experiência do utilizador, e do lado do servidor para garantir que qualquer inserção ou atualização de morada, incluindo via API, back-office ou importação, produz um número normalizado.

Pré-requisitos

• PrestaShop 8.0.0 a 9.99.99
• PHP 7.4 no mínimo (8.1+ recomendado)
• Nenhuma dependência externa: o módulo não incorpora nenhuma biblioteca de terceiros

Instalação

1. Descarregue o arquivo dfphoneintl-1.0.0.zip a partir da sua conta de cliente DataFirefly.
2. No back-office PrestaShop, vá a Módulos → Gestor de módulos → Instalar um módulo.
3. Arraste e largue o ficheiro ZIP e clique em Instalar.
4. O módulo regista-se automaticamente nos hooks necessários. Não é criada nenhuma tabela SQL: o módulo lê os indicativos a partir da tabela nativa ps_country.

Configuração

Vá a Módulos → Gestor de módulos → DataFirefly International Phone Input → Configurar. Estão disponíveis três definições:

• Ativar no campo « Telefone »: ativa ou desativa o seletor e a normalização no campo phone.
• Ativar no campo « Telemóvel »: idem para o campo phone_mobile.
• Países preferidos: lista de códigos ISO2 separados por vírgulas. Estes países são fixados no topo da lista pendente. Valor por defeito: fr,be,lu,ch,gb,us,de,es,it,nl; numa loja portuguesa, coloque por exemplo pt,es,br,fr,gb,de,ch,lu.

Funcionamento do lado do cliente

Páginas em causa

O seletor aparece em todas as páginas do front-office onde figuram campos de telefone: criação de conta, inscrição, gestão das moradas, funil de encomenda (5 etapas e one-page checkout), página de identidade, página de contacto e acompanhamento de encomenda de convidado.

Sincronização com o país

Quando o cliente muda o país no formulário de morada, o indicativo do seletor atualiza-se automaticamente. Selecionar Espanha passa o indicativo a +34, Brasil a +55, etc. Esta sincronização funciona também nos recarregamentos AJAX do checkout nativo: o módulo escuta os eventos PrestaShop updatedAddressForm, updatedAddress, updateCustomerAddressForm e changedCheckoutStep, com um MutationObserver com debounce como rede de segurança para os temas fortemente personalizados.

Deteção nas moradas existentes

Se o campo já contiver um número em formato internacional (edição de uma morada existente), o módulo deteta o país correspondente por correspondência do indicativo mais longo (longest dial-code match): +1242... é reconhecido como Bahamas e não como Estados Unidos.

Funcionamento do lado do servidor

A normalização no servidor está ligada aos hooks actionObjectAddressAddBefore e actionObjectAddressUpdateBefore. Antes de cada INSERT ou UPDATE na tabela ps_address, os campos phone e phone_mobile passam pela classe DfPhoneFormatter. Isto cobre todos os canais de escrita: formulários do front-office, back-office, webservice, importações CSV e módulos de terceiros que manipulam a classe Address.

Regras de normalização

Para uma morada associada a um país de indicativo +351:

• Número que começa por + → conservado tal como está, só os separadores são retirados: +351 912 345 678 torna-se +351912345678.
• Número que começa por 00 → o 00 é substituído por +: 00351912345678 torna-se +351912345678.
• Número que começa por 0 (prefixo de rede, nos países que o usam como França ou Espanha) → o 0 é retirado e o indicativo é prefixado: 0633547864 com indicativo +33 torna-se +33633547864.
• Número que já começa pelo indicativo sem + → o + é simplesmente acrescentado: 351912345678 torna-se +351912345678.
• Outro número composto apenas por algarismos → o indicativo é prefixado: 912345678 torna-se +351912345678.

Compatibilidade de temas e checkout

• Tema Classic PS 8 (Bootstrap 4) e tema PS 9 (Bootstrap 5) suportados nativamente.
• Checkout em 5 etapas e one-page checkout (OPC) suportados.
• As bandeiras são emojis Unicode (Regional Indicator Symbols): sem sprite nem CDN, renderização nativa por todos os navegadores e SO modernos.
• Multiloja: parâmetros globais, lista de países filtrada por loja.
• Multilingue: nomes dos países apresentados no idioma do visitante.

Resolução de problemas

O seletor não aparece

• Verifique que o campo está ativado na configuração do módulo.
• Verifique que o seu tema usa os nomes de campos padrão phone / phone_mobile (ou address[phone] / address[phone_mobile]). Para um campo renomeado por um tema personalizado, contacte o suporte.
• Limpe a cache do PrestaShop (Parâmetros avançados → Desempenho) depois da instalação.

As bandeiras aparecem como letras (PT, ES…)

Comportamento esperado em alguns sistemas Windows antigos que não renderizam os emojis de bandeiras. O indicativo +351 continua apresentado e o módulo continua plenamente funcional.

O indicativo não segue a mudança de país

Num tema muito personalizado cujo select de país não usa o nome id_country, a sincronização automática não consegue ligar-se. O MutationObserver reinicializa mesmo assim o widget, e o cliente pode escolher manualmente o seu indicativo. Contacte o suporte com o URL da sua loja para uma adaptação.

Desinstalação

A desinstalação elimina as três chaves de configuração do módulo. Os números já normalizados na base de dados ficam em formato internacional: nenhum dado de cliente é modificado nem eliminado.

Suporte

Suporte por e-mail incluído, atualizações incluídas durante 12 meses. Garantia de satisfação ou reembolso de 14 dias em todos os módulos DataFirefly.