Purple Portal API: What You Can Do With It

Un riferimento tecnico per IT manager e architetti di rete su come sfruttare la Purple Portal API. Questa guida dettaglia gli endpoint disponibili, l'autenticazione e i casi d'uso reali per integrare i dati del guest WiFi con i sistemi aziendali, al fine di migliorare la business intelligence e l'efficienza operativa. Copre sia i pattern di integrazione REST API che Webhook, con casi di studio concreti nei settori dell'ospitalità, del retail e degli eventi.

📖 9 minuti di lettura📝 2,212 parole🔧 2 esempi pratici❓ 3 domande di esercitazione📚 9 definizioni chiave

Ascolta questa guida

Visualizza trascrizione del podcast

Benvenuti al Technical Briefing di Purple. Sono un Senior Content Strategist qui in Purple e, nei prossimi dieci minuti, vi fornirò una panoramica concisa e pratica della nostra Portal API: cos'è, cosa potete fare e come sfruttarla per ottenere il massimo impatto sul vostro business. Questo briefing è rivolto ai responsabili IT, agli architetti e ai direttori operativi che hanno l'esigenza di trasformare il proprio WiFi per gli ospiti da una semplice utilità a una potente risorsa di dati.

Partiamo dal contesto. Offrite il WiFi per gli ospiti all'interno dei vostri locali. Ogni giorno si connettono centinaia o migliaia di persone, che forniscono la propria e-mail, forse il proprio nome, e acconsentono ai vostri termini. Si tratta di preziosi dati di prima parte. Il Purple Portal offre dashboard eccellenti per visualizzare tutto questo, ma il vero potenziale si esprime quando collegate questi dati al resto del vostro ecosistema aziendale. È qui che entra in gioco la Portal API. È il ponte che consente ai vostri sistemi di comunicare in modo programmatico con la nostra piattaforma.

Entriamo ora nei dettagli tecnici. La Portal API è un'interfaccia RESTful standard. L'autenticazione è semplice e sicura, grazie a una pratica API Key. Non dovrete preoccuparvi di complessi handshake OAuth per la comunicazione server-to-server. Aspetto fondamentale, non ci sono limiti di frequenza (rate limit). L'abbiamo progettata per una scalabilità di livello enterprise: che gestiate un singolo hotel o una catena nazionale di cinquecento punti vendita, l'API è in grado di supportare i vostri volumi.

Avete a disposizione due modalità principali per estrarre i dati. La prima è il metodo pull: endpoint REST standard. Pensate a endpoint come "visitors" e "venues". Potete scrivere uno script per chiamare questi endpoint in modo pianificato, scaricare tutti i dati dei visitatori delle ultime ventiquattro ore e caricarli nel vostro data warehouse per l'analisi. Questa è la soluzione ideale per la business intelligence, per creare dashboard di sintesi in Power BI o Tableau.

Ma la parte davvero interessante è il metodo push: i Webhook. Questa opzione è pensata per il tempo reale. Configurate un endpoint di ascolto sul vostro lato e, nel momento stesso in cui un ospite si autentica sul vostro WiFi, vi inviamo un payload JSON con tutti i suoi dettagli: nome, e-mail, locale in cui si trova, numero di visite e persino il metodo di autenticazione utilizzato, che si tratti di un modulo di registrazione, di un social login o di altro. È quasi istantaneo. Questo è ciò che abilita un coinvolgimento immediato e personalizzato. È la differenza tra l'invio di un'e-mail di marketing domani e l'invio di una notifica di bentornato con un'offerta esclusiva nell'istante esatto in cui un cliente fedele varca la vostra soglia.

Parliamo dei campi dati che si ottengono. Il payload del Webhook è strutturato in quattro oggetti principali. L'oggetto client fornisce l'indirizzo MAC e lo user agent. Gli oggetti company e venue forniscono gli identificativi e le coordinate geografiche della posizione specifica. L'oggetto session fornisce il timestamp di autenticazione. E l'oggetto user è dove si trova il valore reale: nome, cognome, email, sesso, data di nascita, numero di cellulare, codice postale e un conteggio delle visite per venue che mostra le date della prima e dell'ultima visita. È anche possibile acquisire campi personalizzati dal modulo di registrazione della splash page, quindi se si chiede agli ospiti il numero del programma fedeltà o il numero di stanza in un hotel, anche questi dati verranno trasmessi.

