Integrações · O teu formulário
O autocomplete de moradas no teu formulário, em três ficheiros.
Nenhum plugin, nenhuma plataforma: um ficheiro JavaScript que se liga aos campos que já tens, um proxy pronto para o teu servidor que mantém o token em segurança, três linhas para os ligar. O visitante escreve, a rua completa-se, código postal, cidade e distrito preenchem-se sozinhos; uma morada escrita à mão é verificada quando sai do campo. Sugestões a partir dos registos de 27 países.
O que há no kit
- ra-suggerisci.js·o widget: sem dependências, o mesmo ficheiro dos plugins WooCommerce e PrestaShop; sugere enquanto escreves e, na seleção, distribui a morada verificada pelos campos
- ra-proxy.php·o proxy: mantém o token no servidor, aceita apenas o teu domínio, trava por visitante, reencaminha para a RadarAddress; se o token faltar ou o crédito tiver acabado, responde com uma lista vazia e o formulário continua
- esempio.html·um formulário completo — país, morada, código postal, cidade, distrito — que funciona assim que o token está no proxy: copia-se e adapta-se
- README·as opções do widget, o contrato do proxy para quem não usa PHP, o que consome
Como se faz, em três passos
Cria a conta e o token
A conta é gratuita, não pede cartão e todos os meses inclui uma quota de operações: o token cria-se num clique e os passos estão explicados lá.
Põe o proxy no servidor
Copia ra-proxy.php para o mesmo domínio do formulário e escreve o token na linha indicada (melhor ainda: num ficheiro fora da pasta web, lido a partir daí). Nada mais a configurar.
Liga o widget aos campos
Inclui ra-suggerisci.js na página e indica os seletores dos teus campos: morada, código postal, cidade, distrito e, se existir, o país. O resto faz o widget.
<script src="ra-suggerisci.js"></script>
<script>
RASuggerisci.attacca({
url: '/ra-proxy.php', // o proxy no teu servidor, nunca a API
campi: { indirizzo: '#indirizzo', cap: '#cap', localita: '#citta',
provincia: '#provincia', nazione_iso2: '#nazione' }, // o país é facultativo
lingua: 'pt',
modulo: 'contatti/indirizzo' // opcional: que formulário, para o seu registo
});
</script>
campi aceita qualquer seletor CSS. As opções extra: onSeleziona recebe o registo verificado (morada normalizada, resultado, coordenadas quando existem), scriviCampo para os formulários React e Vue, correggiAlBlur para decidir se também se verificam as moradas escritas à mão, headers para um token CSRF em direção ao proxy. Tudo no README do kit; o contrato da API está na documentação.
Requisitos: qualquer página web e, para o proxy do kit, PHP 8.0 ou posterior com cURL; caso contrário, sessenta linhas na tua linguagem. O widget é publicado com a licença Academic Free License 3.0.
O que acontece no formulário
- Enquanto escreve·depois de duas letras o widget propõe as ruas, com o nome completo e o município; as letras seguintes filtram o que já recebeu, sem chamar o servidor a cada tecla; código postal e cidade já preenchidos estreitam a pesquisa
- Na seleção·a morada verificada entra nos campos na forma correta — rua por extenso, número de porta, código postal certo mesmo nas grandes cidades com código postal zonado, cidade e distrito — e conta-se uma verificação de morada; os números da rua completam-se sem outros custos
- Escrita à mão·quem ignora a lista e escreve tudo por si é verificado quando sai do campo: se a morada é reconhecida, os campos arrumam-se; senão, fica como está. Nada bloqueia o envio
- No estrangeiro·com o país indicado, as sugestões vêm do registo desse país e o visitante escreve como se escreve lá, mesmo tudo num único campo; a atribuição do registo está no fundo da lista
Perguntas frequentes
Porque é preciso um proxy? Não posso chamar a API a partir da página?
O token da API dá acesso ao teu crédito: na página, qualquer um o poderia ler. O widget só fala com um endereço do teu próprio site; aí, um ficheiro de sessenta linhas acrescenta o token e reencaminha. O proxy PHP do kit está pronto: copia-se, escreve-se o token, e está feito.
O meu site não é em PHP.
O proxy é a referência, não uma obrigação: recebe o JSON do browser, acrescenta o cabeçalho Authorization com o token, reencaminha para /api/v1/suggest e devolve a resposta. Reescreve-se em qualquer linguagem em poucos minutos; o README descreve o contrato.
Funciona com React, Vue, Angular?
Sim: o widget liga-se aos campos com qualquer seletor CSS. Os formulários controlados exigem que o valor seja escrito com o setter nativo: a opção scriviCampo serve para isso, e é a que o plugin WooCommerce usa no checkout de blocos.
O que consome?
Escrever é grátis. Conta-se uma verificação de morada quando o visitante seleciona uma morada da lista (ou quando uma morada escrita à mão é verificada ao sair do campo, se deixares ativo correggiAlBlur): uma por morada, não por tecla. Todos os meses as primeiras 50 são gratuitas; a partir daí, os pacotes e as subscrições da página de preços.
E se o crédito acabar, ou a RadarAddress não responder?
O widget cala-se e o formulário funciona como sempre: nenhuma mensagem ao visitante, nenhum envio bloqueado. O proxy devolve uma lista vazia nos casos 401, 402 e em qualquer erro de rede.
Também funciona no estrangeiro?
Para todos os países em serviço: basta um campo com o código ISO do país (uma select com IT, DE, FR… ou um campo oculto) indicado em nazione_iso2. O visitante escreve como se escreve no seu país, mesmo tudo num único campo; o popup mostra a atribuição do registo.
Posso mudar o aspeto do popup?
O widget traz os seus próprios estilos, sem ficheiro CSS: as variáveis --ra-sugg-bg, --ra-sugg-bordo e --ra-sugg-hover na tua página mudam as cores; a classe é .ra-sugg-pop para o resto.
Versões
- 1.1.1 — o widget de hoje: lista de sugestões tão larga como o campo, «snc» proposto só para uma morada italiana, textos nas treze línguas (sem língua indicada, inglês).
- 1.0.0 — primeira versão do kit: widget, proxy PHP com limites e controlo da origem, formulário de exemplo, README.
As outras integrações: AcyMailing, Community Builder, Contact Form 7, Convert Forms, Drupal Webform, Fluent Forms, Formidable Forms, Gravity Forms, Magento, MailPoet, Make, n8n, Ninja Forms, OpenCart, PrestaShop, Shopify, Shopware, The Newsletter Plugin, VirtueMart, WooCommerce, WPForms e Zapier. A lista.