Pāriet uz saturu

Izstrādātāja ceļvedis · Reģistrācijas veidlapas

Izveidojiet savu reģistrēšanās pieredzi.

Saglabājiet savu HTML, stilu un vietnes ietvaru. Savienojiet pielāgoto veidlapu ar publicētu smartest.email veidlapu, izmantojot tās publisko reģistrācijas galapunktu.

Šajā ceļvedī ir aprakstīts

Publiska veidlapu konfigurācija un reģistrācija no jebkuras vietnes izcelsmes

Piekrišana, validācija, atbildes un pieprasījumu ierobežojumi

Izmantojiet savas veidlapas URL.

Sadaļā Reģistrācijas veidlapas izveidojiet veidlapu ar obligātu e-pasta lauku un obligātu piekrišanas izvēles rūtiņu, tad publicējiet to. Cilnē Uzstādīšana redzams precīzs veidlapas URL.

Pamata URL

https://api.smartest.email/api/v1/public/forms/{FORM_ID}

Izmantojiet veidlapas cilnē Uzstādīšana redzamo URL. Tālāk esošajos piemēros aizstājiet FORM_ID ar publicētās veidlapas ID.

1

Izveidot

Iestatiet laukus un skaidru piekrišanas tekstu.

2

Publicēt

Jaunas veidlapas sākas kā melnraksti; publiskie maršruti atgriež 404 līdz publicēšanai.

3

Integrēt

Izmantojiet iegulšanas kodu vai izsauciet abus tālāk norādītos publiskos galapunktus.

Izmantojiet savu HTML veidlapu.

Tieša iesniegšana tiek atbalstīta. Izveidojiet un publicējiet veidlapu smartest.email, lai noteiktu laukus un piekrišanas tekstu, un izmantojiet tās ID savas vietnes esošajā veidlapā. Varat izvēlēties iegultas veidlapas tipu, neuzstādot logrīku.

Jūsu vietne var iesniegt datus ar JavaScript fetch(), vai jūsu serveris var pārsūtīt reģistrāciju JSON formātā. Publiskajam galapunktam nav vajadzīga API atslēga, piekļuves pilnvara vai smartest.email iegulšanas skripts.

POST
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/submit

Aizstājiet FORM_ID ar publicētās veidlapas UUID. Nosūtiet Content-Type: application/json ar tālāk norādīto saturu.

JSON pieprasījums · pēc apmeklētāja piekrišanas
{
  "data": {
    "email": "visitor@example.com"
  },
  "consent": true
}

Iestatiet consent atbilstoši apmeklētāja nepārprotamai izvēlei un parādiet veidlapas piekrišanas tekstu un privātuma paziņojumu. Saglabājiet consent augstākajā līmenī; konfigurētos kontaktu laukus ievietojiet data. Iekļaujiet visus publicētās veidlapas obligātos laukus.

Parastai HTML veidlapas darbībai vajadzīgs adapteris

Galapunkts pieņem tikai JSON. Parasts <form method="post" action="…"> sūta URL kodētus vai multipart datus un saņem 415 JSON body required. Izmantojiet tālāk redzamo pārlūkprogrammas JavaScript piemēru, vai nosūtiet savam serverim, lai tas pārsūtītu JSON uz smartest.email.

Iegūstot publisko konfigurāciju etiķetes un validācija paliek saskaņotas ar publicēto veidlapu. Tas nav priekšnoteikums katram iesniegumam. Jūsu integrācija pati apstrādā veiksmes ziņojumu vai novirzīšanu; šis galapunkts vienmēr atbild ar JSON.

Attēlojiet publicētos laukus.

Šim publiskajam galapunktam nav vajadzīga piekļuves pilnvara. Iegūstiet to, rādot veidlapu, un izmantojiet atgrieztos lauku nosaukumus, piekrišanas tekstu un privātuma URL savā saskarnē.

GET
https://api.smartest.email/api/v1/public/forms/{FORM_ID}

Atgriež 200 ar drošiem attēlošanas datiem aktīvai veidlapai. Katra veiksmīga iegūšana palielina skatījumu skaitu; izvairieties no periodiskas aptaujas.

GET
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/embed.js

Gatavs iekļauta vai uznirstoša logrīka skripts. Izmantojiet precīzu skripta URL no cilnes Uzstādīšana, ja nav vajadzīga pielāgota saskarne.

GET
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/landing

Mitināta reģistrācijas lapa aktīvai veidlapai.

GET /api/v1/public/forms/{FORM_ID} · atbildes piemērs
{
  "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"
}

