Purple Portal API: Cosa Puoi Fare

Sintesi Esecutiva

Per i responsabili IT di sedi multi-sito - hotel, catene retail, stadi e centri congressi - la rete WiFi per gli ospiti è più di un semplice servizio di cortesia. È una fonte ricca e continuamente aggiornata di dati proprietari (first-party data) in grado di generare un impatto aziendale misurabile su marketing, operazioni e customer experience. L'API di Purple Hub fornisce l'interfaccia programmatica necessaria per sbloccare questo valore su scala. Consente ai team tecnici di andare oltre i cruscotti di analisi integrati e di creare integrazioni robuste e automatizzate che inseriscono dati sui visitatori conformi al GDPR direttamente nei sistemi aziendali principali, dalle piattaforme CRM e strumenti di marketing automation fino ai programmi fedeltà e ai data warehouse di business intelligence.

Questa guida è un riferimento pratico e operativo per architetti di soluzioni, responsabili IT e sviluppatori senior. Descrive in dettaglio il modello di autenticazione, gli endpoint disponibili, i modelli di integrazione e gli scenari di implementazione reali che dimostrano come l'API di Purple WiFi possa trasformare un'implementazione WiFi da un centro di costo a un asset di dati strategico. Sia che stiate valutando l'API per la prima volta o che stiate pianificando un'integrazione di livello enterprise, questo documento fornisce le basi tecniche e i framework decisionali necessari per procedere con sicurezza.

Approfondimento Tecnico

Autenticazione e Versionamento dell'API

L'API di Purple Hub utilizza l'autenticazione tramite API Key, un modello semplice e sicuro ideale per le integrazioni server-to-server. A differenza dei flussi OAuth 2.0, che richiedono cicli di scambio e aggiornamento dei token, l'autenticazione tramite API Key prevede l'inclusione di un segreto statico negli intestazioni della richiesta. Questa semplicità riduce l'overhead di integrazione senza compromettere la sicurezza, a condizione che la chiave venga memorizzata in modo sicuro e ruotata periodicamente come parte della normale politica di gestione delle credenziali.

La versione di produzione attuale è la v1.7, che ha introdotto diversi miglioramenti importanti rispetto alla v1.6.2. In particolare, la proprietà unsubscribed nell'oggetto dati utente distingue ora chiaramente tra un utente che ha revocato attivamente il consenso al marketing dopo essere stato precedentemente iscritto e un utente che non si è mai iscritto affatto. Questa distinzione è fondamentale per la conformità al GDPR e per un'accurata segmentazione del pubblico. Inoltre, gli endpoint Visitors e Venues restituiscono ora una risposta HTTP 200 OK quando non vengono trovati dati, anziché un 404 Not Found, che in precedenza causava confusione nelle logiche di monitoraggio e gestione degli errori.

Endpoint Disponibili

L'API di Portal Company espone tre categorie principali di endpoint con cui i team IT interagiranno regolarmente.

Tutti gli endpoint restituiscono dati in formato JSON. L'endpoint visitors è quello utilizzato più comunemente, in quanto espone la ricchezza completa dei dati del profilo ospite raccolti durante il percorso di autenticazione del Captive Portal. Ciò include nome, cognome, indirizzo email, sesso, data di nascita, numero di cellulare, codice postale, provider di autenticazione (es. modulo di registrazione, login social), conteggio delle visite per sede e qualsiasi campo personalizzato configurato sulla splash page.

Limiti di frequenza (Rate Limits)

Un vantaggio architetturale chiave delle API di Purple Portal è che non ci sono limiti di frequenza. La piattaforma è progettata per supportare qualsiasi volume di richieste o transazioni, rendendola adatta a implementazioni su larga scala in cui gli script potrebbero dover elaborare migliaia di record di sedi o milioni di profili di visitatori. Ciò rimuove un vincolo comune che complica la progettazione dell'integrazione con altre piattaforme ed elimina la necessità di limitazione delle richieste o logica di back-off nel codice client.

Modelli di integrazione: Pull vs. Push