Ora, nella versione uno punto sette dell'API, c'è un importante miglioramento da notare. Il campo unsubscribed ora distingue chiaramente tra gli utenti che hanno attivamente revocato il consenso al marketing dopo essere stati precedentemente iscritti, rispetto a quelli che semplicemente non hanno mai prestato il consenso. Questo è fondamentale per la conformità al GDPR e per una segmentazione accurata. Non si vuole trattare un iscritto disattivato allo stesso modo di qualcuno che non è mai entrato nel funnel di marketing.

Parliamo più in dettaglio dei pattern di integrazione. Per il pattern pull della REST API, il flusso di lavoro tipico è uno script pianificato, ad esempio in Python o Node.js, che viene eseguito ogni notte. Si autentica con la chiave API, interroga l'endpoint dei visitatori per ciascuna venue, trasforma i dati nel formato richiesto e li carica in un database centrale. Questo è un classico processo ETL. Per un operatore multi-sito, si esegue un'iterazione attraverso gli ID delle venue e si aggregano i dati a livello centrale.

Per il pattern push del Webhook, l'architettura è leggermente diversa. È necessario un endpoint accessibile pubblicamente e protetto da SSL. Una funzione serverless è l'ideale in questo caso: AWS Lambda, Azure Functions o Google Cloud Functions. È conveniente, si scala automaticamente e gestisce la concorrenza che si registrerebbe in una venue affollata. Quando la funzione riceve la richiesta POST da Purple, deve analizzare il JSON, eseguire la propria logica di business — forse una ricerca nel CRM o una verifica della fedeltà — e restituire una risposta duecento OK il più rapidamente possibile.

Questo mi porta al requisito di implementazione più importante: il listener deve rispondere entro dieci secondi. In caso contrario, Purple reinserirà la richiesta in coda e riproverà dopo tre ore. Errori persistenti causeranno la disattivazione automatica del Webhook per motivi di sicurezza. Pertanto, mantenete il listener leggero. Eseguite l'elaborazione minima necessaria per restituire una risposta rapida e, se dovete eseguire un'elaborazione pesante, inserite l'evento in una coda interna ed elaboratelo in modo asincrono.

Ora diamo un'occhiata ad alcuni scenari reali per rendere tutto questo concreto.

Considera un hotel di duecento camere. Desiderano inserire automaticamente i nuovi ospiti WiFi in un percorso di email di benvenuto nella loro piattaforma di marketing. La soluzione è semplice: configurare un Webhook, creare un semplice listener serverless e, quando arrivano i dati di un nuovo utente, verificare se esiste già nella piattaforma di marketing. In caso contrario, aggiungerlo e avviare il percorso di benvenuto. L'hotel può anche utilizzare il campo del conteggio delle visite per distinguere i visitatori che effettuano il primo accesso dagli ospiti di ritorno e personalizzare la comunicazione di conseguenza. Un ospite di ritorno potrebbe ricevere un'offerta di fidelizzazione anziché un benvenuto generico.

Ora considera una catena di vendita al dettaglio nazionale con cinquanta negozi. Desiderano una dashboard centrale che mostri le tendenze del traffico pedonale in tutti i punti vendita. In questo caso, il modello pull delle API REST è la scelta giusta. Uno script notturno interroga l'endpoint dei visitatori per ciascuna delle cinquanta sedi, aggrega i dati e li carica in un data warehouse. Il team di analytics crea quindi le proprie dashboard su questi dati. Possono vedere quali negozi hanno i tassi di nuovi visitatori più elevati, quali hanno i migliori rapporti di visitatori di ritorno e come i tempi di permanenza si correlano con le prestazioni di vendita.

Permettimi ora di illustrare alcune trappole comuni e come evitarle.

