Οδηγός προγραμματιστών · Φόρμες εγγραφής
Δημιουργήστε τη δική σας εμπειρία εγγραφής.
Διατηρήστε το δικό σας HTML, τη μορφοποίηση και το πλαίσιο ανάπτυξης του ιστοτόπου σας. Συνδέστε την προσαρμοσμένη φόρμα σας με μια δημοσιευμένη φόρμα smartest.email μέσω του δημόσιου τελικού σημείου εγγραφής της.
Αυτός ο οδηγός καλύπτει
Δημόσιες ρυθμίσεις φορμών και εγγραφές από οποιαδήποτε προέλευση ιστοτόπου
Συγκατάθεση, επικύρωση, αποκρίσεις και όρια αιτημάτων
Χρησιμοποιήστε το URL της φόρμας σας.
Δημιουργήστε μια φόρμα στις Φόρμες εγγραφής, προσθέστε ένα υποχρεωτικό πεδίο email και ένα υποχρεωτικό πλαίσιο συγκατάθεσης και δημοσιεύστε την. Η καρτέλα Εγκατάσταση εμφανίζει το ακριβές URL της φόρμας σας.
Βασικό URL
https://api.smartest.email/api/v1/public/forms/{FORM_ID}Χρησιμοποιήστε το URL στην καρτέλα Εγκατάσταση της φόρμας. Αντικαταστήστε το FORM_ID με το αναγνωριστικό της δημοσιευμένης φόρμας στα παρακάτω παραδείγματα.
Δημιουργία
Ορίστε τα πεδία σας και ένα σαφές κείμενο συγκατάθεσης.
Δημοσίευση
Οι νέες φόρμες ξεκινούν ως πρόχειρα· οι δημόσιες διαδρομές επιστρέφουν 404 μέχρι τη δημοσίευση.
Ενσωμάτωση
Χρησιμοποιήστε το απόσπασμα ενσωμάτωσης ή καλέστε τα δύο δημόσια τελικά σημεία παρακάτω.
Χρησιμοποιήστε τη δική σας φόρμα HTML.
Υποστηρίζεται η απευθείας υποβολή. Δημιουργήστε και δημοσιεύστε μια φόρμα στο smartest.email για να ορίσετε τα πεδία και το κείμενο συγκατάθεσης και χρησιμοποιήστε το αναγνωριστικό της στην υπάρχουσα φόρμα του ιστοτόπου σας. Μπορείτε να επιλέξετε τον τύπο ενσωματωμένης φόρμας χωρίς να εγκαταστήσετε το widget.
Ο ιστότοπός σας μπορεί να υποβάλλει με JavaScript fetch(), ή ο δικός σας διακομιστής μπορεί να προωθεί την εγγραφή ως JSON. Το δημόσιο τελικό σημείο δεν απαιτεί κλειδί API, διακριτικό πρόσβασης ή script ενσωμάτωσης smartest.email.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/submitΑντικαταστήστε το FORM_ID με το UUID της δημοσιευμένης φόρμας σας. Στείλτε Content-Type: application/json με το παρακάτω περιεχόμενο.
{
"data": {
"email": "visitor@example.com"
},
"consent": true
}Ορίστε consent από τη ρητή επιλογή του επισκέπτη και εμφανίστε το κείμενο συγκατάθεσης και την ενημέρωση απορρήτου της φόρμας. Διατηρήστε consent στο ανώτερο επίπεδο· τοποθετήστε τα ρυθμισμένα πεδία επαφής μέσα στο data. Συμπεριλάβετε όλα τα υποχρεωτικά πεδία της δημοσιευμένης φόρμας.
Μια απλή ενέργεια φόρμας HTML χρειάζεται προσαρμογέα
Το τελικό σημείο δέχεται μόνο JSON. Μια συνηθισμένη <form method="post" action="…"> στέλνει δεδομένα URL-encoded ή multipart και λαμβάνει 415 JSON body required. Χρησιμοποιήστε το παρακάτω παράδειγμα JavaScript για τον περιηγητή, ή υποβάλετε στον δικό σας διακομιστή ώστε να στείλει JSON στο smartest.email.
Η ανάκτηση των δημόσιων ρυθμίσεων διατηρεί τις ετικέτες και την επικύρωση σε συμφωνία με τη δημοσιευμένη φόρμα. Δεν αποτελεί προϋπόθεση για κάθε υποβολή. Η ενσωμάτωσή σας χειρίζεται το δικό της μήνυμα επιτυχίας ή ανακατεύθυνση· αυτό το τελικό σημείο αποκρίνεται πάντα με JSON.
Εμφανίστε τα πεδία που δημοσιεύσατε.
Αυτό το δημόσιο τελικό σημείο δεν απαιτεί διακριτικό πρόσβασης. Ανακτήστε το όταν εμφανίζετε μια φόρμα και χρησιμοποιήστε τα ονόματα πεδίων, το κείμενο συγκατάθεσης και το URL απορρήτου που επιστρέφονται στην προσαρμοσμένη διεπαφή σας.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}Επιστρέφει 200 με ασφαλή δεδομένα εμφάνισης για μια ενεργή φόρμα. Κάθε επιτυχής ανάκτηση αυξάνει τον αριθμό προβολών της· αποφύγετε τις επαναλαμβανόμενες κλήσεις ελέγχου.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/embed.jsΈτοιμο script ενσωματωμένου ή αναδυόμενου widget. Χρησιμοποιήστε το ακριβές URL του script από την Εγκατάσταση αν δεν χρειάζεστε προσαρμοσμένη διεπαφή.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/landingΦιλοξενούμενη σελίδα εγγραφής για ενεργή φόρμα.
{
"id": "FORM_ID",
"name": "Newsletter",
"organizationName": "Example Studio",
"type": "embedded",
"fields": [
{ "name": "email", "type": "email", "label": "Email address", "required": true },
{ "name": "consent", "type": "checkbox", "label": "I agree to receive email updates.", "required": true }
],
"styling": {},
"successAction": {},
"privacyUrl": "https://example.com/privacy"
}Η απόκριση μπορεί να περιλαμβάνει επιπλέον ρυθμισμένα πεδία, επιλογές και κανόνες επικύρωσης. successAction περιγράφει τη συμπεριφορά του έτοιμου widget· η απευθείας υποβολή εξακολουθεί να επιστρέφει τη γενική απόκριση JSON παρακάτω. Το script και η φιλοξενούμενη σελίδα επιστρέφουν 404 για πρόχειρες, μη δημοσιευμένες, μη έγκυρες ή άγνωστες φόρμες.
Στείλτε τη συγκατάθεση μαζί με τα δεδομένα.
Υποβάλετε JSON αφού ο επισκέπτης επιλέξει ρητά να λαμβάνει email μάρκετινγκ. Η ένδειξη συγκατάθεσης ανήκει στο ανώτερο επίπεδο· μην τοποθετείτε τη συγκατάθεση μέσα στο data.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/submitΧωρίς διακριτικό πρόσβασης. Στείλτε Content-Type: application/json και {data:{email:...},consent:true}. Επιστρέφει την ίδια γενική επιτυχία για νέες και υπάρχουσες διευθύνσεις.
<form id="signup-form">
<fieldset id="signup-fields" disabled>
<legend>Subscribe to email updates</legend>
<label id="email-label" for="signup-email">Email address</label>
<input id="signup-email" type="email" autocomplete="email" required>
<label for="signup-consent">
<input id="signup-consent" type="checkbox" required>
<span id="consent-label"></span>
</label>
<a id="privacy-link" href="/privacy">Privacy notice</a>
<button id="signup-submit" type="submit">Subscribe</button>
</fieldset>
<p id="signup-status" role="status" aria-live="polite"></p>
</form>
<script type="module">
const endpoint = "https://api.smartest.email/api/v1/public/forms/FORM_ID";
const form = document.querySelector("#signup-form");
const fields = document.querySelector("#signup-fields");
const button = document.querySelector("#signup-submit");
const status = document.querySelector("#signup-status");
let ready = false;
let submitting = false;
form.addEventListener("submit", async event => {
event.preventDefault();
if (!ready || submitting || !form.reportValidity()) return;
submitting = true;
button.disabled = true;
try {
const response = await fetch(endpoint + "/submit", {
method: "POST",
credentials: "omit",
headers: { "Content-Type": "application/json", "Accept": "application/json" },
body: JSON.stringify({
data: { email: document.querySelector("#signup-email").value.trim() },
consent: document.querySelector("#signup-consent").checked
})
});
const result = await response.json();
status.textContent = result.message || "Please try again.";
if (response.ok) form.reset();
} catch {
status.textContent = "Please try again.";
} finally {
submitting = false;
button.disabled = false;
}
});
try {
const response = await fetch(endpoint, { credentials: "omit" });
if (!response.ok) throw new Error("Signup form unavailable");
const config = await response.json();
document.querySelector("#email-label").textContent =
config.fields.find(field => field.name === "email").label;
document.querySelector("#consent-label").textContent =
config.fields.find(field => field.name === "consent").label;
if (config.privacyUrl) {
document.querySelector("#privacy-link").href = config.privacyUrl;
}
ready = true;
fields.disabled = false;
} catch (error) {
status.textContent = error.message;
}
</script>Αντικαταστήστε FORM_ID με το UUID της φόρμας σας και ορίστε τον εναλλακτικό /privacy σύνδεσμο προς τη δική σας ενημέρωση, αν η φόρμα δεν έχει ρυθμισμένο privacyUrl. Αυτό το παράδειγμα χειρίζεται τα δύο υποχρεωτικά πεδία· εμφανίστε και στείλτε τυχόν επιπλέον υποχρεωτικά πεδία από τις δημοσιευμένες ρυθμίσεις σας.
Απόκριση αποδοχής
{"success":true,"message":"Thank you for subscribing."}Η απόκριση σκόπιμα δεν αναφέρει αν μια διεύθυνση υπάρχει ήδη. Οι υπάρχουσες εγγεγραμμένες και διαγραμμένες από τη λίστα επαφές διατηρούν την κατάστασή τους· μόνο μια νέα αποδεκτή διεύθυνση προσθέτει συνδρομητή και καταγραφή συγκατάθεσης.
Στείλτε μόνο ονόματα που υπάρχουν στον δημοσιευμένο fields πίνακα. Τα υποχρεωτικά πεδία πρέπει να παρέχονται. Για επιπλέον πεδία, στείλτε τιμές πλαισίων επιλογής ως boolean, αριθμούς ως αριθμητικές συμβολοσειρές, ημερομηνίες ως YYYY-MM-DD, και τιμές select ή radio ακριβώς όπως αναφέρονται στο options. Το API επικυρώνει ξανά τα δεδομένα στον διακομιστή.
Η προαιρετική ιδιότητα ανώτερου επιπέδου website είναι παγίδα ανεπιθύμητων υποβολών. Παραλείψτε την ή αφήστε την κενή για κανονική υποβολή. Μια μη κενή τιμή επιστρέφει τη γενική απόκριση επιτυχίας χωρίς να προσθέτει επαφή· δεν είναι πεδίο για το URL του ιστοτόπου του επισκέπτη.
Χειριστείτε σφάλματα και όρια κίνησης.
Τα δημόσια τελικά σημεία φορμών επιτρέπουν αιτήματα GET, POST και OPTIONS μεταξύ διαφορετικών προελεύσεων από εξωτερικούς ιστοτόπους με κεφαλίδες Content-Type και Accept. Χρησιμοποιήστε credentials: omit στα αιτήματα περιηγητή· δεν απαιτούνται cookie λογαριασμού, κεφαλίδα Authorization ή κλειδί API.
| Κατάσταση | Σημασία |
|---|---|
| 200 | Ρυθμίσεις ή αποδεκτή υποβολή· μια διπλότυπη διεύθυνση λαμβάνει την ίδια απόκριση υποβολής. |
| 400 / 415 | Εσφαλμένο JSON / το αίτημα δεν είναι application/json. |
| 404 | Άγνωστη, πρόχειρη, μη δημοσιευμένη ή μη έγκυρη φόρμα. |
| 409 | Ο λογαριασμός έχει φτάσει το όριο επαφών του. |
| 413 / 422 | Το σώμα υπερβαίνει τα 16 KiB / η συγκατάθεση ή τα δεδομένα πεδίων δεν είναι έγκυρα. |
| 429 | Συμπληρώθηκε το όριο αιτημάτων· ο κώδικας περιηγητή μπορεί να χρησιμοποιήσει retry_after στο σώμα JSON. Οι ενσωματώσεις διακομιστή μπορούν επίσης να διαβάσουν Retry-After. |
Τα σφάλματα χρησιμοποιούν {"error":true,"message":"..."}· τα σφάλματα ορίου αιτημάτων περιλαμβάνουν επίσης retry_after σε δευτερόλεπτα. Οι φόρμες επιτρέπουν έως 30 αιτήματα ανά IP ανά λεπτό, συμπεριλαμβανομένων έως 10 υποβολών. Η Πολιτική Ασφάλειας Περιεχομένου του ιστοτόπου σας πρέπει να επιτρέπει https://api.smartest.email στο connect-src· η έτοιμη ενσωμάτωση το χρειάζεται επίσης στο script-src.
Όταν ο δικός σας διακομιστής προωθεί υποβολές, αυτές μοιράζονται την εξερχόμενη IP του διακομιστή για τον περιορισμό του ρυθμού αιτημάτων.
Συγκατάθεση και παράδοση
Μια νέα αποδεκτή εγγραφή δημιουργεί μια εγγεγραμμένη επαφή και αποθηκεύει το κείμενο συγκατάθεσης της φόρμας, την ώρα και την παρεχόμενη προέλευση του αιτήματος. Η προσαρμοσμένη διεπαφή σας πρέπει να εμφανίζει το κείμενο συγκατάθεσης και την ενημέρωση απορρήτου πριν ο επισκέπτης υποβάλει τη φόρμα. Η καταγεγραμμένη προέλευση του αιτήματος δεν αποτελεί απόδειξη ταυτότητας. Αυτό το τελικό σημείο χρησιμοποιεί απλή εγγραφή· δεν στέλνει email επιβεβαίωσης ούτε επαληθεύει την κυριότητα της διεύθυνσης.