Le API di Purple WiFi supportano due modelli di integrazione fondamentalmente diversi, ciascuno adatto a casi d'uso differenti. Comprendere quale modello applicare in uno scenario specifico è la decisione architetturale più importante che prenderai.

Il modello di pull tramite REST API prevede che il tuo sistema effettui richieste su richiesta o pianificate agli endpoint API per recuperare i dati. Questo è l'approccio corretto per l'elaborazione batch, la reportistica e la business intelligence. Uno script ETL notturno che estrae tutti i dati dei visitatori dal giorno precedente e li carica in un data warehouse è un esempio canonico. Il modello pull ti offre il controllo completo su quando e quanti dati recuperare.

Il modello di push tramite Webhook prevede che Purple invii dati al tuo sistema nel momento in cui si verifica un evento specifico - nello specifico, quando un ospite si autentica sulla rete WiFi. Il tuo sistema deve esporre un endpoint HTTP accessibile pubblicamente e protetto da SSL (un "listener") in grado di ricevere ed elaborare questi payload JSON POST. Il modello Webhook è la scelta corretta per qualsiasi caso d'uso che richieda dati quasi in tempo reale, come l'invio di un messaggio di benvenuto personalizzato, l'aggiornamento dello stato "visto l'ultima volta" di un cliente in un CRM o la notifica a un hospitality manager dell'arrivo di un ospite VIP.

Struttura del payload del Webhook

Il payload JSON fornito da un Webhook di Purple è strutturato in quattro oggetti principali, ognuno dei quali fornisce una dimensione diversa di contesto per l'evento di autenticazione.

L'oggetto user.visitCountForVenues è particolarmente prezioso per i gestori di reti multi-sito. Fornisce un conteggio delle visite per singola sede, insieme ai timestamp firstVisit e lastVisit, consentendo di identificare i visitatori al primo accesso rispetto ai clienti fidelizzati che ritornano, direttamente al momento dell'autenticazione - senza alcuna chiamata API aggiuntiva.

Guida all'implementazione

Prerequisiti e configurazione

L'accesso alle API del portale richiede una licenza Engage. Una volta ottenuta la licenza, genera la tua chiave API all'interno delle impostazioni del portale Purple. Per lo sviluppo iniziale e i test, lo strumento consigliato è Postman; Purple fornisce una guida di configurazione dedicata per impostare le variabili d'ambiente e gli header di richiesta corretti. È disponibile anche un file demo in PHP per i team che preferiscono un punto di partenza basato su scripting lato server.

Configurazione di un'integrazione Webhook

La distribuzione di un'integrazione Webhook prevede cinque passaggi. Primo, crea e distribuisci il tuo endpoint listener su un URL accessibile pubblicamente e protetto da SSL. Una funzione serverless (AWS Lambda, Azure Functions o Google Cloud Functions) rappresenta una scelta architetturale eccellente: si adatta automaticamente, comporta costi minimi a bassi volumi e gestisce le richieste simultanee senza configurazione. Secondo, valida l'URL del listener nel portale Purple navigando su Gestione > Sedi > Webhook. Purple invierà una richiesta di test per confermare che l'endpoint sia raggiungibile e restituisca l'header richiesto wifiWebhookListener: 1. Terzo, crea o modifica un LogicFlow nel portale e aggiungi un nodo di azione Webhook, selezionando il tuo URL convalidato. Quarto, assicurati che lo stato del LogicFlow sia impostato su 'Online'. Quinto, associa il LogicFlow al relativo Percorso di Accesso. Da questo momento, ogni autenticazione ospite su quel percorso attiverà il tuo Webhook.

Gestione dei tentativi e idempotenza