La prima trappola è la gestione dei eventi duplicati. Una singola visita di un ospite può attivare più eventi di autenticazione, ad esempio se lo schermo del telefono si blocca e si riconnette, o se si sposta tra diversi access point. Il tuo listener deve essere idempotente. Prima di intraprendere un'azione come l'invio di un'email, verifica se hai già elaborato un evento per quell'utente in data odierna.

La seconda trappola consiste nel non convalidare l'URL del listener prima di andare online. Purple richiede di convalidare l'endpoint nel portale prima che possa ricevere dati. Assicurati che il tuo listener sia attivo e restituisca l'intestazione wifiWebhookListener corretta prima di collegarlo a un LogicFlow.

La terza trappola è ignorare lo stato dell'iscrizione. Controlla sempre il campo unsubscribed prima di aggiungere un utente a una lista di marketing. L'invio di comunicazioni di marketing a qualcuno che ha revocato il consenso è una violazione del GDPR con conseguenze significative.

Ora passiamo a una sessione rapida di domande e risposte.

Posso sincronizzare questi dati con il mio CRM personalizzato? Sì. Se il tuo CRM dispone di un'API, puoi utilizzare un listener Webhook come middleware per formattare i dati di Purple e inviarli al tuo sistema. Gli ID restituiti nel payload del Webhook corrispondono a quelli delle API REST, quindi puoi anche effettuare chiamate successive per ottenere ulteriori dettagli, se necessario.

Come gestisco un utente che visita più sedi del mio patrimonio immobiliare? L'API fornisce il conteggio delle visite per ID sede, consentendoti di tracciare facilmente il percorso di un cliente all'interno dell'intero patrimonio e di creare un profilo cross-site completo.

Esiste un limite al numero di URL Webhook che posso configurare? No. Puoi convalidare e utilizzare tutti gli URL listener di cui hai bisogno, il che è utile se diversi team o sistemi devono ricevere gli stessi dati sugli eventi.

Cosa succede se il mio listener non è attivo per manutenzione? Purple riproverà a inviare le notifiche non andate a buon fine, quindi potresti ricevere un accumulo di eventi arretrati quando il tuo listener tornerà online. Il tuo listener deve gestire questa situazione in modo ottimale, elaborando eventi che potrebbero arrivare non in ordine cronologico.

Per riassumere tutto ciò che abbiamo trattato oggi, la Purple Portal API è la chiave per sbloccare l'immenso valore dei dati del tuo guest WiFi. Utilizza le REST API per estrarre dati per reportistica e analisi. Utilizza i Webhook per inviare dati in tempo reale per un coinvolgimento dei clienti immediato e personalizzato. Ricorda il principio fondamentale: push per il tempo reale, pull per i report.

Il tuo prossimo passo è consultare la documentazione API nel nostro portale di supporto. Se disponi di una licenza Engage, genera una chiave API e inizia a esplorare con Postman. Crea un semplice listener Webhook. Guarda il flusso di dati entrare. Quello è il momento in cui il potenziale di questo strumento diventa cristallino.

Grazie per aver ascoltato il Purple Technical Briefing. Se desideri parlare con uno dei nostri solutions architect in merito ai tuoi requisiti di integrazione specifici, visita purple dot ai e prenota una demo. Alla prossima.

Punti chiave

✓La Purple Portal API fornisce l'accesso programmatico ai dati del WiFi per gli ospiti utilizzando una semplice autenticazione tramite API Key, senza limiti di frequenza.
✓Richiede una licenza Engage e attualmente opera sulla versione v1.7, che ha migliorato la conformità al GDPR attraverso una gestione più chiara dello stato di disiscrizione.
✓Utilizza l'API REST (pull) per esportazioni di dati batch, processi ETL e dashboard di analisi.
✓Utilizza i Webhook (push) per azioni in tempo reale guidate da eventi, come sincronizzazioni CRM, messaggistica personalizzata e attivatori di programmi fedeltà.
✓I listener dei Webhook devono essere protetti da SSL, rispondere entro 10 secondi ed essere progettati per gestire eventi duplicati in modo idempotente.
✓I casi d'uso principali spaziano dall'ospitalità (arricchimento del CRM in tempo reale), alla vendita al dettaglio (analisi multicanale) e agli eventi (dati di affluenza verificati per gli sponsor).
✓L'API consente alle organizzazioni di trasformare la propria infrastruttura WiFi da un centro di costo a una risorsa di dati strategica con un ROI chiaro e misurabile.

