Integrazioni · Il tuo form
L'autocomplete degli indirizzi nel tuo form, in tre file.
Nessun plugin, nessuna piattaforma: un file JavaScript che si aggancia ai campi che hai già, un proxy pronto per il tuo server che tiene il token al sicuro, tre righe per collegarli. Il visitatore scrive, la via si completa, CAP, città e provincia si riempiono da soli; un indirizzo scritto a mano viene verificato quando lascia il campo. Suggerimenti dai registri di 26 nazioni.
Cosa c'è nel kit
- ra-suggerisci.js·il widget: nessuna dipendenza, lo stesso file dei plugin WooCommerce e PrestaShop; suggerisce mentre si digita, alla selezione distribuisce l'indirizzo verificato nei campi
- ra-proxy.php·il proxy: tiene il token sul server, accetta solo il tuo dominio, frena per visitatore, inoltra a RadarAddress; se il token manca o il credito è finito risponde con una lista vuota e il form va avanti
- esempio.html·un form completo — nazione, indirizzo, CAP, città, provincia — che funziona appena il token è nel proxy: si copia e si adatta
- README·le opzioni del widget, il contratto del proxy per chi non usa PHP, cosa consuma
Come si fa, in tre passi
Crea l'account e il token
L'account è gratuito, non chiede la carta e ogni mese comprende una quota di elaborazioni: il token si crea in un clic e i passi sono spiegati lì.
Metti il proxy sul server
Copia ra-proxy.php sullo stesso dominio del form e scrivi il token nella riga indicata (meglio ancora: in un file fuori dalla cartella web, letto da lì). Niente altro da configurare.
Aggancia il widget ai campi
Includi ra-suggerisci.js nella pagina e indica i selettori dei tuoi campi: indirizzo, CAP, città, provincia e, se c'è, la nazione. Il resto lo fa il widget.
<script src="ra-suggerisci.js"></script>
<script>
RASuggerisci.attacca({
url: '/ra-proxy.php', // il proxy sul tuo server, mai l'API
campi: { indirizzo: '#indirizzo', cap: '#cap', localita: '#citta',
provincia: '#provincia', nazione_iso2: '#nazione' }, // il paese è facoltativo
lingua: 'it'
});
</script>
campi accetta qualunque selettore CSS. Le opzioni in più: onSeleziona riceve il record verificato (indirizzo normalizzato, esito, coordinate quando ci sono), scriviCampo per i form React e Vue, correggiAlBlur per decidere se verificare anche gli indirizzi scritti a mano, headers per un token CSRF verso il proxy. Tutto nel README del kit; il contratto dell'API è nella documentazione.
Requisiti: una pagina web qualsiasi e, per il proxy del kit, PHP 8.0 o successivo con cURL; altrimenti sessanta righe nel tuo linguaggio. Il widget è pubblicato con licenza Academic Free License 3.0.
Cosa succede nel form
- Mentre scrive·dopo due lettere il widget propone le vie, col nome completo e il comune; le lettere in più filtrano quello che ha già ricevuto, senza chiamare il server a ogni tasto; CAP e città già compilati restringono la ricerca
- Alla selezione·l'indirizzo verificato entra nei campi nella forma corretta — via per esteso, civico, CAP giusto anche nelle grandi città zonate, città e provincia — e si conta una verifica contatto; i civici della via si completano senza altri addebiti
- Scritto a mano·chi ignora la lista e scrive tutto da sé viene verificato quando lascia il campo: se l'indirizzo si riconosce, i campi si sistemano; se no, resta com'è. Nulla blocca mai l'invio
- All'estero·con la nazione indicata i suggerimenti vengono dal registro di quel paese e il visitatore scrive come si scrive lì, anche tutto in un campo; l'attribuzione del registro sta in fondo alla lista
Domande frequenti
Perché serve un proxy? Non posso chiamare l'API dalla pagina?
Il token API dà accesso al tuo credito: nella pagina lo leggerebbe chiunque. Il widget parla solo con un indirizzo del tuo stesso sito; lì un file di sessanta righe aggiunge il token e inoltra. Il proxy PHP del kit è pronto: si copia, si scrive il token, fine.
Il mio sito non è in PHP.
Il proxy è il riferimento, non un obbligo: riceve il JSON dal browser, aggiunge l'intestazione Authorization con il token, inoltra a /api/v1/suggest e restituisce la risposta. Si riscrive in qualunque linguaggio in pochi minuti; il README descrive il contratto.
Funziona con React, Vue, Angular?
Sì: il widget si aggancia ai campi con un selettore CSS qualsiasi. I form controllati vogliono che il valore sia scritto col setter nativo: l'opzione scriviCampo serve a questo, ed è quella che usa il plugin WooCommerce sul checkout a blocchi.
Cosa consuma?
Digitare è gratis. Si conta una verifica contatto quando il visitatore seleziona un indirizzo dalla lista (o quando un indirizzo scritto a mano viene verificato all'uscita dal campo, se lasci acceso correggiAlBlur): una per indirizzo, non per tasto. Ogni mese le prime 50 sono gratuite; oltre, i pacchetti e gli abbonamenti della pagina prezzi.
E se il credito finisce, o RadarAddress non risponde?
Il widget tace e il form funziona come sempre: nessun messaggio al visitatore, nessun invio bloccato. Il proxy restituisce una lista vuota su 401, 402 e su qualunque errore di rete.
Vale per l'estero?
Per tutte le nazioni in servizio: basta un campo con il codice ISO del paese (una select con IT, DE, FR… o un campo nascosto) indicato in nazione_iso2. Il visitatore scrive come si scrive nel suo paese, anche tutto in un campo; il popup riporta l'attribuzione del registro.
Posso cambiare l'aspetto del popup?
Il widget porta i suoi stili, senza file CSS: le variabili --ra-sugg-bg, --ra-sugg-bordo e --ra-sugg-hover sulla tua pagina cambiano i colori; la classe è .ra-sugg-pop per il resto.
Versioni
- 1.0.0 — prima versione del kit: widget, proxy PHP con freni e controllo dell'origine, form d'esempio, README.
Le altre integrazioni: WooCommerce, PrestaShop, AcyMailing, Convert Forms e Community Builder. L'elenco.