Vai al contenuto principale
Italiano

Custom Captive Portal: HTML and CSS Guide

Questa guida di riferimento tecnica e autorevole definisce gli standard di sviluppo, l'architettura CSS e i vincoli a livello di rete necessari per progettare e codificare una landing page di un Captive Portal personalizzato. Fornisce a sviluppatori frontend e architetti di rete strategie pratiche per navigare negli ambienti Apple CNA e webview Android, garantendo esperienze WiFi per gli ospiti perfette al pixel, conformi e altamente performanti.

📖 11 minuti di lettura📝 2,731 parole🔧 2 esempi pratici❓ 3 domande di esercitazione📚 8 definizioni chiave

Ascolta questa guida

Visualizza trascrizione del podcast
Custom Captive Portal: HTML and CSS Guide — A Purple Technical Briefing [INTRODUCTION] Welcome to the Purple Technical Briefing series. Today we are getting into the weeds on something that affects every single guest WiFi deployment — the captive portal. Specifically, we are talking about how to write clean, reliable HTML and CSS for a custom captive portal landing page. If you have ever connected to hotel WiFi and been greeted by a broken splash page — missing images, unstyled text, a login button that does not respond to touch — you have experienced what happens when a developer builds a portal without understanding the constraints of the environment it runs in. Today, we are going to make sure that does not happen to you. This briefing is aimed at frontend developers, creative designers, and web developers who are either building a captive portal from scratch or customising an existing template. We will cover the HTML structure, the CSS rules that matter, the Apple CNA mini-browser constraints that trip up even experienced developers, and how platforms like Purple's portal builder can eliminate most of this complexity entirely. Let us get into it. [TECHNICAL DEEP-DIVE] First, let us establish what a captive portal actually is at the network level. When a device connects to a WiFi network that requires authentication, the network intercepts HTTP traffic and redirects the user to a landing page. This is the captive portal. The user sees a splash page, completes an action — entering an email, accepting terms, logging in via social — and the network then grants full internet access. The critical thing to understand is where this page is rendered. On iOS devices, it opens inside Apple's Captive Network Assistant — the CNA — which is a stripped-down WebKit webview. It is not Safari. It has no persistent cookies. It cannot load external resources. It has limited JavaScript support. And it closes the moment the user switches to another app. On macOS, the CNA renders at a fixed 900 by 572 pixels. On Android, modern devices use Chrome Custom Tabs, which are considerably more capable. Windows 10 opens the user's default browser. Samsung devices use Samsung Internet. This platform fragmentation is the single biggest source of broken captive portals in production. Developers test on their Android phone, everything looks great, and then the hotel's iPhone-toting guests get a white screen with unstyled text. So let us talk about how to code defensively. The golden rule for captive portal HTML and CSS is this: treat the page as if it has no internet connection. Because during the authentication phase, it does not. The network is captive. Any resource your page tries to load from an external URL — a Google Font, a CDN-hosted stylesheet, a JavaScript library, a logo image — will fail silently or cause a loading spinner that never resolves. Starting with the HTML structure. Your document should be a clean HTML5 page. In the head, you need a viewport meta tag with content set to width equals device-width and initial-scale equals one. This is non-negotiable for mobile rendering. Without it, iOS will render the page at 980 pixels wide and scale it down, making everything microscopic. Your CSS must be inline — either in a style block within the head element, or as inline style attributes on individual elements. Do not use an external stylesheet linked via a link tag. That stylesheet lives on your server, which the captive network cannot reach during authentication. The page will render completely unstyled. For fonts, use a system font stack. Something like: font-family — apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Helvetica Neue, Arial, sans-serif. This tells the browser to use whatever system font is available. Do not use Google Fonts. The import call will fail, and your fallback font will be Times New Roman, which is not the brand experience your client is paying for. For images — your logo, background graphics, decorative elements — you have two options. Either serve them from the same captive portal server, which means they are on the same local network and accessible before authentication completes. Or, better, encode them as Base64 data URIs directly in your HTML or CSS. This eliminates the external dependency entirely. Now let us talk about the page layout. Since over ninety percent of captive portal logins happen on mobile devices, your design should be mobile-first. That means a single-column layout, a maximum width of around 480 pixels, centred on the page. Use flexbox on the body element — display flex, flex-direction column, align-items centre, justify-content centre, min-height 100 viewport height. This centres your content card vertically and horizontally on any screen size. Your primary call-to-action button needs to be touch-friendly. Apple's Human Interface Guidelines specify a minimum tap target of 44 by 44 pixels. In practice, for a primary CTA, you want something more like 48 pixels tall, full width within the container, with a border-radius of around 8 to 12 pixels. For form fields — email input, name input — set the font-size to at least 16 pixels. This is critical. iOS Safari and the CNA will automatically zoom in on any input field with a font-size below 16 pixels, which breaks your carefully crafted layout. Setting font-size to 16 pixels or above prevents this zoom behaviour. The legal consent section deserves particular attention. Under GDPR, if you are collecting personal data — even just an email address — you need explicit, informed consent. This means a checkbox that is unchecked by default, with a visible label that clearly states what the user is consenting to. Do not pre-tick the checkbox. The consent checkbox itself must be clearly visible without scrolling. Now, a critical implementation detail for iOS CNA specifically. When the user completes authentication, the CNA monitors whether the captive domain has become accessible. The check is triggered by full page navigation, not by JavaScript AJAX calls. This means if you build a single-page app that submits the form via fetch or XMLHttpRequest and updates the DOM without a full page redirect, the CNA will never detect that authentication has completed. You must redirect to a new URL after authentication — a full HTTP redirect, not a JavaScript DOM manipulation. This is one of the most common mistakes in captive portal development. For JavaScript, keep it minimal. The CNA has limited JS support and no access to localStorage or sessionStorage. Cookies are destroyed when the CNA closes. Any state management that relies on these browser APIs will fail. Vanilla JavaScript event listeners are fine. jQuery is a 30-kilobyte external dependency that will fail to load. [IMPLEMENTATION RECOMMENDATIONS AND PITFALLS] Let me give you the practical implementation checklist. First: viewport meta tag, always. Second: all CSS inline, no external stylesheets. Third: all images either served from the captive portal server or Base64-encoded. Fourth: system font stack, no web fonts. Fifth: minimum 16 pixel font size on all input fields. Sixth: touch-friendly tap targets, minimum 44 by 44 pixels. Seventh: single column layout, max-width 480 pixels. Eighth: full page redirect on authentication, not a JavaScript state update. Ninth: GDPR-compliant consent checkbox, unchecked by default. Tenth: test on a real iOS device using an actual captive network, not a browser preview. The pitfalls I see most often in production. Number one: Google Fonts — remove the import, it will fail. Number two: external JavaScript libraries — Bootstrap, jQuery, any CDN-hosted script will fail. Number three: CSS variables declared in an external stylesheet — they must be in your inline style block. Number four: background images referenced by URL — Base64 encode them. Number five: AJAX form submission without a post-authentication redirect — the CNA will not detect authentication completion. Now, the honest conversation about building versus buying. Building a custom captive portal from scratch means you are also responsible for the backend infrastructure — the RADIUS server, the database, the SSL certificate, the DNS configuration, the network integration with your access points, and the ongoing security patching. This is a significant engineering commitment. Purple's portal builder gives you a drag-and-drop interface with a custom HTML and CSS editor for developers who need pixel-perfect control, while handling all of the backend infrastructure — the authentication, the data capture, the analytics, the GDPR compliance tooling, and the network integrations with over 200 access point vendors. You get the creative control without the infrastructure overhead. [RAPID-FIRE Q AND A] Can I use CSS Grid in a captive portal? Yes, but test on iOS CNA specifically. Flexbox has broader support in older WebKit versions. Can I use SVG logos? Yes, inline SVGs are fully supported and preferable to Base64-encoded PNGs for logos because they scale perfectly on retina displays. Does the macOS CNA support the same constraints as iOS CNA? Broadly yes, with one difference: macOS CNA renders at a fixed 900 by 572 pixel window. Can I use a CSS framework like Tailwind? Only if you generate a purged, self-contained CSS file and inline it in your style block. What about HTTPS? Your captive portal must be served over HTTP for the initial redirect to work — HTTPS connections cannot be intercepted by the captive network. [SUMMARY AND NEXT STEPS] To summarise today's briefing. A custom captive portal is a constrained web environment, not a standard browser context. The Apple CNA and Android webviews impose strict limitations on external resources, cookies, JavaScript, and session state. The solution is to build self-contained HTML pages with inline CSS, system fonts, Base64-encoded images, and full-page redirects on authentication. For venue operators and IT teams evaluating their options: if your requirement is a fully branded, bespoke portal with custom HTML and CSS, the choice is between building and maintaining the full stack yourself — which is a substantial engineering commitment — or using a platform like Purple that provides the custom HTML and CSS editing capability on top of a production-grade backend infrastructure. The next steps from here: review Purple's portal editor documentation, audit your existing portal against the mobile-first checklist we covered today, and if you are starting from scratch, use the HTML template structure we outlined as your baseline. Thanks for listening, and we will see you in the next briefing.

