Ενσωματώσεις · Το δικό σας form
Η αυτόματη συμπλήρωση διευθύνσεων στο δικό σας form, σε τρία αρχεία.
Κανένα πρόσθετο, καμία πλατφόρμα: ένα αρχείο JavaScript που συνδέεται με τα πεδία που έχετε ήδη, ένα έτοιμο proxy για τον διακομιστή σας που κρατά το token ασφαλές, τρεις γραμμές για να τα συνδέσετε. Ο επισκέπτης γράφει, η οδός συμπληρώνεται, ταχυδρομικός κώδικας, πόλη και επαρχία γεμίζουν μόνα τους· μια χειρόγραφη διεύθυνση επαληθεύεται όταν αφήνει το πεδίο. Προτάσεις από τα μητρώα 26 χωρών.
Τι περιέχει το κιτ
- ra-suggerisci.js·το widget: καμία εξάρτηση, το ίδιο αρχείο με τα πρόσθετα WooCommerce και PrestaShop· προτείνει καθώς πληκτρολογείτε, και στην επιλογή κατανέμει την επαληθευμένη διεύθυνση στα πεδία
- ra-proxy.php·το proxy: κρατά το token στον διακομιστή, δέχεται μόνο τον δικό σας τομέα, βάζει όριο ανά επισκέπτη, προωθεί στο RadarAddress· αν λείπει το token ή έχει τελειώσει η πίστωση απαντά με άδεια λίστα και το form συνεχίζει κανονικά
- esempio.html·ένα πλήρες form — χώρα, διεύθυνση, ταχυδρομικός κώδικας, πόλη, επαρχία — που λειτουργεί μόλις το token μπει στο proxy: το αντιγράφετε και το προσαρμόζετε
- README·τις επιλογές του widget, το συμβόλαιο του proxy για όσους δεν χρησιμοποιούν PHP, τι καταναλώνει
Πώς γίνεται, σε τρία βήματα
Δημιουργήστε τον λογαριασμό και το token
Ο λογαριασμός είναι δωρεάν, δεν ζητά κάρτα και κάθε μήνα περιλαμβάνει ένα μερίδιο επεξεργασιών: το token δημιουργείται με ένα κλικ και τα βήματα εξηγούνται εκεί.
Τοποθετήστε το proxy στον διακομιστή
Αντιγράψτε το ra-proxy.php στον ίδιο τομέα με το form και γράψτε το token στη γραμμή που υποδεικνύεται (ακόμη καλύτερα: σε ένα αρχείο εκτός του φακέλου web, που διαβάζεται από εκεί). Τίποτα άλλο δεν χρειάζεται ρύθμιση.
Συνδέστε το widget με τα πεδία
Συμπεριλάβετε το ra-suggerisci.js στη σελίδα και υποδείξτε τους επιλογείς των πεδίων σας: διεύθυνση, ταχυδρομικός κώδικας, πόλη, επαρχία και, αν υπάρχει, η χώρα. Τα υπόλοιπα τα κάνει το widget.
<script src="ra-suggerisci.js"></script>
<script>
RASuggerisci.attacca({
url: '/ra-proxy.php', // το proxy στον δικό σας διακομιστή, ποτέ το API
campi: { indirizzo: '#indirizzo', cap: '#cap', localita: '#citta',
provincia: '#provincia', nazione_iso2: '#nazione' }, // η χώρα είναι προαιρετική
lingua: 'el'
});
</script>
Το campi δέχεται οποιονδήποτε επιλογέα CSS. Οι επιπλέον επιλογές: το onSeleziona λαμβάνει την επαληθευμένη εγγραφή (κανονικοποιημένη διεύθυνση, αποτέλεσμα, συντεταγμένες όταν υπάρχουν), το scriviCampo για τα form React και Vue, το correggiAlBlur για να αποφασίσετε αν επαληθεύονται και οι χειρόγραφες διευθύνσεις, το headers για ένα token CSRF προς το proxy. Όλα στο README του κιτ· το συμβόλαιο του API είναι στην τεκμηρίωση.
Απαιτήσεις: οποιαδήποτε ιστοσελίδα και, για το proxy του κιτ, PHP 8.0 ή νεότερη με cURL· διαφορετικά εξήντα γραμμές στη δική σας γλώσσα. Το widget δημοσιεύεται με άδεια Academic Free License 3.0.
Τι συμβαίνει στο form
- Καθώς γράφει·μετά από δύο γράμματα το widget προτείνει τις οδούς, με το πλήρες όνομα και τον δήμο· τα επιπλέον γράμματα φιλτράρουν όσα έχει ήδη λάβει, χωρίς να καλεί τον διακομιστή σε κάθε πλήκτρο· ταχυδρομικός κώδικας και πόλη ήδη συμπληρωμένα περιορίζουν την αναζήτηση
- Στην επιλογή·η επαληθευμένη διεύθυνση μπαίνει στα πεδία στη σωστή μορφή — οδός ολογράφως, αριθμός, ο σωστός ταχυδρομικός κώδικας ακόμη και στις μεγάλες πόλεις με ζώνες, πόλη και επαρχία — και μετριέται μία επαλήθευση επαφής· οι αριθμοί της οδού συμπληρώνονται χωρίς άλλη χρέωση
- Χειρόγραφη·όποιος αγνοεί τη λίστα και γράφει τα πάντα μόνος του επαληθεύεται όταν αφήνει το πεδίο: αν η διεύθυνση αναγνωρίζεται, τα πεδία τακτοποιούνται· αν όχι, παραμένει όπως είναι. Τίποτα δεν μπλοκάρει ποτέ την αποστολή
- Στο εξωτερικό·με τη χώρα υποδεδειγμένη, οι προτάσεις προέρχονται από το μητρώο εκείνης της χώρας και ο επισκέπτης γράφει όπως γράφεται εκεί, ακόμη και όλο σε ένα πεδίο· η απόδοση πηγής του μητρώου βρίσκεται στο κάτω μέρος της λίστας
Συχνές ερωτήσεις
Γιατί χρειάζεται ένα proxy; Δεν μπορώ να καλέσω το API απευθείας από τη σελίδα;
Το token του API δίνει πρόσβαση στην πίστωσή σας: στη σελίδα θα μπορούσε να το διαβάσει οποιοσδήποτε. Το widget επικοινωνεί μόνο με μια διεύθυνση του ίδιου σας του ιστότοπου· εκεί ένα αρχείο εξήντα γραμμών προσθέτει το token και το προωθεί. Το proxy PHP του κιτ είναι έτοιμο: το αντιγράφετε, γράφετε το token, τέλος.
Ο ιστότοπός μου δεν είναι σε PHP.
Το proxy είναι το σημείο αναφοράς, όχι υποχρέωση: λαμβάνει το JSON από το browser, προσθέτει την κεφαλίδα Authorization με το token, το προωθεί στο /api/v1/suggest και επιστρέφει την απάντηση. Ξαναγράφεται σε οποιαδήποτε γλώσσα μέσα σε λίγα λεπτά· το README περιγράφει το συμβόλαιο.
Λειτουργεί με React, Vue, Angular;
Ναι: το widget συνδέεται με τα πεδία μέσω οποιουδήποτε επιλογέα CSS. Τα ελεγχόμενα form θέλουν η τιμή να γράφεται με τον εγγενή setter: η επιλογή scriviCampo χρησιμεύει ακριβώς σε αυτό, και είναι αυτή που χρησιμοποιεί το πρόσθετο WooCommerce στο checkout σε blocks.
Τι καταναλώνει;
Η πληκτρολόγηση είναι δωρεάν. Μία επαλήθευση επαφής μετριέται όταν ο επισκέπτης επιλέγει μια διεύθυνση από τη λίστα (ή όταν μια χειρόγραφη διεύθυνση επαληθεύεται με την έξοδο από το πεδίο, αν κρατάτε ενεργό το correggiAlBlur): μία ανά διεύθυνση, όχι ανά πλήκτρο. Κάθε μήνα οι πρώτες 50 είναι δωρεάν· πέρα από αυτές, τα πακέτα και οι συνδρομές της σελίδας τιμών.
Κι αν τελειώσει η πίστωση, ή το RadarAddress δεν απαντήσει;
Το widget σωπαίνει και το form λειτουργεί όπως πάντα: κανένα μήνυμα στον επισκέπτη, καμία αποστολή μπλοκαρισμένη. Το proxy επιστρέφει άδεια λίστα στα 401, 402 και σε οποιοδήποτε σφάλμα δικτύου.
Ισχύει και για το εξωτερικό;
Για όλες τις χώρες σε λειτουργία: αρκεί ένα πεδίο με τον κωδικό ISO της χώρας (ένα select με IT, DE, FR… ή ένα κρυφό πεδίο) που υποδεικνύεται στο nazione_iso2. Ο επισκέπτης γράφει όπως γράφεται στη χώρα του, ακόμη και όλο σε ένα πεδίο· το popup αναφέρει την απόδοση πηγής του μητρώου.
Μπορώ να αλλάξω την εμφάνιση του popup;
Το widget φέρνει τα δικά του στιλ, χωρίς αρχείο CSS: οι μεταβλητές --ra-sugg-bg, --ra-sugg-bordo και --ra-sugg-hover στη σελίδα σας αλλάζουν τα χρώματα· η κλάση είναι .ra-sugg-pop για τα υπόλοιπα.
Εκδόσεις
- 1.0.0 — πρώτη έκδοση του κιτ: widget, proxy PHP με όρια χρήσης και έλεγχο προέλευσης, δείγμα form, README.
Οι άλλες ενσωματώσεις: WooCommerce, PrestaShop, AcyMailing, Convert Forms και Community Builder. Η λίστα.