# Form

Un form che costruisci nella dashboard, pubblichi al suo link e incorpori dove vuoi. Ogni invio arriva come notifica push sul tuo telefono, passando dallo stesso percorso di un webhook: instradamento, livelli di priorità e cronologia dei messaggi funzionano come già conosci.

Niente casella email di mezzo. Niente controllare un foglio di calcolo.

## Crea un form

**Forms → Create.** Il builder ha cinque schede e un'anteprima in tempo reale accanto:

| Scheda | Cosa contiene |
|--------|---------------|
| Fields | Titolo, testo introduttivo, i campi, testo del piè di pagina |
| Design | Tema, colori, font, dimensione, raggio degli angoli, pulsante di invio |
| Settings | Titolo push, instradamento, priorità, limiti di risposta, messaggi |
| Share | Link pubblico, codice QR, codice di incorporamento |
| Preview | La stessa anteprima in tempo reale, per schermi stretti |

Salva e la scheda Share ti fornisce il link: `https://frms.click/<id>`.

## Tipi di campo

| Gruppo | Tipi |
|--------|------|
| Testo | Testo breve, testo lungo, email, telefono, numero, URL, data |
| Scelta | Menu a tendina, pulsanti radio, caselle di controllo, casella singola (consenso) |
| Valutazione | Valutazione a stelle (1–5), NPS (0–10) |
| Layout | Titolo, paragrafo, separatore |
| Tracciamento | Campo nascosto |

Fino a **30 campi** per form, fino a 50 opzioni in un campo di scelta. I campi email, telefono, numero e URL vengono validati nel browser e di nuovo sul server: il controllo lato client è una comodità, non la protezione.

I campi di layout sono solo decorativi: non compaiono mai nel messaggio. Caricamento di file e pagamenti non sono supportati.

### Campi nascosti

Un campo nascosto porta un valore dal link al messaggio. Assegnagli un nome di parametro e `?utm_source=newsletter` nell'URL arriva nella notifica. Con un clic aggiungi tutti e cinque i parametri UTM insieme.

Quando un form è incorporato, i parametri della **pagina ospitante** vengono passati, quindi una landing page di campagna etichetta da sola i propri invii senza alcun lavoro da parte tua.

## Come appare il messaggio

Prima le risposte, nell'ordine in cui compaiono i campi:

```
Name: Jane Doe
Email: jane@example.com
Rating: ★★★★☆ 4/5
Message: Do you ship to Canada?

utm_source: newsletter
Form: Contact
IP: 203.0.113.10
Submitted: 2026-09-23 14:05
```

I campi nascosti, l'IP del visitatore e il timestamp stanno in fondo, dopo le risposte. Il timestamp usa il fuso orario del tuo account. Tutto è cifrato a riposo con la tua chiave personale, esattamente come ogni altro messaggio.

## Titolo push

Per impostazione predefinita la notifica ha come titolo `Form: <form name>`. Un template lo rende utile a colpo d'occhio:

```
New lead: {Name} ({Email})
```

I token fanno riferimento ai campi **tramite la loro etichetta**, senza distinzione tra maiuscole e minuscole, più `{form}` per il nome del form. Le risposte vuote vengono omesse dal titolo; se non resta nulla, si usa il titolo predefinito. Il template non è mai esposto nella pagina pubblica.

## Il badge di Pocket Alert

Una pagina pubblicata mostra sotto di sé un piccolo link "Powered by Pocket Alert". Con un piano a pagamento puoi disattivarlo in **Design → Branding**.

Decide l'API, non il browser: salvare il flag con il piano gratuito lo reimposta, e se un piano a pagamento scade il badge ricompare sulla pagina pubblica senza che tu tocchi il form.

## Instradamento e priorità

Un form può puntare a un'applicazione e a un dispositivo specifico, e può avere un livello di priorità da silenzioso a critico, gli stessi livelli dell'API. Lascia il livello su *Default* e il form segue le tue regole di consegna abituali.

Ogni invio consuma un messaggio dalla tua quota giornaliera. Quando la quota è esaurita, il visitatore vede un generico messaggio "riprova più tardi" senza alcun riferimento al tuo piano, e tu ricevi la solita email di limite raggiunto.

## Chiudere un form

Tre interruttori indipendenti, uno qualsiasi dei quali lo chiude:

- **Accepting responses**: disattivato lo chiude immediatamente
- **Response limit**: si chiude dopo N invii; lo slot viene riservato prima che il messaggio venga creato, quindi un picco di traffico non può superarlo
- **Close on**: una data e un orario nel tuo fuso orario