Sintesi Esecutiva

Per i responsabili IT di sedi multi-sito — hotel, catene retail, stadi e centri congressi — la rete WiFi per gli ospiti è molto più di un semplice servizio di cortesia. Si tratta di una fonte ricca e costantemente aggiornata di dati di prima parte in grado di generare un impatto aziendale misurabile su marketing, operazioni e customer experience. L'API di Purple Portal fornisce l'interfaccia programmatica necessaria per sbloccare questo valore su scala. Consente ai team tecnici di andare oltre i dashboard di analisi integrati e di creare integrazioni robuste e automatizzate che inseriscono i dati dei visitatori conformi al GDPR direttamente nei sistemi aziendali principali, dalle piattaforme CRM e strumenti di marketing automation ai programmi di fidelizzazione 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 pattern di integrazione e gli scenari di implementazione reali che dimostrano come l'API di Purple WiFi possa trasformare un'installazione Wi-Fi da centro di costo ad asset di dati strategico. Sia che stiate valutando l'API per la prima volta, sia che stiate pianificando un'integrazione di livello di produzione, 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 Portal utilizza l'autenticazione tramite API Key, un modello semplice e sicuro, particolarmente adatto alle 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 header della richiesta. Questa semplicità riduce il sovraccarico di integrazione senza compromettere la sicurezza, a condizione che la chiave sia memorizzata in modo sicuro e ruotata periodicamente come parte della normale politica di gestione delle credenziali.

L'attuale versione di produzione è la v1.7, che ha introdotto diversi miglioramenti importanti rispetto alla v1.6.2. In particolare, la proprietà unsubscribed nell'oggetto dati utente ora distingue chiaramente tra un utente che ha revocato attivamente il consenso al marketing dopo essersi precedentemente iscritto e un utente che non si è mai iscritto. Questa distinzione è fondamentale per la conformità al GDPR e per un'accurata segmentazione del pubblico. Inoltre, gli endpoint Visitors e Venues ora restituiscono una risposta HTTP 200 OK quando non vengono trovati dati, anziché un errore 404 Not Found, che in precedenza generava 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.

Endpoint	Metodo	Scopo
`/visitors`	GET	Recupera i profili dei visitatori ospiti, inclusi dati di contatto, dati demografici e cronologia delle visite
`/venues`	GET	Recupera i dati a livello di sede e i metadati di configurazione
`/unsubscribes`	GET	Recupera un elenco di utenti che hanno scelto di non ricevere comunicazioni di marketing

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

Limiti di Velocità (Rate Limits)

Un vantaggio architetturale chiave della Purple Portal API è che non ci sono limiti di velocità. La piattaforma è progettata per supportare qualsiasi volume di richieste o transazioni, rendendola adatta a distribuzioni 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 limitare le richieste (throttling) o di logiche di back-off nel codice client.

Modelli di Integrazione: Pull vs. Push

La Purple WiFi API supporta 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 pull REST API prevede che il tuo sistema effettui richieste on-demand o pianificate agli endpoint dell'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 del giorno precedente e li carica in un data warehouse è un esempio canonico. Il modello pull ti offre il pieno controllo su quando e quanti dati recuperare.

Il modello push Webhook prevede che Purple invii i dati al tuo sistema nel momento stesso in cui si verifica un evento specifico, in particolare 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 di "ultima visualizzazione" di un cliente in un CRM o la notifica a un manager del settore hospitality dell'arrivo di un ospite VIP.

Struttura del Payload del Webhook

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