📚 Part of our core series: La guida definitiva ai Captive Portal →

header_image.png

Executive Summary

Per le sedi aziendali—che spaziano dagli hotel di lusso Hospitality e catene di negozi Retail agli hub di transito Transport e moderni campus medici Healthcare —la splash page WiFi per gli ospiti rappresenta la porta d'ingresso digitale. Tuttavia, oltre il 90% degli accessi WiFi degli ospiti avviene su dispositivi mobili, dove il rendering non è gestito da browser standard come Safari o Chrome, ma da webview Captive Network Assistant (CNA) altamente limitate [1]. Questi "mini-browser" impongono severe limitazioni di sandbox: bloccano le CDN esterne, disabilitano i cookie persistenti, ignorano i web font esterni e limitano fortemente l'esecuzione di JavaScript per mitigare i rischi di sicurezza e prevenire il dirottamento delle sessioni (session hijacking) [2].

Quando uno sviluppatore progetta una splash page utilizzando i tradizionali standard web, questi vincoli si traducono in layout interrotti, elementi del brand mancanti e pulsanti di accesso non funzionanti, con un impatto diretto sulla soddisfazione del cliente e sul coinvolgimento digitale. Questa guida fornisce soluzioni a queste sfide, presentando pratiche di codifica difensive—come CSS inline, codifica degli asset in Base64, stack di font di sistema e handshake di autenticazione espliciti basati sulla navigazione—per garantire un rendering multipiattaforma fluido. Inoltre, esaminiamo come l'utilizzo di una soluzione gestita come il portal builder di Purple consenta agli sviluppatori di mantenere il controllo creativo completo su HTML/CSS, delegando al contempo l'autenticazione RADIUS, la scalabilità del database, la conformità GDPR/PCI e le integrazioni AP multi-vendor [3].

Technical Deep-Dive