Il tuo listener deve essere progettato per gestire le dinamiche tipiche dei sistemi distribuiti. Purple tenterà nuovamente l'invio di un Webhook fallito dopo tre ore se il tuo listener non risponde (timeout superiore a 10 secondi) o restituisce uno stato di errore. Ciò significa che il tuo listener potrebbe ricevere lo stesso evento più volte. Inoltre, una singola visita dell'ospite può generare più eventi di autenticazione - ad esempio, quando un dispositivo si riconnette dopo il blocco dello schermo, o quando un utente si sposta in roaming tra i punti di accesso. La tua logica di elaborazione deve quindi essere idempotente: l'applicazione dello stesso evento due volte deve produrre lo stesso risultato dell'applicazione singola. Un modello di implementazione comune consiste nel verificare se un'azione (come l'invio di un'e-mail di benvenuto) sia già stata eseguita per un determinato ID utente entro una finestra temporale definita prima di eseguirla.

Best Practice

Diversi principi dovrebbero guidare qualsiasi implementazione in produzione dell'API del Purple Portal. Implementa sempre l'integrazione con l'ultima versione dell'API (v1.7) e aggiorna i percorsi degli URL e la logica di analisi delle risposte al rilascio di nuove versioni. Tratta la tua API Key come una credenziale sensibile: memorizzala in un gestore di segreti (come AWS Secrets Manager o Azure Key Vault) anziché nel codice sorgente o nelle variabili di ambiente su sistemi condivisi. Per i listener di Webhook, implementa una registrazione strutturata di ogni payload e risposta in arrivo per facilitare il debug e i percorsi di controllo. Rispetta i campi unsubscribed e unsubscribedDate nell'oggetto utente; l'elaborazione di azioni di marketing verso utenti che hanno effettuato l'opt-out costituisce una violazione del GDPR. Infine, testa la tua integrazione con l'intera gamma di casi limite: utenti senza indirizzo email, utenti con campi personalizzati nulli ed eventi di autenticazione che arrivano fuori dall'ordine cronologico.

Risoluzione dei problemi e mitigazione dei rischi

La modalità di errore più comune in un'integrazione Webhook è un listener lento o non disponibile. Se l'endpoint non risponde costantemente entro 10 secondi, Purple disabiliterà automaticamente il Webhook dopo un periodo prolungato di mancata risposta, richiedendo una nuova verifica manuale nel portale. Per mitigare questo rischio, implementa un endpoint di controllo dello stato (health check) sullo stesso server del tuo listener e includilo nel monitoraggio della tua infrastruttura. Assicurati che il tuo listener esegua solo un'elaborazione sincrona minima prima di restituire una risposta 200 OK; delega qualsiasi calcolo pesante o chiamata API a valle a una coda asincrona.

Per le integrazioni API REST, il rischio principale è l'obsolescenza dei dati nei sistemi a valle se il processo di pull pianificato fallisce in modo silenzioso. Implementa avvisi sui tuoi script ETL per informare il team operativo se un'esecuzione fallisce o non produce risultati in modo imprevisto. Quando esegui la migrazione dall'API v1.6.2 alla v1.7, controlla tutto il codice che fa riferimento al campo unsubscribed e all'endpoint Unsubscribes, poiché il nome della proprietà è stato corretto da unsubcribers a unsubscribers nella v1.7.

ROI e impatto aziendale

Il business case per l'integrazione con le Purple Portal API è ampiamente consolidato in molteplici settori verticali. Nel settore hospitality, gli hotel che utilizzano integrazioni CRM attivate tramite Webhook segnalano miglioramenti significativi nei tassi di apertura delle email per le comunicazioni personalizzate rispetto alle campagne broadcast generiche, poiché il messaggio viene recapitato nel momento di massima rilevanza - ovvero quando l'ospite si trova fisicamente in loco. Nel retail, il collegamento dei dati del WiFi per gli ospiti a un programma di fidelizzazione consente ai gestori di identificare e premiare i visitatori ad alta frequenza, aumentando la spesa media e i tassi di visite ripetute. Per le grandi arene pubbliche e i centri congressi, le analisi basate su API forniscono i dati granulari sull'affluenza necessari per giustificare le valutazioni delle sponsorizzazioni e ottimizzare il posizionamento dei punti di ristoro.