Un form chiuso resta comunque raggiungibile: i visitatori vedono il tuo messaggio di chiusura al posto dei campi, e gli invii vengono rifiutati lato server.

## Incorporamento

La scheda Share ti fornisce un embed tramite script:

```html
<div data-pocketalert-form="<id>"></div>
<script src="https://frms.click/embed/form.js" async></script>
```

Il form si carica in un iframe che comunica la propria altezza, quindi non c'è una scrollbar interna né un'altezza fissa da mantenere. Lo sfondo della pagina resta visibile: imposta il colore della card del form su tonalità trasparenti-friendly e si integra.

Dopo un invio il contenitore emette un evento `pocketalert:submit` a cui puoi agganciare l'analytics:

```js
document.querySelector('[data-pocketalert-form]')
  .addEventListener('pocketalert:submit', () => gtag('event', 'generate_lead'));
```

Dove gli script non sono consentiti, è disponibile anche uno snippet `<iframe>` semplice: altezza fissa, e i parametri dell'URL non vengono passati.

## Limitare dove si può usare il form

L'id di un form è pubblico — viaggia nel link e nel codice QR — quindi per impostazione predefinita chiunque lo abbia può incorporare il form in qualsiasi pagina. **Settings → Where it can be used** accetta un elenco di domini e lo chiude:

- solo quei siti possono incorporare il form (la pagina viene servita con una policy `frame-ancestors` corrispondente);
- un invio il cui `Origin` (o `Referer`) non è nell'elenco viene rifiutato con `403`;
- il link diretto del form continua a funzionare comunque.

Scrivi host, non URL: `example.com`, `app.example.com`, `*.example.com` per ogni sottodominio, `localhost:3000` mentre sviluppi. Fino a 10 voci. `www.` viene ignorato, quindi `example.com` copre `www.example.com`.

Un elenco vuoto significa "ovunque", che è l'impostazione giusta per un link che condividi in una bio o un codice QR su un poster.

> **Warning: Cosa blocca e cosa non blocca**
>
> `Origin` è impostato dal browser e una pagina non può falsificarlo. Uno script che parla direttamente con l'API può inviare qualsiasi header desideri, quindi l'elenco consentiti impedisce che il tuo form venga incorporato sul sito di qualcun altro — non è una difesa contro un flooder determinato. I rate limit qui sotto coprono quel caso.

## Da dove arriva un invio

Quando un invio arriva da un form incorporato, l'host viene registrato nel messaggio accanto all'IP:

```
Form: Contact (abc123)
Source: shop.example.com
IP: 203.0.113.10
```

Gli invii dalla pagina diretta del form non hanno la riga `Source`.

## Protezione dallo spam

- Un campo honeypot che nessun essere umano vede. I bot che lo compilano ricevono una schermata di successo dall'aspetto normale e non viene consegnato nulla.
- Rate limit: 10 invii al minuto da un singolo IP, 60 al minuto e 300 all'ora per form. Il tetto orario esiste perché un flood non possa esaurire la quota di un'intera giornata in pochi minuti.
- Le pagine pubbliche dei form sono `noindex`, quindi un form non compare da solo nei risultati di ricerca.

Il CAPTCHA non è richiesto e, per ora, non è offerto sui form.

## Limiti del piano

| Piano | Form |
|-------|------|
| Gratuito | 1 |
| Starter | 10 |
| Medium | 30 |
| Large | Illimitati |

Gli invii in sé sono limitati solo dalla tua quota giornaliera di messaggi.

## API

Tutto ciò che fa il builder è disponibile tramite la REST API:

| Endpoint | Cosa fa |
|----------|---------|
| [`GET /v1/forms`](https://info.pocketalert.app/api/forms/get-forms.md) | Elenca i tuoi form |
| [`POST /v1/forms`](https://info.pocketalert.app/api/forms/create.md) | Crea un form |
| [`PUT /v1/forms/:tid`](https://info.pocketalert.app/api/forms/update.md) | Sostituisce campi, design e impostazioni |
| [`DELETE /v1/forms/:tid`](https://info.pocketalert.app/api/forms/delete.md) | Elimina il form |
| [`GET /v1/forms/:tid`](https://info.pocketalert.app/api/forms/get-form.md) | Pubblico: campi e design di un form attivo |
| [`POST /v1/forms/:tid/submit`](https://info.pocketalert.app/api/forms/submit.md) | Pubblico: accetta un invio |

I primi quattro usano il tuo token normale; gli ultimi due sono quelli che chiama la pagina del form stessa.