Atbilde var ietvert papildu konfigurētos laukus, izvēles un validācijas noteikumus. successAction apraksta gatavā logrīka darbību; tieša iesniegšana joprojām atgriež tālāk norādīto vispārīgo JSON atbildi. Skripts un mitinātā lapa atgriež 404 melnrakstiem, nepublicētām, nederīgām vai nezināmām veidlapām.

Nosūtiet piekrišanu kopā ar datiem.

Nosūtiet JSON pēc tam, kad apmeklētājs nepārprotami izvēlas saņemt mārketinga e-pastus. Piekrišanas karodziņš atrodas augstākajā līmenī; nelieciet consent iekš data.

POST
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/submit

Bez piekļuves pilnvaras. Nosūtiet Content-Type: application/json un {data:{email:...},consent:true}. Atgriež vienādu vispārīgu veiksmes atbildi jaunām un esošām adresēm.

HTML + pārlūkprogrammas JavaScript · e-pasta un piekrišanas veidlapa
<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>

Aizstājiet FORM_ID ar veidlapas UUID un iestatiet rezerves /privacy saiti uz savu paziņojumu, ja veidlapai nav konfigurēta privacyUrl. Šajā piemērā ir apstrādāti divi obligātie lauki; attēlojiet un nosūtiet visus papildu obligātos laukus no publicētās konfigurācijas.

Pieņemšanas atbilde

JSON
{"success":true,"message":"Thank you for subscribing."}

Atbilde apzināti neatklāj, vai adrese jau pastāv. Esošie abonētie un atteikušies kontakti saglabā pašreizējo stāvokli; tikai jauna pieņemta adrese pievieno abonentu un piekrišanas ierakstu.

Sūtiet tikai nosaukumus, kas ir publicētajā fields masīvā. Obligātie lauki jānorāda. Papildu laukiem sūtiet izvēles rūtiņu vērtības kā loģiskās vērtības, skaitļus kā skaitļu virknes, datumus kā YYYY-MM-DD, un select vai radio vērtības tieši tā, kā norādīts options. API atkārtoti pārbauda datus serverī.

Neobligātais augstākā līmeņa website rekvizīts ir mēstuļu slazds. Parastā iesniegumā izlaidiet to vai atstājiet tukšu. Netukša vērtība atgriež vispārīgo veiksmes atbildi bez kontakta pievienošanas; tas nav apmeklētāja vietnes URL lauks.

Apstrādājiet kļūmes un datplūsmas ierobežojumus.

Publiskie veidlapu galapunkti atļauj starpizcelsmes GET, POST un OPTIONS pieprasījumus no ārējām vietnēm ar Content-Type un Accept galvenēm. Pārlūkprogrammas pieprasījumos izmantojiet credentials: omit; konta sīkdatnes, Authorization galvene vai API atslēga nav vajadzīga.

StatussNozīme
200Konfigurācija vai pieņemts iesniegums; atkārtota adrese saņem tādu pašu iesniegšanas atbildi.
400 / 415Nederīgs JSON / pieprasījums nav application/json.
404Nezināma, melnraksta, nepublicēta vai nederīga veidlapa.
409Konts ir sasniedzis kontaktu ierobežojumu.
413 / 422Saturs pārsniedz 16 KiB / piekrišana vai lauku dati nav derīgi.
429Sasniegts pieprasījumu ierobežojums; pārlūkprogrammas kods var izmantot retry_after JSON saturā. Servera integrācijas var arī nolasīt Retry-After.

Kļūdas izmanto {"error":true,"message":"..."}; pieprasījumu ierobežojuma kļūdas ietver arī retry_after sekundēs. Veidlapām ir atļauti līdz 30 pieprasījumiem no vienas IP adreses minūtē, tostarp līdz 10 iesniegumiem. Jūsu vietnes satura drošības politikai jāatļauj https://api.smartest.email iekš connect-src; gatavajam iegultajam logrīkam tas vajadzīgs arī iekš script-src.

Kad jūsu serveris pārsūta iesniegumus, tiem tiek piemērots kopīgs pieprasījumu ierobežojums pēc šī servera izejošās IP adreses.

Piekrišana un piegāde

Jauna pieņemta reģistrācija izveido abonētu kontaktu un saglabā veidlapas piekrišanas tekstu, laiku un norādīto pieprasījuma izcelsmi. Jūsu saskarnei pirms iesniegšanas jāparāda veidlapas piekrišanas teksts un privātuma paziņojums. Reģistrētā pieprasījuma izcelsme nav identitātes pierādījums. Šis galapunkts izmanto vienpakāpes pieteikšanos; tas nesūta apstiprinājuma e-pastu un nepārbauda adreses piederību.