Oggetto	Campi Chiave	Descrizione
`client`	`mac`, `userAgent`	Identificatori a livello di dispositivo
`company`	`id`, `name`, `uniqId`	I dettagli dell'account della tua azienda
`venue`	`id`, `name`, `latitude`, `longitude`	La sede specifica in cui è avvenuta l'autenticazione
`session`	`authenticationTime`	Timestamp ISO 8601 dell'evento di autenticazione
`user`	`email`, `firstName`, `lastName`, `gender`, `provider`, `visitCountForVenues`, `customFields`	Dati completi del profilo ospite

L'oggetto user.visitCountForVenues è particolarmente prezioso per gli operatori multi-sito. Fornisce un conteggio delle visite per singola sede insieme ai timestamp di firstVisit e lastVisit, consentendo di identificare i visitatori al primo accesso rispetto ai clienti fidelizzati che ritornano 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 e i test iniziali, 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 con scripting lato server.

Configurazione di un'integrazione Webhook

La distribuzione di un'integrazione Webhook prevede cinque passaggi. Innanzitutto, crea e distribuisci il tuo endpoint di ascolto (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 solida: si ridimensiona automaticamente, comporta costi minimi a bassi volumi e gestisce le richieste simultanee senza configurazione. In secondo luogo, convalida l'URL del listener nel portale Purple accedendo a Gestione > Sedi > Webhook. Purple invierà una richiesta di test per confermare che l'endpoint sia raggiungibile e restituisca l'header richiesto wifiWebhookListener: 1. In terzo luogo, crea o modifica un LogicFlow nel portale e aggiungi un nodo azione Webhook, selezionando l'URL convalidato. In quarto luogo, assicurati che il LogicFlow sia impostato sullo stato "Online". In quinto luogo, associa il LogicFlow al relativo Access Journey. Da questo momento in poi, ogni autenticazione di un ospite su quel percorso attiverà il tuo Webhook.

Gestione dei tentativi e idempotenza

Il tuo listener deve essere progettato per gestire le realtà dei sistemi distribuiti. Purple riproverà a inviare un Webhook non riuscito dopo tre ore se il tuo listener non risponde (il timeout supera i 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 di un ospite può attivare più eventi di autenticazione, ad esempio quando un dispositivo si riconnette dopo il blocco dello schermo o quando un utente si sposta tra diversi punti di accesso. La 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 nuovamente.

Best Practice

Diversi principi dovrebbero guidare qualsiasi implementazione in produzione delle API del Purple Portal. Esegui sempre l'implementazione sulla versione API più recente (v1.7) e aggiorna i percorsi URL e la logica di analisi delle risposte al rilascio di nuove versioni. Tratta la tua chiave API 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 d'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 audit. Rispetta i campi unsubscribed e unsubscribedDate nell'oggetto utente; l'elaborazione di azioni di marketing nei confronti di utenti che hanno revocato il consenso costituisce una violazione del GDPR. Infine, testa la tua integrazione su un'ampia gamma di casi limite: utenti senza indirizzo e-mail, 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 inattività, 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; trasferisci qualsiasi calcolo pesante o chiamata API a valle a una coda asincrona.

Per le integrazioni con API REST, il rischio principale è l'obsolescenza dei dati nei sistemi a valle se il processo di pull pianificato fallisce silenziosamente. Implementa avvisi sui tuoi script ETL per notificare al team operativo se un'esecuzione fallisce o non produce output in modo imprevisto. Durante 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 la Purple Portal API è ampiamente consolidato in molteplici settori verticali. Nel settore dell'ospitalità, gli hotel che utilizzano integrazioni CRM attivate tramite Webhook registrano miglioramenti significativi nei tassi di apertura delle e-mail 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 degli ospiti a un programma di fidelizzazione consente agli operatori di identificare e premiare i visitatori ad alta frequenza, aumentando la spesa media e i tassi di visite ripetute. Per i grandi spazi pubblici e i centri congressi, l'analisi basata su API fornisce 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) sulla Purple WiFi API significa che il costo dell'integrazione si adegua alla tua infrastruttura, non al 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 massimi di throughput. Il costo totale di proprietà (TCO) per un'integrazione 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 solo grazie al miglioramento dei tassi di conversione marketing.

