Custom Captive Portal: HTML and CSS Guide

This authoritative technical reference guide outlines the development standards, CSS architecture, and network-level constraints required to design and code a custom captive portal landing page. It provides frontend developers and network architects with actionable strategies to navigate Apple CNA and Android webview environments, ensuring pixel-perfect, compliant, and highly performant guest WiFi experiences.

📖 11 min read📝 2,731 words🔧 2 worked examples❓ 3 practice questions📚 8 key definitions

Listen to this guide

View podcast transcript

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.

Key Takeaways

✓Captive portals run in highly restricted mini-browsers (like Apple's iOS Websheet) that block external stylesheets, web fonts, cookies, and local storage.
✓Designing for 'Zero Connectivity' is mandatory: all CSS must be inline, and visual assets should be embedded directly as Base64 Data URIs.
✓A full-page HTTP redirect is required after successful login to trigger the iOS exit handshake; AJAX-based DOM updates will leave devices trapped in a captive loop.
✓Mobile-first layouts must feature a single-column card structure (max-width: 480px), touch-friendly targets (min 44px), and input fonts of at least 16px to prevent auto-zooming.
✓Legal compliance under GDPR requires explicit, unchecked-by-default checkboxes for marketing opt-ins, decoupled from the standard Terms of Service agreement.
✓While custom coding offers complete creative freedom, hosting and scaling RADIUS servers, database security, and multi-vendor integrations present massive operational overhead.
✓Purple's platform combines developer-level HTML/CSS workspace control with a secure, cloud-native, globally distributed RADIUS infrastructure and native compliance tools.

📚 Part of our core series: The Ultimate Guide to Captive Portals →

Executive Summary

For enterprise venues—ranging from luxury hotels Hospitality and retail chains Retail to transit hubs Transport and modern medical campuses Healthcare —the guest WiFi splash page is the digital front door. However, over 90% of guest WiFi logins occur on mobile devices, where rendering is governed not by standard browsers like Safari or Chrome, but by highly restricted Captive Network Assistant (CNA) webviews [1]. These "mini-browsers" enforce severe sandbox limitations: they block external CDNs, disable persistent cookies, ignore external web fonts, and severely restrict JavaScript execution to mitigate security risks and prevent session hijacking [2].

When a developer designs a splash page using traditional web standards, these constraints result in broken layouts, missing brand assets, and non-functional login buttons, directly impacting customer satisfaction and digital engagement. This guide provides solutions to these challenges, presenting defensive coding practices—such as inline CSS, Base64 asset encoding, system font stacks, and explicit navigation-driven authentication handshakes—to ensure seamless cross-platform rendering. Furthermore, we examine how utilizing a managed solution like Purple's portal builder allows developers to maintain complete HTML/CSS creative control while offloading RADIUS authentication, database scaling, GDPR/PCI compliance, and multi-vendor AP integrations [3].

Technical Deep-Dive

To build a resilient custom captive portal, developers must understand the network-level interception and browser virtualization that occurs when a guest associates with an open Service Set Identifier (SSID).

The Captive Portal Lifecycle

When a client device associates with a captive SSID, the following sequence is triggered:

IP Association: The device completes a 3-way handshake and requests an IP address via DHCP.
Active Connectivity Probe: The operating system's background network manager immediately sends an HTTP GET request to a dedicated vendor-neutral canary URL (e.g., Apple's http://captive.apple.com/hotspot-detect.html or Google's http://connectivitycheck.gstatic.com/generate_204) [1].
DNS/HTTP Interception: The local Wireless LAN Controller (WLC) or Access Point (AP) intercepts this port 80 HTTP request. Instead of returning the expected HTTP 200 or 204 status, the gateway redirects the client's traffic to the captive portal's landing page URL via an HTTP 302 redirect [2].
Webview Spawning: Detecting the redirect, the OS spawns its native Captive Network Assistant (CNA) mini-browser to display the redirected splash page, bypassing the need for the user to manually open a full browser.
Authentication and State Transition: The user completes the login form, submitting credentials back to the portal server, which instructs the gateway (often via a RADIUS Access-Accept or external API call) to authorize the MAC address.
CNA Exit Handshake: The CNA mini-browser performs another HTTP GET to its canary URL. If it receives the expected 200/204 response, it changes its top-right button from "Cancel" to "Done" and establishes the WiFi connection as the primary network interface.

Platform-Specific Mini-Browser Constraints

Each operating system handles this lifecycle within different webview environments, resulting in highly fragmented behavior. The table below details these critical constraints:

Platform / Webview	Display Method	Persistent Cookies	External Web Fonts	JavaScript Execution	Window Dimensions	Exit Handshake Trigger
Apple iOS CNA (Websheet)	Mini-Browser Popup	Blocked (Destroyed on close)	Blocked (Offline)	Limited (No localStorage/sessionStorage)	Responsive (Device-width)	Full-page HTTP Redirect Only [1]
Apple macOS CNA (Captive Network Assistant)	Mini-Browser Popup	Blocked	Blocked	Limited (No alert/confirm dialogs)	Fixed (900px x 572px)	Full-page HTTP Redirect Only
Android (Google) (CaptivePortalLogin)	Push Notification -> Chrome Custom Tab	Allowed (Shared with Chrome)	Allowed (If whitelisted in walled garden)	Full	Responsive	Automatic (Captive Portal API / 204 Check) [2]
Samsung Android (Samsung Internet)	Push Notification -> Mini-Browser	Allowed	Allowed	Full	Responsive	Automatic
Windows 10/11 (Default Browser)	Auto-Launch Default Browser	Allowed (Full browser context)	Allowed	Full	Responsive	Manual / Automatic

Coding Around the Apple CNA "Done" Button Trap

One of the most frequent failure modes in custom portal development is the "Done" Button Trap on iOS devices. When a user authenticates, the iOS Websheet webview must detect that the network is no longer captive. It does this by monitoring the success of its background canary requests.

Crucially, the iOS CNA will only trigger this check upon a full-page HTTP navigation (location redirect). If a developer builds a modern Single Page Application (SPA) that submits form data via an asynchronous AJAX call (e.g., fetch() or Axios) and updates the DOM dynamically without changing the URL, the CNA will never re-run its connectivity check. The user will be authenticated at the gateway level, but the CNA button in the top-right corner will remain as "Cancel". If the frustrated user clicks "Cancel", the iOS device will immediately disassociate from the SSID, terminating the WiFi session [1].

To prevent this, the authentication success handler must perform a full-page redirect to a physical landing page (e.g., window.location.href = '/success') or submit the login form natively via a standard HTTP POST action.

Implementation Guide

To ensure consistent rendering across all platforms, developers must transition from modern, asset-heavy web design to a highly self-contained, defensive coding style.

The Golden Rule: Design for Zero Internet Connectivity

During the captive state, the client device has no access to the wider internet. It can only resolve and access IP addresses and domains explicitly whitelisted in the wireless controller's Walled Garden (such as the IP of the captive portal server itself). Therefore, any external asset referenced in your HTML will fail to load, resulting in a broken layout.

To design defensively, implement the following Mobile-First Captive Portal Design Checklist:

1. Viewport Configuration

To prevent mobile devices from scaling down the viewport to a desktop width (typically 980px), the HTML `` must include a responsive viewport meta tag. Without this, text and input fields will appear microscopic on mobile devices:

2. Inlining CSS and Removing External Dependencies

Never link to external CSS files or CDNs (e.g., Bootstrap, Tailwind, or Google Fonts). All CSS must be embedded within a `

<div class="portal-card">
    <div class="logo-container">
        
        
            
            YOUR BRAND
        
    </div>
    
    <h1>Welcome to Guest WiFi</h1>
    <p>Please enter your details below to gain secure, high-speed internet access.</p>
    
    
    
        <div class="form-group">
            Full Name
            
        </div>
        
        <div class="form-group">
            Email Address
            
        </div>
        
        <div class="consent-group">
            
            
                I accept the <a href="#">Terms of Service</a> and consent to data processing in compliance with GDPR regulations.
            
        </div>
        
        <div id="terms_box" class="terms-scrollbox">
            <strong>WiFi Terms of Service:</strong><br />
            1. This service is provided as-is without warranties.<br />
            2. Users must not engage in illegal bandwidth-intensive activities.<br />
            3. Personal data is collected solely for authentication and marketing opt-ins in compliance with our Privacy Policy.
        </div>
        
        Connect to WiFi
    
    
    <div class="footer">
        Powered by Purple | Secure Guest WiFi
    </div>
</div>


## Troubleshooting &amp; Risk Mitigation

When deploying custom-coded HTML/CSS captive portals, IT operations teams frequently encounter several severe operational risks:

### 1. The SSL/TLS Certificate Warning Loop

Because captive portals function by intercepting traffic, they present a fundamental conflict with modern HTTPS web security. When a user attempts to visit an HTTPS site (e.g., `https://www.google.com`), and the gateway attempts to redirect that traffic to an HTTP captive portal, the browser detects a mismatch in the SSL certificate and displays a critical "Your connection is not private" security warning. 

* **Mitigation**: Never attempt to intercept HTTPS traffic directly. Rely entirely on the operating system's native CNA helper (which makes an unencrypted HTTP request to trigger the redirect). Ensure your captive portal's domain has a valid, publicly trusted SSL certificate (e.g., Let's Encrypt or DigiCert) and is served over HTTPS *only after* the initial HTTP redirect has successfully routed the user to your portal domain [2].

### 2. DNS Resolution Failures (The Walled Garden Trap)

If your custom HTML page references external resources—such as a social login OAuth endpoint (e.g., Facebook, Google) or a payment gateway—the DNS requests for these domains will fail unless they are explicitly whitelisted in the wireless controller's Walled Garden. If a domain is missing from the whitelist, the login flow will stall, presenting a blank screen.

* **Mitigation**: Maintain a strict, minimal Walled Garden list. If utilizing social logins, whitelist the specific wildcard domains recommended by the identity providers (e.g., `*.google.com`, `*.gstatic.com`). 

### 3. Session Timeout and MAC Spoofing Vulnerabilities

Standard captive portals authenticate devices based on their MAC addresses. However, modern mobile operating systems (iOS 14+ and Android 10+) utilize randomized MAC addresses (private WiFi addresses) by default, rotating them periodically. This can lead to guests being repeatedly prompted to re-authenticate, destroying the user experience [1].

* **Mitigation**: Implement reasonable session timeouts (e.g., 24 hours) on the RADIUS server to prevent stale sessions, and utilize modern authentication standards like **Passpoint (Hotspot 2.0)** or **WPA3-Enterprise** for seamless, secure onboarding that bypasses MAC-based captive portals entirely.

## Purple Product Relevance: Build vs. Buy

While coding a single HTML page is straightforward, hosting, securing, and scaling a custom captive portal infrastructure presents massive technical and compliance hurdles. The table below compares the engineering and operational realities of self-hosting a custom portal versus utilizing Purple's managed enterprise platform:

| Feature / Operational Requirement | Self-Hosted Custom Portal | Purple Enterprise WiFi Platform |
| :--- | :--- | :--- |
| **HTML/CSS Customization** | Fully manual coding, uploading files to individual APs or local web servers. | **Pixel-perfect developer editor** allowing custom HTML/CSS injects, combined with a drag-and-drop visual builder.
| **RADIUS Infrastructure** | Must deploy, configure, and maintain highly available FreeRADIUS or Cloud RADIUS servers [4]. | **Built-in, globally distributed, cloud-native RADIUS** with active-active redundancy and 99.99% uptime SLAs.
| **Multi-Vendor AP Support** | Custom integration scripts required for each hardware vendor (Cisco, Aruba, Meraki, Ruckus) [5]. | **Native, out-of-the-box integration** with over 200 hardware models; unified portal deployment across mixed-hardware estates.
| **Data Privacy &amp; Compliance** | Venue assumes 100% legal liability for GDPR, CCPA, and PCI DSS compliance, including secure database encryption and data deletion workflows. | **Fully compliant by design**. Built-in consent management, automated data-subject deletion requests, and secure ISO 27001-certified hosting.
| **Analytics &amp; Marketing** | Requires building custom data ingestion pipelines and integrating third-party marketing tools. | **Enterprise-grade analytics dashboard** with real-time footfall tracking, return-rate metrics, and automated marketing campaign triggers [6].
| **Identity Provider Integrations** | Manual OAuth2 integrations with Google, Facebook, Apple, and local SMS gateways. | **One-click integrations** with major social platforms, SMS gateways, and Azure AD / Okta for corporate guests.

Purple's platform resolves the "Build vs. Buy" dilemma. It provides developers with the complete creative freedom of a custom HTML/CSS workspace while eliminating the complex, high-risk backend infrastructure engineering required to support secure RADIUS authentication at scale.

## ROI &amp; Business Impact

Investing in a professionally engineered, responsive custom captive portal delivers quantifiable returns across IT operations, marketing, and legal compliance.

### 1. Operational Cost Reduction (IT Helpdesk Tickets)

In large-scale deployments, such as a stadium or multi-site retail chain, a broken captive portal is a leading driver of IT helpdesk escalations. When guests encounter a "white screen" or a non-responsive login button, they overwhelm on-site staff or submit support tickets.

$$\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}$$

* **Scenario**: A convention center with 1,000,000 annual visitors. A poorly coded portal has a 5% failure rate on older iOS devices, leading to a 10% helpdesk contact rate. At an industry-standard $15 per support ticket, the operational cost is:
  $$(1,000,000 \times 0.05 \times 0.10) \times \$15 = \$75,000 \text{ annually in avoidable support overhead}$$
* **Outcome**: Transitioning to a CNA-optimized, mobile-first template reduces the portal failure rate to &lt;0.1%, virtually eliminating this operational drain.

### 2. Marketing Data Capture and Opt-in Optimization

For retail and hospitality venues, the guest WiFi portal is the primary mechanism for capturing clean, first-party customer data. A poorly designed user interface with microscopic text or a clunky form layout causes high **bounce rates**—users abandon the login process entirely, resulting in lost marketing opportunities.

* **Case Study (Retail)**: A national retail chain implemented a mobile-first optimized captive portal utilizing Purple's platform. By replacing a multi-step login form with a single-field email input (font-size: 16px) and an optimized 48px tap-target button, they saw a **42% increase in completed registrations** and a **28% increase in marketing newsletter opt-ins** within the first quarter [6].

### 3. Legal and Regulatory Risk Mitigation

Under GDPR and CCPA, non-compliant data collection carries severe financial penalties (up to 4% of global annual turnover under GDPR). Relying on pre-ticked checkboxes or failing to provide a clear, easily accessible Privacy Policy on your splash page exposes the enterprise to immense legal liability.

* **Mitigation ROI**: Implementing an explicit, un-ticked consent checkbox and hosting terms within an optimized scrollbox ensures 100% regulatory compliance, mitigating the risk of multi-million dollar regulatory fines and protecting brand reputation.

## Summary of Key Takeaways

* **The CNA Sandbox is Restrictive**: Apple's iOS Websheet and macOS CNA are highly sandboxed environments that block external assets, cookies, and web fonts. All styling and assets must be self-contained (inline CSS, Base64 images, system fonts) [1].
* **AJAX Breaks the iOS Exit Handshake**: To successfully transition the iOS device from "captive" to "connected" (changing the top-right button from "Cancel" to "Done"), you must trigger a full-page HTTP redirect. Asynchronous DOM updates will leave the device in a captive loop.
* **Mobile-First is Mandatory**: Over 90% of logins occur on mobile. Design a single-column layout (max-width: 480px), utilize touch-friendly tap targets (minimum 44px x 44px), and enforce a minimum 16px font size on all text inputs to prevent automatic iOS browser zooming.
* **Walled Gardens Control DNS**: Any external domain referenced during login (e.g., social login APIs) must be explicitly whitelisted in the wireless controller's walled garden, or the page will fail to load.
* **Purple Eliminates Backend Complexity**: Utilizing Purple's portal builder gives developers complete HTML/CSS control via a custom editor, while offloading the immense security, scaling, and compliance burdens of RADIUS, multi-vendor AP integrations, and GDPR-compliant database management [3].

## References

* [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] [How to Implement 802.1X Authentication with Cloud RADIUS](/guides/implementing-8021x-with-cloud-radius)
* [5] [Cisco Wireless APs: 2026 Guide to Products &amp; Deployment](/blog/cisco-wireless-ap)
* [6] [Purple WiFi Marketing &amp; Analytics Platform](/guest-wifi-marketing-analytics-platform)

---

## Listen to the Technical Briefing

Listen to a senior solutions architect discuss the technical constraints and implementation strategies for custom captive portals:

Key Definitions

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.

Worked Examples

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:

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.
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.
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.
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.

Examiner's Commentary: 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:

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.
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.
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.
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.

Examiner's Commentary: 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.

Practice Questions

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?

Hint: 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.

View model answer

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?

Hint: 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.

View model answer

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:

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.
Set to Unchecked: Ensure both checkboxes are unchecked by default in the HTML (checked attribute omitted).
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.
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?

Hint: 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.

View model answer

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:

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.
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.
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.

Continue reading in this series

Why Your Captive Portal Isn't Loading on iPhone

An authoritative technical reference guide explaining why captive portals fail to load on iOS devices. It dives deep into Apple's Captive Network Assistant (CNA) daemon detection logic, identifies key iOS-specific interference factors like iCloud Private Relay and Private MAC addresses, and outlines comprehensive mitigation strategies for network engineers and venue operators.

Captive Portal vs Splash Page

This authoritative guide breaks down the critical distinction between captive portals and splash pages in guest WiFi networks. It clarifies how the underlying network interception mechanism works in tandem with the visual guest interface, helping IT leaders and venue operators make informed architectural and procurement decisions.