Integrationen · Ihr eigenes Formular
Die Adress-Autovervollständigung in Ihrem eigenen Formular, in drei Dateien.
Kein Plugin, keine Plattform: eine JavaScript-Datei, die sich an die Felder anbindet, die Sie bereits haben, ein fertiger Proxy für Ihren Server, der den Token sicher hält, drei Zeilen, um beides zu verbinden. Der Besucher tippt, die Straße vervollständigt sich, Postleitzahl, Ort und Provinz füllen sich von selbst; eine von Hand eingegebene Adresse wird geprüft, wenn das Feld verlassen wird. Vorschläge aus den Registern von 26 Ländern.
Was im Kit enthalten ist
- ra-suggerisci.js·das Widget: keine Abhängigkeiten, dieselbe Datei wie bei den Plugins WooCommerce und PrestaShop; es schlägt beim Tippen vor und trägt bei der Auswahl die geprüfte Adresse in die Felder ein
- ra-proxy.php·der Proxy: hält den Token auf dem Server, akzeptiert nur Ihre Domain, bremst pro Besucher, leitet an RadarAddress weiter; fehlt der Token oder ist das Guthaben aufgebraucht, antwortet er mit einer leeren Liste, und das Formular läuft weiter
- esempio.html·ein vollständiges Formular — Land, Adresse, Postleitzahl, Ort, Provinz —, das funktioniert, sobald der Token im Proxy steht: kopieren und anpassen
- README·die Optionen des Widgets, der Vertrag des Proxys für alle ohne PHP, was es verbraucht
So geht's, in drei Schritten
Konto und Token erstellen
Das Konto ist kostenlos, verlangt keine Karte und enthält jeden Monat ein Kontingent an Vorgängen: Der Token entsteht mit einem Klick, und die Schritte sind dort erklärt.
Proxy auf dem Server einrichten
Kopieren Sie ra-proxy.php auf dieselbe Domain wie das Formular und tragen Sie den Token in der angegebenen Zeile ein (noch besser: in einer Datei außerhalb des Web-Ordners, von dort ausgelesen). Sonst ist nichts zu konfigurieren.
Widget an die Felder anbinden
Binden Sie ra-suggerisci.js in die Seite ein und geben Sie die Selektoren Ihrer Felder an: Adresse, Postleitzahl, Ort, Provinz und, falls vorhanden, das Land. Den Rest erledigt das Widget.
<script src="ra-suggerisci.js"></script>
<script>
RASuggerisci.attacca({
url: '/ra-proxy.php', // der Proxy auf Ihrem Server, niemals die API
campi: { indirizzo: '#indirizzo', cap: '#cap', localita: '#citta',
provincia: '#provincia', nazione_iso2: '#nazione' }, // das Land ist optional
lingua: 'de'
});
</script>
campi akzeptiert jeden beliebigen CSS-Selektor. Die zusätzlichen Optionen: onSeleziona erhält den geprüften Datensatz (normalisierte Adresse, Ergebnis, Koordinaten, falls vorhanden), scriviCampo für React- und Vue-Formulare, correggiAlBlur, um zu entscheiden, ob auch von Hand eingegebene Adressen geprüft werden, headers für einen CSRF-Token gegenüber dem Proxy. Alles im README des Kits; der Vertrag der API steht in der Dokumentation.
Voraussetzungen: eine beliebige Webseite und, für den Proxy des Kits, PHP 8.0 oder neuer mit cURL; andernfalls sechzig Zeilen in Ihrer Sprache. Das Widget wird unter der Academic Free License 3.0 veröffentlicht.
Was im Formular passiert
- Während der Eingabe·nach zwei Buchstaben schlägt das Widget Straßen vor, mit vollständigem Namen und Gemeinde; weitere Buchstaben filtern das bereits Erhaltene, ohne bei jedem Tastendruck den Server aufzurufen; eine bereits ausgefüllte Postleitzahl und Stadt grenzen die Suche ein
- Bei der Auswahl·die geprüfte Adresse gelangt in korrekter Form in die Felder — Straße ausgeschrieben, Hausnummer, die richtige Postleitzahl auch in den großen Städten mit Postzonen, Ort und Provinz — und es wird eine Kontaktprüfung gezählt; die Hausnummern der Straße vervollständigen sich ohne weitere Belastung
- Von Hand eingegeben·wer die Liste ignoriert und alles selbst eingibt, wird beim Verlassen des Feldes geprüft: Wird die Adresse erkannt, werden die Felder korrigiert; wenn nicht, bleibt sie wie sie ist. Nichts blockiert jemals die Übermittlung
- Im Ausland·ist das Land angegeben, stammen die Vorschläge aus dem Register dieses Landes, und der Besucher schreibt so, wie man es dort schreibt, auch alles in einem einzigen Feld; die Quellenangabe des Registers steht unten in der Liste
Häufige Fragen
Warum braucht es einen Proxy? Kann ich die API nicht direkt von der Seite aus aufrufen?
Der API-Token gibt Zugriff auf Ihr Guthaben: Auf der Seite könnte ihn jeder auslesen. Das Widget spricht nur mit einer Adresse auf Ihrer eigenen Website; dort fügt eine sechzig Zeilen lange Datei den Token hinzu und leitet weiter. Der PHP-Proxy des Kits ist fertig: kopieren, den Token eintragen, fertig.
Meine Website ist nicht in PHP.
Der Proxy ist die Referenz, keine Pflicht: Er empfängt das JSON vom Browser, fügt den Authorization-Header mit dem Token hinzu, leitet an /api/v1/suggest weiter und gibt die Antwort zurück. Er lässt sich in wenigen Minuten in jeder Sprache neu schreiben; das README beschreibt den Vertrag.
Funktioniert es mit React, Vue, Angular?
Ja: Das Widget bindet sich mit jedem beliebigen CSS-Selektor an die Felder an. Kontrollierte Formulare verlangen, dass der Wert mit dem nativen Setter geschrieben wird: Dafür ist die Option scriviCampo da, dieselbe, die das WooCommerce-Plugin beim Block-Checkout verwendet.
Was verbraucht es?
Tippen ist kostenlos. Eine Kontaktprüfung wird gezählt, wenn der Besucher eine Adresse aus der Liste auswählt (oder wenn eine von Hand eingegebene Adresse beim Verlassen des Feldes geprüft wird, sofern Sie correggiAlBlur aktiviert lassen): eine pro Adresse, nicht pro Tastendruck. Jeden Monat sind die ersten 50 kostenlos; darüber hinaus die Pakete und Abonnements der Preisseite.
Und wenn das Guthaben aufgebraucht ist oder RadarAddress nicht antwortet?
Das Widget bleibt still, und das Formular funktioniert wie immer: keine Meldung an den Besucher, keine blockierte Übermittlung. Der Proxy gibt bei 401, 402 und bei jedem Netzwerkfehler eine leere Liste zurück.
Gilt das auch im Ausland?
Für alle im Dienst befindlichen Länder: Es genügt ein Feld mit dem ISO-Code des Landes (eine Auswahl mit IT, DE, FR… oder ein verstecktes Feld), angegeben in nazione_iso2. Der Besucher schreibt so, wie man es in seinem Land schreibt, auch alles in einem einzigen Feld; das Popup zeigt die Quellenangabe des Registers.
Kann ich das Aussehen des Popups ändern?
Das Widget bringt seine eigenen Stile mit, ohne CSS-Datei: Die Variablen --ra-sugg-bg, --ra-sugg-bordo und --ra-sugg-hover auf Ihrer Seite ändern die Farben; für den Rest ist die Klasse .ra-sugg-pop zuständig.
Versionen
- 1.0.0 — erste Version des Kits: Widget, PHP-Proxy mit Bremsen und Herkunftsprüfung, Beispielformular, README.
Die anderen Integrationen: WooCommerce, PrestaShop, AcyMailing, Convert Forms und Community Builder. Die Liste.