Case Studies

Case Study 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 portafoglio di Premier Inn e ristoranti. Integrando la Purple Portal API con la propria 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 del CRM con il timestamp dell'ultima visita, la posizione della sede e le informazioni sul dispositivo. Ciò consente al team di marketing di segmentare il pubblico in base a recency, frequenza e posizione, 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, passato da 24 ore (con il precedente modello di polling a lotti) a meno di 60 secondi.

Case Study 2: Retail — Multi-Site Fashion Retailer

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 solidi dati sull'e-commerce ma praticamente di nessuna informazione sul comportamento dei visitatori in negozio. Collegando l'API del guest WiFi di Purple al proprio data warehouse esistente tramite un processo ETL notturno, ha creato per la prima volta una vista cliente multicanale. 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 presentavano un valore medio dell'ordine superiore del 34% sul loro successivo acquisto online, fornendo un business case convincente per ulteriori investimenti nell'esperienza digitale in negozio. L'integrazione non ha richiesto modifiche all'infrastruttura e-commerce esistente, dimostrando la natura a basso attrito del modello di pull delle REST API.

Caso di Studio 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 su conteggi manuali e scansioni dei badge, che richiedevano molto lavoro e risultavano imprecisi. Esponendo 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 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.

Definizioni chiave

Webhook

Un meccanismo automatizzato in cui un server invia una notifica di dati in tempo reale (un push) a un'altra applicazione quando si verifica un evento specifico, tramite una richiesta HTTP POST.

Nel contesto di Purple, un Webhook invia un payload JSON con i dati del visitatore al tuo sistema nel momento stesso in cui un ospite si autentica sulla rete WiFi. Questo è fondamentale per gli aggiornamenti in tempo reale del marketing e del CRM.

REST API

Uno stile architetturale standardizzato per la creazione di servizi web che consente a un sistema di richiedere (o estrarre) dati da un altro utilizzando metodi HTTP standard come GET e POST.

I team IT utilizzano le REST API di Purple per scrivere script che estraggono dati aggregati di visitatori e sedi per l'analisi in strumenti di business intelligence come Power BI o Tableau.

API Key Authentication

Un modello di sicurezza in cui l'accesso a una API viene concesso fornendo un token segreto univoco (la chiave) con ogni richiesta, in genere nell'header HTTP Authorization.

Questo metodo è più semplice di OAuth ed è ideale per le integrazioni server-to-server. I tuoi script devono includere una API Key valida negli header della richiesta per accedere ai dati di Purple.

Idempotency

La proprietà di un'operazione per cui può essere applicata più volte senza modificare il risultato oltre l'applicazione iniziale.

Il tuo listener di Webhook dovrebbe essere idempotente. Se riceve lo stesso evento di autenticazione due volte (il che può accadere a causa di tentativi ripetuti o riconnessioni del dispositivo), non dovrebbe, ad esempio, inviare due email di benvenuto.

JSON (JavaScript Object Notation)

Un formato leggero e basato su testo per l'interscambio di dati, facile da leggere per gli esseri umani e da analizzare e generare per le macchine.

Le API e i Webhook di Purple forniscono tutti i dati in formato JSON. La tua applicazione dovrà analizzare questo JSON per estrarre campi come email, nome e numero di visite.

LogicFlow

Lo strumento visivo drag-and-drop di Purple per la creazione di flussi di lavoro automatizzati di marketing e coinvolgimento in grado di attivare azioni in base al comportamento e ai dati demografici dei visitatori.

Utilizzi LogicFlow per definire il percorso dell'ospite. È qui che colleghi il tuo Webhook, indicando al sistema di attivarlo quando un utente raggiunge lo stato "Online" del suo percorso di accesso.

Captive Portal

La pagina web che un utente visualizza e con cui deve interagire prima di poter accedere a una rete WiFi pubblica, che in genere richiede l'autenticazione o l'acquisizione di dati.

La piattaforma Purple gestisce il Captive Portal e i dati inseriti dall'utente in questa pagina (ad es. nome, email, campi personalizzati) sono quelli che diventano disponibili tramite le Portal API.

