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 26 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'
});
</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 contatto; 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 contatto 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.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: WooCommerce, PrestaShop, AcyMailing, Convert Forms e Community Builder. A lista.