Per creare un Captive Portal personalizzato resiliente, gli sviluppatori devono comprendere l'intercettazione a livello di rete e la virtualizzazione del browser che si verificano quando un ospite si associa a un Service Set Identifier (SSID) aperto.

Il ciclo di vita del Captive Portal

Quando un dispositivo client si associa a un SSID captive, viene attivata la seguente sequenza:

  1. Associazione IP: il dispositivo completa un handshake a 3 vie e richiede un indirizzo IP tramite DHCP.
  2. Probe di connettività attiva: il gestore di rete in background del sistema operativo invia immediatamente una richiesta HTTP GET a un URL canary dedicato e neutrale rispetto al fornitore (ad es. http://captive.apple.com/hotspot-detect.html di Apple o http://connectivitycheck.gstatic.com/generate_204 di Google) [1].
  3. Intercettazione DNS/HTTP: il Wireless LAN Controller (WLC) o l'Access Point (AP) locale intercetta questa richiesta HTTP sulla porta 80. Invece di restituire lo stato HTTP 200 o 204 previsto, il gateway reindirizza il traffico del client all'URL della landing page del Captive Portal tramite un reindirizzamento HTTP 302 [2].
  4. Generazione della Webview: rilevando il reindirizzamento, il sistema operativo avvia il suo mini-browser nativo Captive Network Assistant (CNA) per visualizzare la splash page reindirizzata, evitando che l'utente debba aprire manualmente un browser completo.
  5. Autenticazione e transizione di stato: l'utente compila il modulo di accesso, inviando le credenziali al server del portale, che istruisce il gateway (spesso tramite un Access-Accept RADIUS o una chiamata API esterna) ad autorizzare l'indirizzo MAC.
  6. Handshake di uscita CNA: il mini-browser CNA esegue un'altra richiesta HTTP GET al suo URL canary. Se riceve la risposta 200/204 prevista, cambia il pulsante in alto a destra da "Annulla" a "Fine" e stabilisce la connessione WiFi como interfaccia di rete primaria.

Vincoli dei mini-browser specifici per piattaforma

Ogni sistema operativo gestisce questo ciclo di vita all'interno di diversi ambienti webview, con un comportamento altamente frammentato. La tabella seguente illustra in dettaglio questi vincoli critici:

Piattaforma / Webview Metodo di visualizzazione Cookie persistenti Web font esterni Esecuzione JavaScript Dimensioni della finestra Trigger dell'handshake di uscita
Apple iOS CNA (Websheet) Popup mini-browser Bloccato (Distrutto alla chiusura) Bloccato (Offline) Limitato (Nessun localStorage/sessionStorage) Responsive (Larghezza dispositivo) Solo reindirizzamento HTTP a pagina intera [1]
Apple macOS CNA (Captive Network Assistant) Popup mini-browser Bloccato Bloccato Limitato (Nessuna finestra di dialogo alert/confirm) Fisso (900px x 572px) Solo reindirizzamento HTTP a pagina intera
Android (Google) (CaptivePortalLogin) Notifica push -> Scheda personalizzata Chrome Consentito (Condiviso con Chrome) Consentito (Se inserito nella whitelist del walled garden) Completa Responsive Automatico (API Captive Portal / Controllo 204) [2]
Samsung Android (Samsung Internet) Notifica push -> Mini-browser Consentito Consentito Completa Responsive Automatico
Windows 10/11 (Browser predefinito) Avvio automatico del browser predefinito Consentito (Contesto browser completo) Consentito Completa Responsive Manuale / Automatico

cna_constraints_comparison.png

Aggirare la trappola del pulsante "Fine" di Apple CNA

Uno dei problemi di malfunzionamento più frequenti nello sviluppo di portali personalizzati è la trappola del pulsante "Fine" sui dispositivi iOS. Quando un utente si autentica, la webview Websheet di iOS deve rilevare che la rete non è più captive. Lo fa monitorando il successo delle sue richieste canary in background.

In modo cruciale, l'iOS CNA attiverà questo controllo solo in seguito a una navigazione HTTP a pagina intera (reindirizzamento della posizione). Se uno sviluppatore crea una moderna Single Page Application (SPA) che invia i dati del modulo tramite una chiamata AJAX asincrona (ad es. fetch() o Axios) e aggiorna il DOM in modo dinamico senza modificare l'URL, il CNA non eseguirà mai nuovamente il controllo di connettività. L'utente sarà autenticato a livello di gateway, ma il pulsante CNA nell'angolo in alto a destra rimarrà impostato su "Annulla". Se l'utente frustrato fa clic su "Annulla", il dispositivo iOS si disassocdissociarsi dall'SSID, terminando la sessione WiFi [1].

Per evitare questo problema, l'handler di autenticazione riuscita deve eseguire un reindirizzamento a pagina intera verso una landing page fisica (ad es. window.location.href = '/success') o inviare il modulo di login in modo nativo tramite un'azione HTTP POST standard.

Guida all'implementazione

Per garantire un rendering coerente su tutte le piattaforme, gli sviluppatori devono passare da un web design moderno e ricco di risorse a uno stile di codifica altamente autonomo e difensivo.

La regola d'oro: progettare per l'assenza di connettività Internet

Durante lo stato captive, il dispositivo client non ha accesso a Internet. Può solo risolvere e accedere agli indirizzi IP e ai domini esplicitamente inseriti nella whitelist del Walled Garden del controller wireless (come l'IP del server del Captive Portal stesso). Pertanto, qualsiasi risorsa esterna a cui si fa riferimento nell'HTML non verrà caricata, compromettendo il layout della pagina.

Per progettare in modo difensivo, implementa la seguente Checklist per la progettazione di Captive Portal Mobile-First:

mobile_first_checklist.png

1. Configurazione del Viewport

Per evitare che i dispositivi mobili riducano il viewport alla larghezza desktop (in genere 980px), l' `` HTML deve includere un meta tag viewport responsive. Senza questo, il testo e i campi di input appariranno microscopici sui dispositivi mobili:

2. Inserimento del CSS inline e rimozione delle dipendenze esterne

Non collegare mai file CSS esterni o CDN (ad es. Bootstrap, Tailwind o Google Fonts). Tutto il CSS deve essere incorporato all'interno di un blocco `

<div class="portal-card">
    <div class="logo-container">
        
        
            
            IL TUO BRAND
        
    </div>
    
    <h1>Benvenuto nel Guest WiFi</h1>
    <p>Inserisci i tuoi dati qui sotto per ottenere un accesso a internet sicuro e ad alta velocità.</p>
    
    
    
        <div class="form-group">
            Nome completo
            
        </div>
        
        <div class="form-group">
            Indirizzo e-mail
            
        </div>
        
        <div class="consent-group">
            
            
                Accetto i <a href="#">Termini di servizio</a> e acconsento al trattamento dei dati in conformità con le normative GDPR.
            
        </div>
        
        <div id="terms_box" class="terms-scrollbox">
            <strong>Termini di servizio WiFi:</strong><br />
            1. Il servizio viene fornito "così com'è" senza alcuna garanzia.<br />
            2. Gli utenti non devono svolgere attività illegali ad alto consumo di banda.<br />
            3. I dati personali sono raccolti esclusivamente per scopi di autenticazione e opt-in di marketing in conformità con la nostra Informativa sulla privacy.
        </div>
        
        Connettiti al WiFi
    
    
    <div class="footer">
        Powered by Purple | Guest WiFi sicuro
    </div>
</div>


## Risoluzione dei problemi e mitigazione dei rischi

Durante l'implementazione di Captive Portal HTML/CSS personalizzati, i team di IT operations riscontrano frequentemente diversi gravi rischi operativi:

### 1. Il loop di avviso del certificato SSL/TLS

Poiché i Captive Portal funzionano intercettando il traffico, presentano un conflitto fondamentale con la moderna sicurezza web HTTPS. Quando un utente tenta di visitare un sito HTTPS (ad es. `https://www.google.com`) e il gateway tenta di reindirizzare tale traffico a un Captive Portal HTTP, il browser rileva una mancata corrispondenza nel certificato SSL e mostra un avviso di sicurezza critico "La connessione non è privata". 

* **Mitigazione**: Non tentare mai di intercettare direttamente il traffico HTTPS. Affidati interamente all'helper CNA nativo del sistema operativo (che effettua una richiesta HTTP non crittografata per attivare il reindirizzamento). Assicurati che il dominio del tuo Captive Portal abbia un certificato SSL valido e pubblicamente attendibile (ad es. Let's Encrypt o DigiCert) e che sia servito tramite HTTPS *solo dopo* che il reindirizzamento HTTP iniziale ha indirizzato con successo l'utente al dominio del tuo portale [2].

### 2. Errori di risoluzione DNS (La trappola del Walled Garden)

Se la tua pagina HTML personalizzata fa riferimento a risorse esterne, come un endpoint OAuth di social login (ad es. Facebook, Google) o un gateway di pagamento, le richieste DNS per questi domini falliranno a meno che non siano esplicitamente incluse nella whitelist del Walled Garden del controller wireless. Se un dominio manca dalla whitelist, il flusso di accesso si bloccherà, mostrando una schermata vuota.

* **Mitigazione**: Mantieni un elenco di Walled Garden rigoroso e ridotto al minimo. Se utilizzi i social login, inserisci nella whitelist i domini jolly specifici consigliati dagli identity provider (ad es. `*.google.com`, `*.gstatic.com`). 

### 3. Vulnerabilità di timeout della sessione e spoofing MAC

I Captive Portal standard autenticano i dispositivi in base ai loro indirizzi MAC. Tuttavia, i moderni sistemi operativi mobili (iOS 14+ e Android 10+) utilizzano per impostazione predefinita indirizzi MAC casuali (indirizzi WiFi privati), ruotandoli periodicamente. Ciò può far sì che agli ospiti venga richiesto ripetutamente di autenticarsi nuovamente, compromettendo l'esperienza utente [1].

* **Mitigazione**: Implementa timeout di sessione ragionevoli (ad es. 24 ore) sul server RADIUS per prevenire sessioni obsolete e utilizza standard di autenticazione moderni come **Passpoint (Hotspot 2.0)** o **WPA3-Enterprise** per un onboarding fluido e sicuro che aggiri completamente i Captive Portal basati su MAC.

## Rilevanza del prodotto Purple: Build vs. Buy

Sebbene la codifica di una singola pagina HTML sia semplice, l'hosting, la sicurezza e la scalabilità di un'infrastruttura di Captive Portal personalizzata presentano enormi ostacoli tecnici e di conformità. La tabella seguente confronta le realtà ingegneristiche e operative dell'hosting autonomo di un portale personalizzato rispetto all'utilizzo della piattaforma enterprise gestita di Purple:

| Funzionalità / Requisito operativo | Portale personalizzato in self-hosting | Piattaforma WiFi enterprise Purple |
| :--- | :--- | :--- |
| **Personalizzazione HTML/CSS** | Codifica completamente manuale, caricamento di file su singoli AP o server web locali. | **Editor per sviluppatori pixel-perfect** che consente inserimenti HTML/CSS personalizzati, combinato con un builder visivo drag-and-drop.
| **Infrastruttura RADIUS** | È necessario implementare, configurare e mantenere server FreeRADIUS o Cloud RADIUS ad alta disponibilità [4]. | **RADIUS nativo del cloud, integrato e distribuito a livello globale** con ridondanza active-active e SLA di uptime del 99,99%.
| **Supporto AP multi-vendor** | Script di integrazione personalizzati richiesti per ciascun fornitore di hardware (Cisco, Aruba, Meraki, Ruckus) [5]. | **Integrazione nativa e immediata** con oltre 200 hardware models; implementazione unificata del portale su parchi hardware misti.
| **Privacy dei dati e conformità** | La location si assume il 100% della responsabilità legale per la conformità a GDPR, CCPA e PCI DSS, inclusi la crittografia sicura del database e i flussi di lavoro di eliminazione dei dati. | **Completamente conforme fin dalla progettazione**. Gestione del consenso integrata, richieste automatizzate di eliminazione dei dati degli interessati e hosting sicuro certificato ISO 27001.
| **Analisi e marketing** | Richiede la creazione di pipeline di acquisizione dati personalizzate e l'integrazione di strumenti di marketing di terze parti. | **Dashboard di analisi di livello enterprise** con tracciamento delle presenze in tempo reale, metriche sul tasso di ritorno e trigger automatizzati per campagne di marketing [6].
| **Integrazioni con Identity Provider** | Integrazioni OAuth2 manuali con Google, Facebook, Apple e gateway SMS locali. | **Integrazioni con un clic** con le principali piattaforme social, gateway SMS e Azure AD / Okta per gli ospiti aziendali.

La piattaforma di Purple risolve il dilemma "Build vs. Buy". Offre agli sviluppatori la completa libertà creativa di uno spazio di lavoro HTML/CSS personalizzato, eliminando al contempo la complessa e rischiosa ingegnerizzazione dell'infrastruttura backend necessaria per supportare l'autenticazione RADIUS sicura su scala.

## ROI e impatto aziendale

L'investimento in un Captive Portal personalizzato, reattivo e progettato in modo professionale offre ritorni quantificabili in termini di IT operations, marketing e conformità legale.

### 1. Riduzione dei costi operativi (ticket dell'helpdesk IT)

Nelle implementazioni su larga scala, come uno stadio o una catena di vendita al dettaglio multi-sito, un Captive Portal non funzionante è una delle cause principali dell'aumento dei ticket di assistenza all'helpdesk IT. Quando gli ospiti riscontrano una "schermata bianca" o un pulsante di accesso che non risponde, sovraccaricano il personale in loco o inviano ticket di supporto.

$$\text{Annual Support Savings} = (\text{Total Annual Guest Visits} \times \text{Portal Failure Rate} \times \text{Helpdesk Contact Rate}) \times \text{Cost Per Support Ticket}$$

* **R**Scenario**: un centro congressi con 1.000.000 di visitatori annuali. Un portale codificato male ha un tasso di errore del 5% sui dispositivi iOS più vecchi, il che porta a un tasso di contatto dell'helpdesk del 10%. Con uno standard di settore di $15 per ticket di supporto, il costo operativo è:
  $$(1,000,000 \times 0.05 \times 0.10) \times \$15 = \$75,000 \text{ all'anno in costi di supporto evitabili}$$
* **Risultato**: il passaggio a un modello ottimizzato per CNA e mobile-first riduce il tasso di errore del portale a &lt;0,1%, eliminando virtualmente questo spreco operativo.

### 2. Acquisizione dei dati di marketing e ottimizzazione dell'opt-in

Per i settori retail e hospitality, il Captive Portal WiFi per gli ospiti è il meccanismo principale per acquisire dati puliti di prima parte sui clienti. Un'interfaccia utente progettata male, con testi microscopici o un layout dei moduli macchinoso, causa elevati **tassi di rimbalzo** (bounce rate): gli utenti abbandonano completamente il processo di accesso, con una conseguente perdita di opportunità di marketing.

* **Caso di studio (Retail)**: una catena di vendita al dettaglio nazionale ha implementato un captive portal ottimizzato per dispositivi mobili (mobile-first) utilizzando la piattaforma di Purple. Sostituendo un modulo di accesso in più passaggi con un campo di inserimento email singolo (font-size: 16px) e un pulsante tap-target ottimizzato da 48px, ha registrato un **incremento del 42% delle registrazioni completate** e un **incremento del 28% delle iscrizioni alla newsletter di marketing** nel primo trimestre [6].

### 3. Mitigazione dei rischi legali e normativi

In base al GDPR e al CCPA, la raccolta di dati non conforme comporta severe sanzioni finanziarie (fino al 4% del fatturato annuo globale ai sensi del GDPR). Affidarsi a caselle di controllo preselezionate o non fornire un'Informativa sulla privacy chiara e facilmente accessibile sulla splash page espone l'azienda a enormi responsabilità legali.

* **ROI della mitigazione**: l'implementazione di una casella di controllo del consenso esplicita e non preselezionata e l'hosting dei termini all'interno di uno scrollbox ottimizzato garantiscono la conformità normativa al 100%, mitigando il rischio di sanzioni multimilionarie e proteggendo la reputazione del brand.

## Sintesi dei punti chiave

* **La sandbox CNA è restrittiva**: Websheet di iOS di Apple e CNA di macOS sono ambienti altamente isolati (sandboxed) che bloccano risorse esterne, cookie e web font. Tutti gli stili e le risorse devono essere autonomi (CSS inline, immagini Base64, font di sistema) [1].
* **AJAX interrompe l'handshake di uscita di iOS**: per far passare con successo il dispositivo iOS da "captive" a "connesso" (cambiando il pulsante in alto a destra da "Annulla" a "Fine"), è necessario attivare un reindirizzamento HTTP a pagina intera. Gli aggiornamenti asincroni del DOM lasceranno il dispositivo in un loop captive.
* **Il mobile-first è obbligatorio**: oltre il 90% degli accessi avviene da dispositivi mobili. Progetta un layout a colonna singola (max-width: 480px), utilizza target di tocco (tap target) ottimizzati per il touch (minimo 44px x 44px) e imponi una dimensione minima del carattere di 16px su tutti i campi di testo per impedire lo zoom automatico del browser iOS.
* **I Walled Garden controllano il DNS**: qualsiasi dominio esterno a cui si fa riferimento durante l'accesso (ad esempio, le API di login social) deve essere esplicitamente inserito nella whitelist del walled garden del controller wireless, altrimenti la pagina non verrà caricata.
* **Purple elimina la complessità del backend**: l'utilizzo del costruttore di portali di Purple offre agli sviluppatori il controllo completo di HTML/CSS tramite un editor personalizzato, eliminando al contempo gli immensi oneri di sicurezza, scalabilità e conformità di RADIUS, delle integrazioni AP multi-vendor e della gestione dei database conforme al GDPR [3].

## Riferimenti

* [1] [Wireless Broadband Alliance: Captive Network Portal Behavior](https://captivebehavior.wballiance.com/)
* [2] [Android Open Source Project: Captive Portal Login Webview Integration](https://source.android.com/docs/core/connect/android-custom-tabs-captive-portal)
* [3] [European Data Protection Board: Guidelines on Consent under Regulation 2016/679](https://edpb.europa.eu/our-work-tools/our-documents/guidelines/guidelines-052020-consent-under-regulation-2016679_en)
* [4] [Come implementare l'autenticazione 802.1X con Cloud RADIUS](/guides/implementing-8021x-with-cloud-radius)
* [5] [Cisco Wireless AP: Guida 2026 ai prodotti e all'implementazione](/blog/cisco-wireless-ap)
* [6] [Piattaforma di marketing e analisi Purple WiFi](/guest-wifi-marketing-analytics-platform)

---

## Ascolta il briefing tecnico

Ascolta un senior solutions architect che discute i vincoli tecnici e le strategie di implementazione per i captive portal personalizzati:

Definizioni chiave

Captive Portal

A web page that is displayed to newly connected users of a Wi-Fi network before they are granted broader access to network resources, typically used for authentication, payment, or displaying terms of service.

IT teams deploy captive portals at the gateway level to control guest access, capture user data, and enforce legal compliance.

Captive Network Assistant (CNA)

A highly restricted, sandboxed mini-browser spawned automatically by operating systems (such as Apple iOS and macOS) upon detecting a captive network redirect, designed solely to facilitate portal authentication.

CNA webviews enforce strict limitations, including blocking external CDNs, persistent cookies, and local storage, which frequently break standard web designs.

Walled Garden

A restricted list of IP addresses, subnets, or domain names that an unauthenticated guest user is permitted to access through the gateway before completing the captive portal login process.

Developers must ensure that any external resource (such as social login APIs or payment gateways) is whitelisted in the walled garden to prevent the login flow from stalling.

Base64 Encoding

A binary-to-text encoding scheme that represents binary data (such as images) as an ASCII string, allowing assets to be embedded directly within HTML or CSS documents.

Utilizing Base64 encoding for logos and icons eliminates external HTTP requests, ensuring assets render perfectly within offline CNA environments.

RADIUS (Remote Authentication Dial-In User Service)

A networking protocol that provides centralized Authentication, Authorization, and Accounting (AAA) management for users who connect and use a network service.

The captive portal server communicates with a RADIUS server to authorize the guest's MAC address at the network gateway once authentication criteria are met.

System Font Stack

A CSS font-family declaration that prioritizes pre-installed operating system fonts (such as San Francisco on iOS, Segoe UI on Windows, and Roboto on Android) over external web fonts.

Implementing a system font stack ensures immediate typography rendering without triggering blocked external HTTP requests to services like Google Fonts.

Canary URL

A dedicated, unencrypted HTTP URL maintained by operating system vendors (e.g., captive.apple.com) to test whether a device has unrestricted internet connectivity.

The OS background network manager checks this URL to detect the presence of a captive portal and trigger the CNA webview popup.

Passpoint (Hotspot 2.0)

An industry standard developed by the Wi-Fi Alliance that enables mobile devices to automatically discover and securely authenticate with Wi-Fi hotspots, bypassing manual captive portal logins.

Enterprises utilize Passpoint alongside platforms like Purple to transition guests from friction-heavy splash pages to seamless, cellular-like secure roaming experiences.

Esempi pratici

A luxury 250-room hotel chain [Hospitality](/industries/hospitality) wants to implement a custom guest WiFi login page that perfectly matches their premium brand guidelines. Their creative agency designed a splash page utilizing custom brand typography (hosted on Adobe Fonts), multiple high-resolution background images (hosted on a public AWS S3 bucket), and a multi-step animated JavaScript wizard. When deployed, iOS guests connect to the SSID, but the portal pops up as a blank white screen, and users are unable to authenticate.

To resolve the blank screen and broken branding, we must restructure the portal's frontend architecture to comply with the Apple CNA sandbox constraints:

  1. Typography Remediation: Since Adobe Fonts requires an external HTTP request that is blocked by the CNA, we replace the custom font call with a native, premium system font stack (font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif;). This ensures instant rendering without external network calls.
  2. Asset Optimization: The background images on AWS S3 are blocked because S3 is not in the gateway's walled garden. We compress the primary brand logo, convert it to a lightweight SVG, and encode it directly in the HTML as a Base64 Data URI. For the background, we replace the heavy images with a clean, responsive CSS gradient using the hotel's brand colors, significantly reducing page weight.
  3. JavaScript Simplification: The multi-step animated wizard relies on external jQuery and GSAP libraries. We strip out these external dependencies and refactor the form into a single-page, single-column HTML structure. Form validation is rewritten in lightweight, vanilla JavaScript.
  4. Authentication Handshake: The form submission is modified from an AJAX-based submission to a native HTML <form action="/submit" method="POST"> to trigger a full-page redirect, allowing the iOS Websheet to execute its canary check and display the 'Done' button.
Commento dell'esaminatore: This scenario represents the classic conflict between high-end creative design and the rigid security constraints of captive webviews. Creative agencies often treat the captive portal as a standard desktop website. However, because the device is in a pre-authenticated state, the network blocks all external traffic. By inlining CSS, system-stacking fonts, Base64-encoding assets, and utilizing native form submissions, we preserve the premium brand aesthetic while achieving 100% operational reliability on iOS and Android devices.

A national retail chain [Retail](/industries/retail) with 450 stores wants to capture guest emails via WiFi splash pages to fuel their CRM. They require guests to opt-in to marketing newsletters. The initial design has a pre-checked 'I agree to receive marketing emails' checkbox. Furthermore, the portal is hosted on a single local server in their headquarters. During peak hours (Saturday afternoon), guests across the country experience severe delays, and many are unable to load the login page, leading to a massive drop in data capture rates.

We must address both the compliance violation and the infrastructure bottleneck:

  1. Compliance Remediation: Under GDPR and CCPA, pre-checked consent boxes are illegal. We modify the HTML to make the marketing consent checkbox unchecked by default (<input type="checkbox" id="marketing_consent">). We also add a separate, mandatory checkbox for the Terms of Service to decouple legal agreement from marketing opt-in.
  2. Infrastructure Scaling: Hosting a national captive portal on a single centralized server creates a single point of failure and a massive latency bottleneck. We migrate the portal frontend to a highly available, globally distributed Content Delivery Network (CDN) with edge-caching.
  3. RADIUS Integration: We configure the local store access points to point to a cloud-native RADIUS cluster with active-active redundancy, ensuring that authentication requests are processed locally at the edge with sub-50ms latency, even during peak Saturday traffic.
  4. Purple Migration: To eliminate this entire engineering overhead, the retailer migrates to Purple. Purple's built-in GDPR consent tooling automatically manages compliant opt-ins, and their globally distributed cloud infrastructure handles millions of daily authentications with 99.99% uptime, completely resolving the scaling bottleneck.
Commento dell'esaminatore: Pre-checked consent checkboxes represent a severe compliance risk that can lead to massive regulatory fines. Decoupling marketing consent from the Terms of Service is a technical and legal best practice. On the infrastructure side, centralized hosting of captive portals is an anti-pattern. A nationwide retail footprint requires a decentralized, edge-cached frontend combined with a cloud-native RADIUS backend. Migrating to a managed platform like Purple eliminates this architectural complexity, allowing the retailer to focus on marketing campaigns rather than database scaling.

Domande di esercitazione

Q1. An IT team at a major international airport [Transport](/industries/transport) deploys a custom-coded captive portal. They notice that while Android users connect seamlessly, a significant portion of iOS users experience an issue where they authenticate successfully but cannot browse the web. On closer inspection, the iOS devices show they are connected to the SSID, but the top-right button on the captive popup still says 'Cancel' instead of 'Done'. What is the root cause of this issue, and how should the developer fix it?

Suggerimento: Analyze how the Apple CNA helper detects that a network has transitioned from captive to authenticated, and what browser action is required to trigger this check.

Visualizza risposta modello

The root cause is that the portal's success page is updating the UI dynamically via JavaScript (AJAX/SPA routing) rather than performing a full-page HTTP navigation. The Apple iOS Captive Network Assistant (CNA) mini-browser only re-runs its background connectivity check (the canary request to captive.apple.com) when a full-page URL redirect or navigation occurs. If the developer submits the login form via AJAX and simply displays a 'Success' message in the DOM, the CNA remains unaware that the network has been unlocked. Consequently, the top-right button remains as 'Cancel'. If the user clicks 'Cancel' to exit, the OS assumes the login failed and disconnects from the WiFi network.

Solution: The developer must modify the authentication success handler to force a full-page redirect. This can be achieved by submitting the login form natively via a standard HTML <form action="/submit" method="POST"> or by executing window.location.href = '/success_landing_page' in JavaScript once the API returns a successful authentication response. This triggers the required full-page load, forcing the CNA helper to re-evaluate the network state, verify that the canary URL is now reachable, and change the top-right button to 'Done'.

Q2. A stadium operations team [Events] wants to launch a guest WiFi network that captures marketing opt-ins. The compliance officer insists that the portal must be 100% GDPR-compliant. The development team presents a mockup where the login form has a pre-checked box saying 'I agree to the Terms of Service and consent to receive marketing newsletters'. Why is this design non-compliant, and how should the HTML/CSS and form structure be refactored to satisfy GDPR while maintaining a high conversion rate?

Suggerimento: Consider GDPR's strict requirements regarding explicit consent, the decoupling of marketing opt-ins from terms of service, and the physical visibility of legal text on mobile screens.

Visualizza risposta modello

The proposed design violates GDPR on two major fronts: first, pre-checked checkboxes do not constitute valid consent, which must be freely given, specific, informed, and unambiguous. Second, bundling marketing consent with the agreement to the Terms of Service is non-compliant; a user cannot be forced to accept marketing emails as a condition of using the WiFi service.

Refactoring Strategy:

  1. Decouple Consent: Split the checkbox into two separate checkboxes. Checkbox A is mandatory and covers the Terms of Service and Privacy Policy. Checkbox B is optional and covers marketing newsletter opt-in.
  2. Set to Unchecked: Ensure both checkboxes are unchecked by default in the HTML (checked attribute omitted).
  3. CSS Visibility: Since over 90% of users are on mobile, place the checkboxes directly above the 'Connect' button so they are visible 'above the fold' without scrolling. Use a system font stack and set the label font size to 14px with a line-height of 1.4 for readability.
  4. Terms Scrollbox: To prevent the legal text from pushing the form elements off the screen, place the detailed Terms of Service in a scrollable container with a fixed height (max-height: 100px; overflow-y: auto; background-color: #F5F1ED; border: 1px solid #D1D5DB; border-radius: 6px;) that can be toggled open or closed via a text link. This maintains a clean, high-converting layout while ensuring absolute legal compliance.

Q3. A retail chain [Retail](/industries/retail) is deploying a custom-coded splash page across 100 stores. The designer used Google Fonts (Montserrat) and linked to a CDN-hosted Bootstrap stylesheet in the HTML head. During testing on a corporate network, the page renders beautifully. However, when deployed on a test store AP with a captive network configuration, the page renders with unstyled Times New Roman text, broken alignment, and missing icons. Why does this happen, and how must the assets be refactored?

Suggerimento: Analyze the state of the network connection before a user is authenticated, and determine how the browser handles external HTTP requests to domains outside the walled garden.

Visualizza risposta modello

This failure occurs because the device is in an unauthenticated, captive state when the splash page is loaded. In this state, the wireless gateway blocks all outbound internet traffic, allowing requests only to domains explicitly whitelisted in the gateway's Walled Garden. Because the CDN domains for Bootstrap (cdn.jsdelivr.net) and Google Fonts (fonts.googleapis.com) are not whitelisted, the browser's requests to fetch the stylesheet and font files fail silently. Consequently, the browser falls back to its default rendering engine, resulting in unstyled HTML (Times New Roman text) and broken layouts.

Refactoring Strategy:

  1. Inline CSS: Remove the external Bootstrap stylesheet link. Copy the necessary CSS grid/flexbox rules directly into a <style> block in the HTML <head>. This ensures that all layout instructions are delivered in the initial single-page payload.
  2. Implement System Font Stack: Remove the Google Fonts @import or <link> call. Replace it with a native system font stack in the CSS (font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;). This forces the device to use high-quality fonts already pre-installed on the operating system, eliminating the external network dependency entirely.
  3. Base64 Encode Icons/Logos: If the layout relies on external images or icon libraries (like FontAwesome), convert these icons into SVG format and embed them inline within the HTML or as Base64 Data URIs in the CSS. This guarantees that the page is 100% self-contained and renders perfectly even with zero internet connectivity.

Continua a leggere questa serie

Captive Portal vs Splash Page

Questa guida autorevole analizza la distinzione fondamentale tra captive portal e splash page nelle reti WiFi per gli ospiti. Chiarisce come il meccanismo di intercettazione di rete sottostante funzioni in sinergia con l'interfaccia visiva per gli ospiti, aiutando i responsabili IT e i gestori delle strutture a prendere decisioni informate in materia di architettura e acquisti.

Leggi la guida →

Captive Portal Login: Troubleshooting and Explainer

Questa guida fornisce un riferimento tecnico completo per comprendere, implementare e risolvere i problemi dei sistemi di login al captive portal in ambienti WiFi aziendali per ospiti. Spiega gli esatti meccanismi di reindirizzamento HTTP e di dirottamento DNS utilizzati dai moderni captive portal, descrive in dettaglio come l'HSTS e i browser HTTPS sicuri possano bloccare i reindirizzamenti locali e fornisce una checklist di risoluzione dei problemi chiara e pratica che copre sia le soluzioni lato client (disattivazione delle VPN, disattivazione della randomizzazione MAC, utilizzo di NeverSSL) sia le risoluzioni lato operatore (configurazione del walled garden, ottimizzazione del tempo di lease DHCP, verifica dell'intercettazione DNS). I gestori delle sedi, i responsabili IT e gli architetti di rete troveranno questa guida essenziale per ridurre al minimo i ticket di supporto degli ospiti e massimizzare il ROI della loro infrastruttura wireless.

Leggi la guida →

How to Set Up a WiFi Hotspot for Your Business

Questa guida autorevole fornisce a leader IT, architetti di rete e direttori delle operazioni di sede un modello pratico e indipendente dal fornitore per l'implementazione di hotspot WiFi per ospiti sicuri, conformi e che migliorano il business. Copre decisioni architetturali critiche — dalla segmentazione VLAN e configurazione del Captive Portal alla conformità GDPR e alla modellazione del traffico — e dimostra come trasformare l'infrastruttura di rete da un centro di costo a una piattaforma di analisi che genera entrate utilizzando le capacità di Guest WiFi e analisi di Purple.

Leggi la guida →