GDPR (General Data Protection Regulation)

Una legge globale sulla privacy dei dati nell'Unione Europea che disciplina la raccolta, il trattamento e la conservazione dei dati personali dei residenti nell'UE.

Le API di Purple forniscono gli strumenti per creare integrazioni conformi al GDPR, come il rispetto dello stato di disiscrizione di un utente e l'abilitazione dell'esportazione dei dati per le richieste di accesso dell'interessato. L'aggiornamento v1.7 delle API ha migliorato specificamente la chiarezza del campo relativo alla disiscrizione per supportare la conformità.

ETL (Extract, Transform, Load)

Un processo di integrazione dei dati che prevede l'estrazione dei dati da un sistema sorgente, la loro trasformazione nel formato richiesto e il loro caricamento in un sistema di destinazione come un data warehouse.

Il modello di estrazione tramite REST API viene in genere implementato come processo ETL, in cui i dati vengono estratti dall'endpoint /visitors di Purple, trasformati per corrispondere allo schema di destinazione e caricati in un CRM o in un data warehouse.

Esempi pratici

Un hotel da 200 camere desidera aggiungere automaticamente i nuovi utenti del guest WiFi al proprio percorso Salesforce Marketing Cloud e inviare un'email di benvenuto.

Nel Purple Portal, convalida un nuovo URL Webhook che punta a un endpoint sicuro (ad esempio, una funzione serverless su AWS Lambda). 2. Crea un LogicFlow 'Online' che includa il nodo Webhook, configurato per utilizzare l'URL convalidato. 3. Assegna questo LogicFlow al percorso di accesso guest WiFi dell'hotel. 4. La funzione serverless riceve il payload JSON al momento dell'autenticazione dell'ospite, estrae l'email e il nome dell'utente ed effettua una chiamata API a Salesforce Marketing Cloud per aggiungere l'utente al percorso 'Nuovo Ospite'. 5. La funzione restituisce una risposta 200 OK a Purple entro la finestra di timeout di 10 secondi.

Commento dell'esaminatore: Questa soluzione utilizza correttamente il pattern Webhook in tempo reale, ideale per azioni immediate come l'invio di un'email di benvenuto. L'uso di una funzione serverless è un modo economico e scalabile per ospitare l'endpoint del listener. Un'alternativa sarebbe stata quella di interrogare l'endpoint API /visitors, ma ciò avrebbe introdotto un ritardo fino a 24 ore e sarebbe stato significativamente meno efficiente per un requisito in tempo reale.

Una catena di negozi con 50 punti vendita desidera creare una dashboard centrale in Power BI per analizzare le tendenze dei visitatori in tutte le sedi.

Crea uno script (ad esempio, in Python) da eseguire con pianificazione notturna. 2. Lo script si autentica alla Purple Portal API utilizzando la chiave API dell'azienda. 3. Esegue un ciclo su ciascuno dei 50 ID sede, effettuando una chiamata all'endpoint /visitors per ognuno di essi al fine di recuperare tutti i dati dei visitatori del giorno precedente. 4. Lo script trasforma e carica questi dati in un data warehouse centrale (ad esempio, Azure SQL o BigQuery). 5. Power BI viene collegato al data warehouse per creare la dashboard di analisi cross-sede.

Commento dell'esaminatore: Questo è un classico processo ETL (Extract, Transform, Load) ed è l'uso corretto del pattern di polling della REST API. È adatto per l'aggregazione di dati su larga scala non in tempo reale per la business intelligence. L'uso di un data warehouse centrale è una best practice per le prestazioni e la scalabilità quando si gestiscono dati provenienti da più fonti. L'assenza di limiti di frequenza (rate limit) sulla Purple API consente allo script di elaborare tutte le 50 sedi senza problemi di limitazione del traffico.

Domande di esercitazione

Q1. Uno stadio desidera identificare i titolari di abbonamenti VIP quando si connettono al WiFi e inviare una notifica alla dashboard del responsabile dell'ospitalità più vicino. Quale modello di integrazione dovrebbero utilizzare e perché?

