Integraties · Je eigen form
Adres-autocomplete in je eigen form, in drie bestanden.
Geen plugin, geen platform: één JavaScript-bestand dat aan de velden koppelt die je al hebt, een kant-en-klare proxy voor je server die het token veilig houdt, drie regels om ze te verbinden. De bezoeker typt, de straat wordt aangevuld, postcode, plaats en provincie vullen zichzelf in; een handmatig getypt adres wordt gecontroleerd zodra het veld wordt verlaten. Suggesties uit de registers van 26 landen.
Wat zit er in de kit
- ra-suggerisci.js·de widget: geen afhankelijkheden, hetzelfde bestand als de WooCommerce- en PrestaShop-plugins; hij suggereert terwijl je typt en verdeelt bij selectie het geverifieerde adres over de velden
- ra-proxy.php·de proxy: houdt het token op de server, accepteert alleen je eigen domein, remt per bezoeker, stuurt door naar RadarAddress; als het token ontbreekt of het tegoed op is, antwoordt hij met een lege lijst en gaat het form gewoon verder
- esempio.html·een compleet form — land, adres, postcode, plaats, provincie — dat werkt zodra het token in de proxy staat: kopiëren en aanpassen
- README·de opties van de widget, het contract van de proxy voor wie geen PHP gebruikt, wat het verbruikt
Hoe het werkt, in drie stappen
Maak het account en het token aan
Het account is gratis, vraagt geen creditcard en omvat elke maand een aantal bewerkingen: het token maak je met één klik aan en de stappen staan daar uitgelegd.
Zet de proxy op de server
Kopieer ra-proxy.php naar hetzelfde domein als het form en schrijf het token op de aangegeven regel (nog beter: in een bestand buiten de webmap, van daaruit gelezen). Verder niets te configureren.
Koppel de widget aan de velden
Neem ra-suggerisci.js op in de pagina en geef de selectors van je velden op: adres, postcode, plaats, provincie en, als die er is, het land. De rest doet de widget.
<script src="ra-suggerisci.js"></script>
<script>
RASuggerisci.attacca({
url: '/ra-proxy.php', // de proxy op je server, nooit de API
campi: { indirizzo: '#indirizzo', cap: '#cap', localita: '#citta',
provincia: '#provincia', nazione_iso2: '#nazione' }, // het land is optioneel
lingua: 'nl'
});
</script>
campi accepteert elke CSS-selector. De extra opties: onSeleziona ontvangt het geverifieerde record (genormaliseerd adres, uitkomst, coördinaten indien aanwezig), scriviCampo voor React- en Vue-forms, correggiAlBlur om te bepalen of ook handmatig getypte adressen worden gecontroleerd, headers voor een CSRF-token richting de proxy. Alles in het README van de kit; het contract van de API staat in de documentatie.
Vereisten: een willekeurige webpagina en, voor de proxy van de kit, PHP 8.0 of hoger met cURL; anders zestig regels in je eigen taal. De widget wordt gepubliceerd onder de Academic Free License 3.0.
Wat er in het form gebeurt
- Terwijl je typt·na twee letters stelt de widget straten voor, met volledige naam en gemeente; extra letters filteren wat al binnen is, zonder bij elke toets de server aan te roepen; een al ingevulde postcode en plaats versmallen de zoekopdracht
- Bij selectie·het geverifieerde adres komt in de juiste vorm in de velden — straat voluit, huisnummer, de juiste postcode ook in grote steden met meerdere postcodes, plaats en provincie — en er wordt één contactverificatie geteld; de huisnummers van de straat worden aangevuld zonder extra kosten
- Handmatig getypt·wie de lijst negeert en alles zelf typt, wordt gecontroleerd bij het verlaten van het veld: als het adres herkend wordt, worden de velden aangepast; zo niet, dan blijft het zoals het is. Niets blokkeert ooit de verzending
- In het buitenland·met het land opgegeven komen de suggesties uit het register van dat land en schrijft de bezoeker zoals daar gebruikelijk is, ook alles in één veld; de bronvermelding van het register staat onderaan de lijst
Veelgestelde vragen
Waarom een proxy? Kan ik de API niet vanaf de pagina aanroepen?
Het API-token geeft toegang tot je tegoed: op de pagina zou iedereen het kunnen lezen. De widget praat alleen met een adres op je eigen site; daar voegt een bestand van zestig regels het token toe en stuurt door. De PHP-proxy van de kit is kant-en-klaar: kopiëren, token invullen, klaar.
Mijn site is niet in PHP.
De proxy is de referentie, geen verplichting: hij ontvangt de JSON van de browser, voegt de Authorization-header met het token toe, stuurt door naar /api/v1/suggest en geeft het antwoord terug. Hij is in elke taal in een paar minuten na te bouwen; het README beschrijft het contract.
Werkt het met React, Vue, Angular?
Ja: de widget koppelt aan de velden met elke CSS-selector. Controlled forms willen dat de waarde met de native setter wordt geschreven: daarvoor dient de optie scriviCampo, dezelfde die de WooCommerce-plugin gebruikt bij de blokken-checkout.
Wat verbruikt het?
Typen is gratis. Er wordt één contactverificatie geteld wanneer de bezoeker een adres uit de lijst kiest (of wanneer een handmatig getypt adres wordt gecontroleerd bij het verlaten van het veld, als je correggiAlBlur aan laat staan): één per adres, niet per toets. Elke maand zijn de eerste 50 gratis; daarboven de pakketten en abonnementen van de prijzenpagina.
En als het tegoed op is, of RadarAddress niet antwoordt?
De widget zwijgt en het form werkt zoals altijd: geen bericht aan de bezoeker, geen geblokkeerde verzending. De proxy geeft een lege lijst terug bij 401, 402 en bij elke netwerkfout.
Werkt het ook in het buitenland?
Voor alle landen die we ondersteunen: genoeg is een veld met de ISO-code van het land (een select met IT, DE, FR… of een verborgen veld), opgegeven in nazione_iso2. De bezoeker schrijft zoals in zijn land gebruikelijk is, ook alles in één veld; de popup toont de bronvermelding van het register.
Kan ik het uiterlijk van de popup aanpassen?
De widget brengt zijn eigen stijlen mee, zonder CSS-bestand: de variabelen --ra-sugg-bg, --ra-sugg-bordo en --ra-sugg-hover op je pagina veranderen de kleuren; voor de rest is er de klasse .ra-sugg-pop.
Versies
- 1.0.0 — eerste versie van de kit: widget, PHP-proxy met limieten per bezoeker en herkomstcontrole, voorbeeldform, README.
De andere integraties: WooCommerce, PrestaShop, AcyMailing, Convert Forms en Community Builder. De lijst.