L'assenza di limiti di frequenza (rate limit) sulle Purple WiFi API significa che il costo dell'integrazione scala con la tua infrastruttura, non con il volume di dati elaborati. Per una catena di vendita al dettaglio nazionale che gestisce centinaia di migliaia di autenticazioni giornaliere, questo rappresenta un vantaggio concreto rispetto alle piattaforme che addebitano costi per singola chiamata API o che impongono tetti di larghezza di banda. Il costo totale di proprietà (TCO) per un'integrazione delle Purple API ben progettata è quindi costituito principalmente dal costo di sviluppo una tantum e dal costo infrastrutturale continuo del listener, entrambi generalmente recuperati entro il primo trimestre grazie al solo miglioramento dei tassi di conversione marketing.

Casi di Studio

Caso di Studio 1: Hospitality - Whitbread Group

Whitbread, la più grande azienda di hotel e ristoranti del Regno Unito, gestisce migliaia di punti di accesso WiFi per gli ospiti in tutto il suo patrimonio di Premier Inn e ristoranti. Integrando le Purple Portal API con la loro piattaforma CRM, il gruppo è stato in grado di creare un profilo ospite unificato che unisce i dati di prenotazione online con il comportamento di visita fisica rilevato sul Captive Portal WiFi. L'integrazione Webhook si attiva a ogni autenticazione dell'ospite, arricchendo il record CRM con il timestamp dell'ultima visita, la posizione della sede e le informazioni sul dispositivo. Ciò consente al team di marketing di segmentare i destinatari in base a recency, frequenza e posizione geografica, e di avviare campagne di re-engagement altamente personalizzate. Il principale risultato tecnico è stato la riduzione del tempo che intercorre tra l'arrivo di un ospite e il suo inserimento in un percorso di marketing attivo da 24 ore (con il precedente modello a polling periodico) a meno di 60 secondi.

Caso di Studio 2: Retail - Rivenditore di Moda Multi-Sito

Un rivenditore di moda nazionale con oltre 80 negozi ha implementato la Purple Portal API per colmare una lacuna critica nella propria strategia di dati sui clienti: disponeva di ottimi dati sull'e-commerce ma di pochissime informazioni sul comportamento dei visitatori in negozio. Collegando l'API di Purple per il guest WiFi al proprio data warehouse esistente tramite un processo ETL notturno, ha creato per la prima volta una vista cliente cross-channel. L'endpoint /visitors veniva interrogato ogni notte per ciascun negozio e i dati venivano uniti ai record delle transazioni e-commerce utilizzando l'indirizzo e-mail come chiave comune. Entro tre mesi, il team di analisi ha identificato che i clienti che si connettevano al WiFi in negozio registravano un valore medio dell'ordine superiore del 34% sul successivo acquisto online, fornendo un business case convincente per ulteriori investimenti nell'esperienza digitale in negozio. L'integrazione non ha richiesto modifiche all'infrastruttura di e-commerce esistente, a dimostrazione del basso livello di attrito del modello pull delle REST API.

Case Study 3: Eventi - Centro Congressi

Un importante centro congressi nel Regno Unito ha utilizzato la Purple Portal API per fornire per la prima volta agli sponsor dati verificati sull'affluenza. In precedenza, i report per gli sponsor si basavano sul conteggio manuale delle persone e sulla scansione dei badge, metodi che richiedevano un uso intensivo di manodopera ed erano imprecisi. Rendendo disponibili tramite API i conteggi dei visitatori aggregati e anonimizzati per zona (mappati sugli ID delle sedi nella piattaforma Purple), il team degli eventi ha potuto fornire agli sponsor dashboard in tempo reale che mostravano il tempo di permanenza e il volume dei visitatori nelle aree sponsorizzate. I dati venivano estratti tramite la REST API ogni 15 minuti durante gli eventi e visualizzati su un portale sponsor personalizzato. Questa funzionalità ha contribuito direttamente a un aumento del 22% dei tassi di rinnovo delle sponsorizzazioni nel primo anno, poiché gli sponsor potevano ora quantificare la portata delle loro attivazioni con dati di prima parte verificati.