Suggerimento: Considera la velocità richiesta per la notifica e se l'azione è attivata da un evento.

Visualizza risposta modello

Dovrebbero utilizzare il modello Webhook (push). Si tratta di un requisito in tempo reale: quando il VIP si connette, un Webhook si attiva immediatamente verso un servizio che verifica l'e-mail o l'indirizzo MAC dell'utente nel database degli abbonati. Se viene trovata una corrispondenza, invia una notifica alla dashboard dell'ospitalità pertinente. Un modello API REST (pull) sarebbe troppo lento, poiché si basa su interrogazioni periodiche e potrebbe introdurre ritardi di minuti o ore.

Q2. Hai il compito di creare un report giornaliero dei 10 locali più visitati della tua catena nazionale di caffetterie. Come faresti a recuperare i dati necessari da Purple?

Suggerimento: Si tratta di un requisito di reportistica in tempo reale o batch? Quale endpoint interrogheresti?

Visualizza risposta modello

Si tratta di un'attività di reportistica batch, quindi il modello API REST (pull) è appropriato. Uno script pianificato verrebbe eseguito quotidianamente, interrogherebbe l'endpoint /visitors per ciascun locale, aggregherebbe i conteggi delle visite del giorno precedente e calcolerebbe quindi i primi 10. Non c'è bisogno della notifica quasi istantanea fornita dai Webhook. L'assenza di limiti di frequenza (rate limit) consente di interrogare tutti i locali in un'unica esecuzione dello script senza problemi di limitazione delle richieste.

Q3. L'endpoint del tuo listener Webhook sta fallendo. Controlli i log e vedi un errore di timeout. Qual è la causa più probabile secondo la documentazione di Purple e quali sono le due conseguenze immediate?

Suggerimento: Pensa ai requisiti di prestazioni di un listener e a cosa fa Purple quando non riesce a consegnare un payload.

Visualizza risposta modello

La causa più probabile è che il listener impiega più di 10 secondi per elaborare il payload JSON in arrivo e restituire una risposta 200 OK. Le due conseguenze immediate sono: (1) Purple smetterà di tentare di inviare la richiesta corrente e la reinserirà in coda per un tentativo di riprovo dopo 3 ore, il che significa che la consegna dei dati subirà un ritardo; e (2) se questa situazione persiste per un periodo prolungato, Purple disabiliterà automaticamente il Webhook del tutto, richiedendo una nuova verifica manuale nel portale prima di poterlo riattivare.

Continua a leggere questa serie

Integrazione di CommScope Ruckus con Purple WiFi: Guida alla Configurazione e all'Installazione

Questa guida di riferimento tecnico fornisce un manuale di configurazione autorevole per l'integrazione delle architetture CommScope Ruckus con Purple WiFi. Dettaglia passo dopo passo le implementazioni per i Captive Portal per Guest WiFi, il WiFi aziendale sicuro per il personale tramite 802.1X e l'isolamento di rete Multi-Tenant utilizzando Ruckus Dynamic PSK.

Integrazione degli Access Point Allied Telesis con Purple WiFi

Questa guida fornisce un playbook di configurazione completo per integrare gli access point Allied Telesis serie TQ con Purple WiFi. Copre il reindirizzamento al Captive Portal esterno, l'autenticazione RADIUS 802.1X e lo steering dinamico delle VLAN utilizzando le chiavi PPSK (Private Pre-Shared Keys) per implementazioni multi-tenant sicure.

Integrazione degli Access Point Grandstream GWN con Purple WiFi

Questa guida tecnica di riferimento dettagliata spiega come integrare gli access point Grandstream GWN con la piattaforma di Guest WiFi e analytics di Purple. Copre la configurazione del Captive Portal Grandstream, le impostazioni RADIUS AAA, la configurazione del walled garden, l'autenticazione sicura del personale tramite 802.1X con instradamento VLAN dinamico e la segmentazione PPSK multi-tenant, offrendo una guida pratica e passo dopo passo per MSP e team IT che implementano WiFi per ospiti e personale su larga scala.