Purple Portal API: Was Sie damit tun können

Eine technische Referenz für IT-Manager und Netzwerkarchitekten zur optimalen Nutzung der Purple Portal API. Dieser Leitfaden beschreibt detailliert die verfügbaren Endpunkte, die Authentifizierung und praxisnahe Anwendungsfälle für die Integration von Gast-WiFi-Daten in Unternehmenssysteme zur Steigerung der Business Intelligence und der betrieblichen Effizienz. Er deckt sowohl REST API- als auch Webhook-Integrationsmuster ab, ergänzt durch konkrete Fallstudien aus den Bereichen Hotellerie, Einzelhandel und Events.

📖 9 Min. Lesezeit📝 2,212 Wörter🔧 2 ausgearbeitete Beispiele❓ 3 Übungsfragen📚 9 Schlüsseldefinitionen

Diesen Leitfaden anhören

Podcast-Transkript ansehen

Willkommen beim Purple Technical Briefing. Ich bin Senior Content Strategist hier bei Purple und werde Ihnen in den nächsten zehn Minuten einen prägnanten, praktischen Überblick über unsere Portal API geben – was sie ist, was Sie damit tun können und wie Sie sie für eine maximale geschäftliche Wirkung nutzen. Dies richtet sich an IT-Manager, Architekten und Operations Directors, die wissen müssen, wie sie ihr Gäste-WiFi von einem einfachen Dienstprogramm in ein leistungsstarkes Daten-Asset verwandeln.

Beginnen wir mit dem Kontext. Sie bieten in Ihren Standorten Gäste-WiFi an. Jeden Tag verbinden sich Hunderte oder Tausende von Menschen. Sie geben ihre E-Mail-Adresse, vielleicht ihren Namen an und stimmen Ihren Bedingungen zu. Das sind wertvolle First-Party-Daten. Das Purple-Portal bietet Ihnen hervorragende Dashboards zur Anzeige dieser Daten, aber die wahre Stärke entfaltet sich, wenn Sie diese Daten mit dem Rest Ihres Geschäfts-Ökosystems verbinden. Hier kommt die Portal API ins Spiel. Sie ist die Brücke, die es Ihren Systemen ermöglicht, programmatisch mit unserer Plattform zu kommunizieren.

Kommen wir nun zu den technischen Details. Die Portal API ist eine standardmäßige RESTful-Schnittstelle. Die Authentifizierung ist einfach und sicher und erfolgt über einen unkomplizierten API-Key. Sie müssen sich keine Sorgen über komplexe OAuth-Handshakes für die Server-zu-Server-Kommunikation machen. Ganz wichtig: Es gibt keine Ratenbegrenzungen (Rate Limits). Wir haben sie für den Unternehmenseinsatz entwickelt. Ganz gleich, ob Sie ein einzelnes Hotel oder eine nationale Kette von fünfhundert Einzelhandelsgeschäften betreiben – die API ist für Ihr Volumen ausgelegt.

Sie haben zwei Hauptmöglichkeiten, um an Daten zu gelangen. Erstens die Pull-Methode: Standard-REST-Endpunkte. Denken Sie an Endpunkte wie Besucher (visitors) und Standorte (venues). Sie können ein Skript schreiben, um diese Endpunkte nach einem Zeitplan aufzurufen, alle Besucherdaten der letzten vierundzwanzig Stunden abzurufen und sie zur Analyse in Ihr Data Warehouse zu laden. Dies ist Ihre erste Wahl für Business Intelligence, um diese Dashboards für das Gesamtbild in Power BI oder Tableau zu erstellen.

Der wirklich spannende Teil ist jedoch die Push-Methode: Webhooks. Diese ist für Echtzeit gedacht. Sie richten auf Ihrer Seite einen Listener-Endpunkt ein, und in dem Moment, in dem sich ein Gast in Ihrem WiFi authentifiziert, senden wir Ihnen ein JSON-Payload mit all seinen Details – Name, E-Mail, in welchem Standort er sich befindet, Anzahl seiner Besuche und sogar die von ihm verwendete Authentifizierungsmethode, sei es ein Registrierungsformular, ein Social Login oder etwas anderes. Es geschieht nahezu augenblicklich. Dies ermöglicht eine sofortige, personalisierte Kundenansprache. Es ist der Unterschied dazwischen, morgen eine Marketing-E-Mail zu senden oder in der Sekunde, in der ein treuer Kunde durch Ihre Tür geht, eine Willkommensbenachrichtigung mit einem einzigartigen Angebot zu senden.

Lassen Sie uns über die Datenfelder sprechen, die Sie erhalten. Die Webhook-Payload ist in vier Hauptobjekte strukturiert. Das Client-Objekt liefert Ihnen die MAC-Adresse und den User-Agent. Die Company- und Venue-Objekte liefern Ihnen die Identifikatoren und Geo-Koordinaten des spezifischen Standorts. Das Session-Objekt liefert Ihnen den Authentifizierungs-Zeitstempel. Und das User-Objekt ist der eigentliche Schatz: Vorname, Nachname, E-Mail, Geschlecht, Geburtsdatum, Mobilnummer, Postleitzahl und eine Besuchsanzahl pro Standort, die das erste und letzte Besuchsdatum anzeigt. Sie können auch benutzerdefinierte Felder aus Ihrem Registrierungsformular auf der Captive Portal-Seite erfassen. Wenn Sie also Gäste nach ihrer Treueprogrammnummer oder ihrer Zimmernummer in einem Hotel fragen, wird dies ebenfalls übertragen.

In Version 1.7 der API gibt es eine wichtige Verbesserung, die erwähnenswert ist. Das Feld „unsubscribed“ unterscheidet nun klar zwischen Nutzern, die sich aktiv vom Marketing abgemeldet haben, nachdem sie zuvor angemeldet waren, und solchen, die sich einfach nie angemeldet haben. Dies ist entscheidend für die GDPR-Konformität und für eine präzise Segmentierung. Sie möchten einen ehemaligen Abonnenten schließlich nicht genauso behandeln wie jemanden, der sich noch nie in Ihrem Marketing-Funnel befunden hat.

Lassen Sie uns die Integrationsmuster im Detail besprechen. Für das REST-API-Pull-Muster ist Ihr typischer Workflow ein geplantes Skript, vielleicht in Python oder Node.js, das jede Nacht ausgeführt wird. Es authentifiziert sich mit Ihrem API-Schlüssel, fragt den Visitors-Endpunkt für jeden Standort ab, transformiert die Daten in Ihr gewünschtes Format und lädt sie in eine zentrale Datenbank. Dies ist ein klassischer ETL-Prozess. Als Betreiber mehrerer Standorte würden Sie die Standort-IDs durchlaufen und die Daten zentral aggregieren.

Für das Webhook-Push-Muster ist die Architektur etwas anders. Sie benötigen einen öffentlich zugänglichen, SSL-gesicherten Endpunkt. Eine serverlose Funktion ist hier ideal – AWS Lambda, Azure Functions oder Google Cloud Functions. Sie ist kosteneffizient, skaliert automatisch und bewältigt die Gleichzeitigkeit, die Sie an einem stark frequentierten Standort erleben würden. Wenn die Funktion den POST-Request von Purple empfängt, sollte sie das JSON parsen, ihre Geschäftslogik ausführen – vielleicht eine CRM-Abfrage oder eine Prüfung des Treuestatus – und so schnell wie möglich eine „200 OK“-Antwort zurückgeben.

Dies bringt mich zur wichtigsten Implementierungsanforderung: Ihr Listener muss innerhalb von zehn Sekunden antworten. Wenn er das nicht tut, reiht Purple die Anfrage erneut in die Warteschlange ein und versucht es nach drei Stunden noch einmal. Dauerhafte Fehler führen dazu, dass der Webhook aus Sicherheitsgründen automatisch deaktiviert wird. Halten Sie Ihren Listener also schlank. Führen Sie nur die minimal erforderliche Verarbeitung durch, um eine schnelle Antwort zurückzugeben. Wenn Sie eine aufwendige Verarbeitung durchführen müssen, verschieben Sie das Ereignis in eine interne Warteschlange und verarbeiten Sie es asynchron.

Sehen wir uns nun einige reale Szenarien an, um dies konkret zu machen.

Stellen Sie sich ein Hotel mit zweihundert Zimmern vor. Dieses möchte neue WiFi-Gäste automatisch in eine Willkommens-E-Mail-Kampagne auf seiner Marketingplattform aufnehmen. Die Lösung ist einfach: Konfigurieren Sie einen Webhook, erstellen Sie einen einfachen serverlosen Listener und prüfen Sie bei der Ankunft der Daten eines neuen Benutzers, ob dieser bereits auf der Marketingplattform existiert. Wenn nicht, fügen Sie ihn hinzu und starten Sie die Willkommenskampagne. Das Hotel kann auch das Feld für die Anzahl der Besuche nutzen, um zwischen Erstbesuchern und wiederkehrenden Gästen zu unterscheiden und die Kommunikation entsprechend anzupassen. Ein wiederkehrender Gast erhält dann beispielsweise ein Treueangebot anstelle einer generischen Begrüßung.

Stellen Sie sich nun eine nationale Einzelhandelskette mit fünfzig Filialen vor. Diese wünscht sich ein zentrales Dashboard, das die Trends des Besucherverkehrs an allen Standorten anzeigt. Hier ist das REST API-Pull-Muster die richtige Wahl. Ein nächtliches Skript fragt den Besucher-Endpunkt für jeden der fünfzig Standorte ab, aggregiert die Daten und lädt sie in ein Data Warehouse. Das Analytics-Team erstellt daraufhin seine Dashboards. Sie können sehen, welche Filialen die höchsten Raten an neuen Besuchern aufweisen, welche das beste Verhältnis an wiederkehrenden Besuchern haben und wie die Verweildauer mit der Verkaufsleistung korreliert.

Lassen Sie mich nun einige häufige Fehlerquellen erläutern und zeigen, wie man sie vermeidet.

Die erste Fehlerquelle ist die doppelte Ereignisverarbeitung. Ein einziger Gästebesuch kann mehrere Authentifizierungsereignisse auslösen – beispielsweise, wenn sich der Bildschirmschoner des Telefons sperrt und es sich neu verbindet oder wenn der Gast zwischen Access Points hin- und herwechselt. Ihr Listener muss idempotent sein. Bevor Sie eine Aktion wie das Senden einer E-Mail ausführen, prüfen Sie, ob Sie heute bereits ein Ereignis für diesen Benutzer verarbeitet haben.

Die zweite Fehlerquelle besteht darin, die Listener-URL vor dem Live-Gang nicht zu validieren. Purple erfordert, dass Sie den Endpunkt im Portal validieren, bevor er Daten empfangen kann. Stellen Sie sicher, dass Ihr Listener live ist und den korrekten wifiWebhookListener-Header zurückgibt, bevor Sie ihn an einen LogicFlow anhängen.

Die dritte Fehlerquelle ist das Ignorieren des Abonnement-Status. Überprüfen Sie immer das Feld für abgemeldete Benutzer, bevor Sie einen Benutzer zu einer Marketingliste hinzufügen. Das Versenden von Marketing-Kommunikation an jemanden, der sich abgemeldet hat, ist ein Verstoß gegen die GDPR mit erheblichen Konsequenzen.

Nun zu einer schnellen Fragerunde.

Kann ich dies mit meinem selbst entwickelten CRM synchronisieren? Ja. Wenn Ihr CRM über eine API verfügt, können Sie einen Webhook-Listener als Middleware verwenden, um die Purple-Daten zu formatieren und in Ihr System zu übertragen. Die im Webhook-Payload zurückgegebenen IDs stimmen mit denen in der REST API überein, sodass Sie bei Bedarf auch Folgeaufrufe starten können, um zusätzliche Details abzurufen.

Wie gehe ich mit einem Benutzer um, der mehrere Standorte in meinem Unternehmen besucht? Die API liefert die Anzahl der Besuche pro Standort-ID, sodass Sie die Reise eines Kunden durch Ihr gesamtes Unternehmen problemlos verfolgen und ein umfassendes standortübergreifendes Profil erstellen können.

Gibt es ein Limit für die Anzahl der Webhook-URLs, die ich konfigurieren kann? Nein. Sie können so viele Listener-URLs validieren und verwenden, wie Sie benötigen. Dies ist besonders nützlich, wenn verschiedene Teams oder Systeme dieselben Ereignisdaten empfangen müssen.

Was passiert, wenn mein Listener wegen Wartungsarbeiten ausfällt? Purple versucht fehlgeschlagene Zustellungen erneut, sodass Sie möglicherweise einen Rückstau an Ereignissen erhalten, wenn Ihr Listener wieder online geht. Ihr Listener muss dies reibungslos verarbeiten und Ereignisse verarbeiten, die möglicherweise außerhalb der chronologischen Reihenfolge eingehen.

Um alles zusammenzufassen, was wir heute besprochen haben: Die Purple Portal API ist Ihr Schlüssel, um den immensen Wert Ihrer Gäste-WiFi-Daten freizusetzen. Nutzen Sie die REST API, um Daten für Berichte und Analysen abzurufen. Nutzen Sie Webhooks, um Daten in Echtzeit für eine sofortige, personalisierte Kundenbindung zu übertragen. Denken Sie an das Grundprinzip: Push für Echtzeit, Pull für Berichte.

Ihr nächster Schritt ist die Überprüfung der API-Dokumentation in unserem Support-Portal. Wenn Sie eine Engage-Lizenz haben, erstellen Sie einen API-Schlüssel und beginnen Sie mit der Erkundung mit Postman. Erstellen Sie einen einfachen Webhook-Listener. Sehen Sie zu, wie die Daten einfließen. Das ist der Moment, in dem das Potenzial dieses Tools glasklar wird.

Vielen Dank, dass Sie sich das Purple Technical Briefing angehört haben. Wenn Sie mit einem unserer Lösungsarchitekten über Ihre spezifischen Integrationsanforderungen sprechen möchten, besuchen Sie purple.ai und buchen Sie eine Demo. Bis zum nächsten Mal.

Wichtigste Erkenntnisse

✓Die Purple Portal API bietet programmatischen Zugriff auf Gast-WiFi-Daten über eine einfache API-Key-Authentifizierung, ohne Ratenbegrenzungen.
✓Sie erfordert eine Engage-Lizenz und läuft derzeit auf Version v1.7, die die GDPR-Konformität durch eine klarere Handhabung des Abmeldestatus verbessert hat.
✓Nutzen Sie die REST API (Pull) für Batch-Datenexporte, ETL-Prozesse und Analyse-Dashboards.
✓Nutzen Sie Webhooks (Push) für ereignisgesteuerte Aktionen in Echtzeit wie CRM-Synchronisierungen, personalisierte Nachrichten und Loyalty-Trigger.
✓Webhook-Listener müssen SSL-gesichert sein, innerhalb von 10 Sekunden antworten und so konzipiert sein, dass sie doppelte Ereignisse idempotent verarbeiten.
✓Die wichtigsten Anwendungsfälle erstrecken sich über das Gastgewerbe (CRM-Anreicherung in Echtzeit), den Einzelhandel (kanalübergreifende Analysen) und Events (verifizierte Besucherdaten für Sponsoren).
✓Die API ermöglicht es Unternehmen, ihre WiFi-Infrastruktur von einer Kostenstelle in ein strategisches Daten-Asset mit einem klaren, messbaren ROI zu verwandeln.

Executive Summary

Für IT-Entscheider an Multi-Site-Standorten – wie Hotels, Einzelhandelsketten, Stadien und Konferenzzentren – ist das Gäste-WiFi weit mehr als eine einfache Annehmlichkeit. Es ist eine reichhaltige, sich kontinuierlich erneuernde Quelle für First-Party-Daten, die messbare geschäftliche Erfolge in den Bereichen Marketing, Betrieb und Customer Experience erzielen kann. Die Purple Portal API bietet die programmierbare Schnittstelle, die erforderlich ist, um diesen Wert in großem Maßstab freizusetzen. Sie ermöglicht es technischen Teams, über die integrierten Analyse-Dashboards hinauszugehen und robuste, automatisierte Integrationen aufzubauen, die GDPR-konforme Besucherdaten direkt in zentrale Geschäftssysteme einspeisen – von CRM-Plattformen und Marketing-Automatisierungstools bis hin zu Treueprogrammen und Business-Intelligence-Warehouses.

Dieser Leitfaden ist eine praktische, direkt anwendbare Referenz für Lösungsarchitekten, IT-Manager und Senior-Entwickler. Er beschreibt das Authentifizierungsmodell, die verfügbaren Endpunkte, Integrationsmuster und reale Bereitstellungsszenarien, die zeigen, wie die Purple WiFi API eine WiFi-Bereitstellung von einem Kostenfaktor in ein strategisches Daten-Asset verwandeln kann. Unabhängig davon, ob Sie die API zum ersten Mal evaluieren oder eine produktionsreife Integration planen, bietet dieses Dokument die technischen Grundlagen und Entscheidungsrahmen, die Sie benötigen, um Ihr Projekt erfolgreich umzusetzen.

Technischer Deep-Dive

Authentifizierung und API-Versionierung

Die Purple Portal API verwendet die API-Key-Authentifizierung, ein unkompliziertes und sicheres Modell, das sich hervorragend für Server-zu-Server-Integrationen eignet. Im Gegensatz zu OAuth 2.0-Flows, die Token-Austausch- und Refresh-Zyklen erfordern, wird bei der API-Key-Authentifizierung ein statisches Secret in den Request-Headern übergeben. Diese Einfachheit reduziert den Integrationsaufwand, ohne die Sicherheit zu beeinträchtigen – vorausgesetzt, der Key wird sicher gespeichert und im Rahmen Ihrer Standard-Richtlinien zur Verwaltung von Anmeldedaten regelmäßig rotiert.

Die aktuelle Produktionsversion ist v1.7, die mehrere wichtige Verbesserungen gegenüber v1.6.2 eingeführt hat. Besonders hervorzuheben ist, dass die Eigenschaft unsubscribed im Benutzerdatenobjekt nun klar zwischen einem Benutzer unterscheidet, der sich aktiv vom Marketing abgemeldet hat, nachdem er zuvor angemeldet war, und einem Benutzer, der sich überhaupt nie angemeldet hat. Diese Unterscheidung ist entscheidend für die GDPR-Konformität und für eine präzise Zielgruppensegmentierung. Darüber hinaus geben die Endpunkte Visitors und Venues nun eine HTTP-Antwort 200 OK zurück, wenn keine Daten gefunden werden, anstatt eines 404 Not Found, was zuvor zu Verwirrung in der Monitoring- und Fehlerbehandlungslogik geführt hatte.

Verfügbare Endpunkte

Die Portal Company API stellt drei primäre Endpunktkategorien bereit, mit denen IT-Teams regelmäßig interagieren.

Endpunkt	Methode	Zweck
`/visitors`	GET	Abrufen von Gästebesucherprofilen, einschließlich Kontaktdaten, Demografie und Besuchsverlauf
`/venues`	GET	Abrufen von Daten auf Standortebene und Konfigurations-Metadaten
`/unsubscribes`	GET	Ruft eine Liste von Benutzern ab, die sich von Marketing-Mitteilungen abgemeldet haben

Alle Endpunkte geben Daten im JSON-Format zurück. Der Endpunkt visitors wird am häufigsten verwendet, da er die gesamte Fülle der Gästeprofildaten offenlegt, die während der Authentifizierung am Captive Portal erfasst wurden. Dies umfasst Vorname, Nachname, E-Mail-Adresse, Geschlecht, Geburtsdatum, Mobilnummer, Postleitzahl, Authentifizierungsanbieter (z. B. Registrierungsformular, Social Login), Anzahl der Besuche pro Standort sowie alle auf der Splash-Page konfigurierten benutzerdefinierten Felder.

Rate Limits

Ein wesentlicher architektonischer Vorteil der Purple Portal API ist, dass keine Rate Limits existieren. Die Plattform ist so konzipiert, dass sie jedes Volumen an Anfragen oder Transaktionen unterstützt. Dadurch eignet sie sich für großflächige Implementierungen, bei denen Skripte möglicherweise Tausende von Standortdatensätzen oder Millionen von Besucherprofilen verarbeiten müssen. Dies beseitigt eine häufige Einschränkung, die das Integrationsdesign mit anderen Plattformen kompliziert, und macht eine Drosselung von Anfragen oder Back-off-Logik in Ihrem Client-Code überflüssig.

Integrationsmuster: Pull vs. Push

Die Purple WiFi API unterstützt zwei grundlegend unterschiedliche Integrationsmuster, die sich jeweils für verschiedene Anwendungsfälle eignen. Zu verstehen, welches Muster in einem bestimmten Szenario anzuwenden ist, ist die wichtigste architektonische Entscheidung, die Sie treffen müssen.

Das REST API Pull-Muster beinhaltet, dass Ihr System bei Bedarf oder nach Zeitplan Anfragen an die API-Endpunkte stellt, um Daten abzurufen. Dies ist der richtige Ansatz für Batch-Verarbeitung, Reporting und Business Intelligence. Ein nächtliches ETL-Skript, das alle Besucherdaten des Vortrags abruft und in ein Data Warehouse lädt, ist ein klassisches Beispiel. Das Pull-Muster gibt Ihnen die volle Kontrolle darüber, wann und wie viele Daten Sie abrufen.

Das Webhook Push-Muster beinhaltet, dass Purple Daten an Ihr System sendet, sobald ein bestimmtes Ereignis eintritt – konkret, wenn sich ein Gast im WiFi-Netzwerk authentifiziert. Ihr System muss einen öffentlich zugänglichen, SSL-gesicherten HTTP-Endpunkt (einen „Listener“) bereitstellen, der diese JSON-POST-Payloads empfangen und verarbeiten kann. Das Webhook-Muster ist die richtige Wahl für alle Anwendungsfälle, die Daten in Fast-Echtzeit erfordern, wie z. B. das Auslösen einer personalisierten Begrüßungsnachricht, das Aktualisieren des Status „Zuletzt gesehen“ eines Kunden in einem CRM oder das Benachrichtigen eines Hospitality-Managers über die Ankunft eines VIP-Gastes.

Webhook Payload-Struktur

Die von einem Purple Webhook übermittelte JSON-Payload ist in vier Hauptobjekte unterteilt, von denen jedes eine andere Dimension des Kontexts für das Authentifizierungsereignis liefert.

Objekt	Schlüsselfelder	Beschreibung
`client`	`mac`, `userAgent`	Identifikatoren auf Geräteebene
`company`	`id`, `name`, `uniqId`	Details zu Ihrem Unternehmenskonto
`venue`	`id`, `name`, `latitude`, `longitude`	Der spezifische Standort, an dem die Authentifizierung stattfand
`session`	`authenticationTime`	ISO 8601-Zeitstempel des Authentifizierungsereignisses
`user`	`email`, `firstName`, `lastName`, `gender`, `provider`, `visitCountForVenues`, `customFields`	Vollständige Gastprofildaten

Das Objekt user.visitCountForVenues ist besonders wertvoll für Betreiber mehrerer Standorte. Es liefert eine standortbezogene Anzahl der Besuche zusammen mit den Zeitstempeln firstVisit und lastVisit. So können Sie Erstbesucher von treuen, wiederkehrenden Kunden direkt zum Zeitpunkt der Authentifizierung unterscheiden – ganz ohne zusätzliche API-Aufrufe.

Implementierungsleitfaden

Voraussetzungen und Einrichtung

Der Zugriff auf die Portal-API erfordert eine Engage-Lizenz. Sobald Sie lizenziert sind, generieren Sie Ihren API-Schlüssel in den Einstellungen des Purple-Portals. Für die erste Entwicklung und Tests wird Postman als Tool empfohlen. Purple bietet eine spezielle Einrichtungsanleitung zur Konfiguration der korrekten Umgebungsvariablen und Request-Header. Für Teams, die einen serverseitigen Skript-Startpunkt bevorzugen, steht auch eine PHP-Demodatei zur Verfügung.

Konfiguration einer Webhook-Integration

Die Bereitstellung einer Webhook-Integration umfasst fünf Schritte. Erstellen und implementieren Sie zunächst Ihren Listener-Endpunkt unter einer öffentlich zugänglichen, SSL-gesicherten URL. Eine serverlose Funktion (AWS Lambda, Azure Functions oder Google Cloud Functions) ist eine architektonisch solide Wahl: Sie skaliert automatisch, verursacht bei geringem Volumen minimale Kosten und verarbeitet gleichzeitige Anfragen ohne Konfigurationsaufwand. Validieren Sie zweitens die Listener-URL im Purple-Portal unter Verwaltung > Standorte > Webhooks. Purple sendet eine Testanfrage, um zu bestätigen, dass der Endpunkt erreichbar ist und den erforderlichen Header wifiWebhookListener: 1 zurückgibt. Drittens: Erstellen oder bearbeiten Sie einen LogicFlow im Portal, fügen Sie einen Webhook-Aktionsknoten hinzu und wählen Sie Ihre validierte URL aus. Viertens: Stellen Sie sicher, dass der LogicFlow den Status „Online“ hat. Fünftens: Verknüpfen Sie den LogicFlow mit der entsprechenden Access Journey. Ab diesem Zeitpunkt löst jede Gastauthentifizierung auf dieser Journey Ihren Webhook aus.

Umgang mit Wiederholungsversuchen und Idempotenz

Ihr Listener muss so konzipiert sein, dass er mit den Gegebenheiten verteilter Systeme umgehen kann. Purple wiederholt eine fehlgeschlagene Webhook-Zustellung nach drei Stunden, wenn Ihr Listener nicht reagiert (Timeout überschreitet 10 Sekunden) oder einen Fehlerstatus zurückgibt. Das bedeutet, dass Ihr Listener dasselbe Ereignis mehrmals empfangen kann. Darüber hinaus kann ein einziger Gastbesuch mehrere Authentifizierungsereignisse auslösen – beispielsweise, wenn sich ein Gerät nach der Bildschirmsperre erneut verbindet oder wenn ein Benutzer zwischen Access Points wechselt. Ihre Verarbeitungslogik muss daher idempotent sein: Die zweimalige Anwendung desselben Ereignisses sollte das gleiche Ergebnis liefern wie die einmalige Anwendung. Ein gängiges Implementierungsmuster besteht darin, vor der Ausführung einer Aktion (z. B. dem Versenden einer Begrüßungs-E-Mail) zu prüfen, ob diese für eine bestimmte Benutzer-ID innerhalb eines definierten Zeitfensters bereits durchgeführt wurde.

Best Practices

Mehrere Prinzipien sollten jede Produktivbereitstellung der Purple Portal API leiten. Führen Sie Deployments immer gegen die neueste API-Version (v1.7) durch und aktualisieren Sie Ihre URL-Pfade sowie die Logik zur Antwortanalyse, wenn neue Versionen veröffentlicht werden. Behandeln Sie Ihren API-Schlüssel wie ein sensibles Anmeldedatum: Speichern Sie ihn in einem Secrets Manager (wie AWS Secrets Manager oder Azure Key Vault) und nicht im Quellcode oder in Umgebungsvariablen auf gemeinsam genutzten Systemen. Implementieren Sie für Webhook-Listener eine strukturierte Protokollierung aller eingehenden Payloads und Antworten, um das Debugging und Audit-Trails zu erleichtern. Beachten Sie die Felder unsubscribed und unsubscribedDate im Benutzerobjekt; die Verarbeitung von Marketingaktionen für abgemeldete Benutzer stellt einen Verstoß gegen die GDPR dar. Testen Sie Ihre Integration schließlich mit der gesamten Bandbreite an Grenzfällen: Benutzer ohne E-Mail-Adresse, Benutzer mit benutzerdefinierten Feldern, die null sind, und Authentifizierungsereignisse, die außerhalb der chronologischen Reihenfolge eingehen.

Fehlerbehebung & Risikominderung

Das häufigste Fehlerszenario bei einer Webhook-Integration ist ein langsamer oder nicht verfügbarer Listener. Wenn der Endpunkt dauerhaft nicht innerhalb von 10 Sekunden antwortet, deaktiviert Purple den Webhook nach einer längeren Phase der Inaktivität automatisch, was eine manuelle erneute Verifizierung im Portal erfordert. Um dieses Risiko zu minimieren, implementieren Sie einen Health-Check-Endpunkt auf demselben Server wie Ihr Listener und binden Sie diesen in Ihre Infrastrukturüberwachung ein. Stellen Sie sicher, dass Ihr Listener nur eine minimale synchrone Verarbeitung durchführt, bevor er eine 200 OK-Antwort zurückgibt; verlagern Sie rechenintensive Prozesse oder nachgelagerte API-Aufrufe in eine asynchrone Warteschlange.

Bei REST-API-Integrationen besteht das Hauptrisiko in veralteten Daten in nachgelagerten Systemen, falls der geplante Pull-Job unbemerkt fehlschlägt. Richten Sie Warnmeldungen für Ihre ETL-Skripte ein, um das Betriebsteam zu benachrichtigen, wenn ein Durchlauf fehlschlägt oder unerwartet keine Ausgabe erzeugt. Überprüfen Sie beim Upgrade von API v1.6.2 auf v1.7 den gesamten Code, der sich auf das Feld unsubscribed und den Endpunkt Unsubscribes bezieht, da der Eigenschaftsname in v1.7 von unsubcribers in unsubscribers korrigiert wurde.

ROI & geschäftliche Auswirkungen

Der Business Case für die Integration mit der Purple Portal API ist über mehrere Branchen hinweg bestens etabliert. Im Gastgewerbe berichten Hotels, die Webhook-gesteuerte CRM-Integrationen nutzen, von signifikanten Verbesserungen der E-Mail-Öffnungsraten für personalisierte Kommunikation im Vergleich zu generischen Broadcast-Kampagnen, da die Nachricht im Moment maximaler Relevanz zugestellt wird – genau dann, wenn der Gast physisch vor Ort ist. Im Einzelhandel ermöglicht die Verknüpfung von Gäste-WiFi-Daten mit einem Treueprogramm den Betreibern, besonders aktive Besucher zu identifizieren und zu belohnen, was den durchschnittlichen Umsatz und die Rate der wiederkehrenden Besuche steigert. Für große öffentliche Veranstaltungsorte und Konferenzzentren liefern API-gestützte Analysen die detaillierten Besucherfrequenzdaten, die zur Rechtfertigung von Sponsoring-Bewertungen und zur Optimierung der Platzierung von Verkaufsständen erforderlich sind.

Das Fehlen von Ratenbegrenzungen bei der Purple WiFi API bedeutet, dass die Kosten für die Integration mit Ihrer Infrastruktur skalieren und nicht mit dem Volumen der von Ihnen verarbeiteten Daten. Für eine nationale Einzelhandelskette, die täglich Hunderttausende von Authentifizierungen verarbeitet, ist dies ein wesentlicher Vorteil gegenüber Plattformen, die pro API-Aufruf abrechnen oder Durchsatzgrenzen auferlegen. Die Gesamtbetriebskosten für eine gut strukturierte Purple API-Integration bestehen daher in erster Linie aus den einmaligen Entwicklungskosten und den laufenden Infrastrukturkosten des Listeners, die sich in der Regel bereits im ersten Quartal allein durch verbesserte Marketing-Konversionsraten amortisieren.

Fallstudien

Fallstudie 1: Gastgewerbe — Whitbread Group

Whitbread, das größte Hotel- und Gastronomieunternehmen Großbritanniens, betreibt Tausende von Gäste-WiFi-Access-Points in seinen Premier Inn- und Restaurant-Standorten. Durch die Integration der Purple Portal API in ihre CRM-Plattform war die Gruppe in der Lage, ein einheitliches Gästeprofil zu erstellen, das Online-Buchungsdaten mit dem physischen Besuchsverhalten kombinierte, das am Captive Portal des WiFi erfasst wurde. Die Webhook-Integration wird bei jeder Gäste-Authentifizierung ausgelöst und reichert den CRM-Datensatz mit dem neuesten Besuchszeitstempel, dem Standort des Veranstaltungsortes und Geräteinformationen an. Dies ermöglicht es dem Marketingteam, Zielgruppen nach Aktualität, Häufigkeit und Standort zu segmentieren und hochgradig personalisierte Re-Engagement-Kampagnen auszulösen. Das wichtigste technische Ergebnis war eine Verkürzung der Zeit zwischen der Ankunft eines Gastes und seinem Eintritt in eine aktive Marketing-Journey von 24 Stunden (unter dem vorherigen Batch-Polling-Modell) auf unter 60 Sekunden.

Fallstudie 2: Einzelhandel — Multi-Site-Modehändler

Ein nationaler Modeeinzelhändler mit über 80 Filialen nutzte die Purple Portal API, um eine kritische Lücke in seiner Kundendatenstrategie zu schließen: Er verfügte über starke E-Commerce-Daten, hatte aber praktisch keine Einblicke in das Verhalten der Besucher in den Filialen. Durch die Anbindung der Purple Gäste-WiFi-API an ihr bestehendes Data Warehouse über einen nächtlichen ETL-Prozess erstellten sie zum ersten Mal eine kanalübergreifende Kundenansicht. Der Endpunkt /visitors wurde jede Nacht für jede Filiale abgefragt, und die Daten wurden unter Verwendung der E-Mail-Adresse als gemeinsamem Schlüssel mit den E-Commerce-Transaktionsdaten zusammengeführt. Innerhalb von drei Monaten stellte das Analyseteam fest, dass Kunden, die sich mit dem WiFi in der Filiale verbanden, bei ihrem nächsten Online-Einkauf einen um 34 % höheren durchschnittlichen Bestellwert hatten, was ein überzeugendes Argument für weitere Investitionen in das digitale Erlebnis in der Filiale lieferte. Die Integration erforderte keine Änderungen an der bestehenden E-Commerce-Infrastruktur, was die reibungslose Natur des REST-API-Pull-Musters demonstriert.

Fallstudie 3: Events — Konferenzzentrum

Ein großes Konferenzzentrum in Großbritannien nutzte die Purple Portal API, um Sponsoren zum ersten Mal verifizierte Besucherdaten zur Verfügung zu stellen. Zuvor stützten sich die Sponsorenberichte auf manuelle Zählungen und Badge-Scans, was arbeitsintensiv und ungenau war. Durch die Bereitstellung aggregierter, anonymisierter Besucherzahlen pro Zone (zugeordnet zu Standort-IDs in der Purple-Plattform) über die API konnte das Event-Team den Sponsoren Echtzeit-Dashboards zur Verfügung stellen, die die Verweildauer und das Besuchervolumen in den gesponserten Bereichen anzeigten. Die Daten wurden während der Veranstaltungen alle 15 Minuten über die REST-API abgerufen und auf einem speziell entwickelten Sponsorenportal angezeigt. Diese Funktion trug im ersten Jahr direkt zu einer Steigerung der Sponsoring-Verlängerungsraten um 22 % bei, da Sponsoren die Reichweite ihrer Aktivitäten nun mit verifizierten First-Party-Daten quantifizieren konnten.

Schlüsseldefinitionen

Webhook

Ein automatisierter Mechanismus, bei dem ein Server eine Echtzeit-Datenbenachrichtigung (einen Push) über eine HTTP-POST-Anfrage an eine andere Anwendung sendet, wenn ein bestimmtes Ereignis eintritt.

Im Purple-Kontext sendet ein Webhook ein JSON-Payload mit Besucherdaten an Ihr System, sobald sich ein Gast im WiFi-Netzwerk authentifiziert. Dies ist entscheidend für Echtzeit-Marketing und CRM-Aktualisierungen.

REST API

Ein standardisierter Architekturstil für die Erstellung von Webdiensten, der es einem System ermöglicht, Daten von einem anderen System mithilfe von Standard-HTTP-Methoden wie GET und POST abzurufen (oder zu pullen).

IT-Teams nutzen die Purple REST API, um Skripte zu schreiben, die Massendaten von Besuchern und Standorten zur Analyse in Business-Intelligence-Tools wie Power BI oder Tableau abrufen.

API Key Authentication

Ein Sicherheitsmodell, bei dem der Zugriff auf eine API gewährt wird, indem bei jeder Anfrage ein eindeutiges, geheimes Token (der Schlüssel) bereitgestellt wird, in der Regel im HTTP-Authorization-Header.

Dies ist einfacher als OAuth und ideal für Server-zu-Server-Integrationen. Ihre Skripte müssen den gültigen API-Schlüssel in den Anfrage-Headern enthalten, um auf die Daten von Purple zuzugreifen.

Idempotency

Eine Eigenschaft einer Operation, die besagt, dass sie mehrmals angewendet werden kann, ohne das Ergebnis über die erste Anwendung hinaus zu verändern.

Ihr Webhook-Listener sollte idempotent sein. Wenn er dasselbe Authentifizierungsereignis zweimal empfängt (was aufgrund von Wiederholungsversuchen oder erneuten Geräteverbindungen passieren kann), sollte er beispielsweise nicht zwei Willkommens-E-Mails senden.

JSON (JavaScript Object Notation)

Ein leichtgewichtiges, textbasiertes Format für den Datenaustausch, das für Menschen einfach zu lesen und für Maschinen einfach zu parsen und zu generieren ist.

Die Purple API und Webhooks liefern alle Daten im JSON-Format. Ihre Anwendung muss dieses JSON parsen, um Felder wie E-Mail, Name und Anzahl der Besuche zu extrahieren.

LogicFlow

Das visuelle Drag-and-Drop-Tool von Purple zur Erstellung automatisierter Marketing- und Engagement-Workflows, die Aktionen basierend auf dem Verhalten und der Demografie der Besucher auslösen können.

Sie verwenden LogicFlow, um die Customer Journey des Gastes zu definieren. Hier binden Sie Ihren Webhook ein und weisen das System an, ihn auszulösen, wenn ein Benutzer den Status "Online" seiner Zugangsreise erreicht.

Captive Portal

Die Webseite, die ein Benutzer sieht und mit der er interagieren muss, bevor ihm Zugriff auf ein öffentliches WiFi-Netzwerk gewährt wird, was in der Regel eine Authentifizierung oder Datenerfassung erfordert.

Die Purple-Plattform betreibt das Captive Portal, und die vom Benutzer auf dieser Seite eingegebenen Daten (z. B. Name, E-Mail, benutzerdefinierte Felder) sind diejenigen, die über die Portal API verfügbar werden.

GDPR (General Data Protection Regulation)

Ein umfassendes Datenschutzgesetz in der Europäischen Union, das die Erhebung, Verarbeitung und Speicherung personenbezogener Daten von Personen mit Wohnsitz in der EU regelt.

Die Purple API bietet die Tools zur Erstellung GDPR-konformer Integrationen, wie z. B. die Berücksichtigung des Abmeldestatus eines Benutzers und die Ermöglichung des Datenexports für Auskunftsbegehren. Das API-Update v1.7 hat speziell die Klarheit des Abmeldefelds verbessert, um die Compliance zu unterstützen.

ETL (Extract, Transform, Load)

Ein Datenintegrationsprozess, bei dem Daten aus einem Quellsystem extrahiert, in das erforderliche Format transformiert und in ein Zielsystem wie ein Data Warehouse geladen werden.

Das REST API-Pull-Muster wird typischerweise als ETL-Prozess implementiert, bei dem Daten aus dem /visitors-Endpunkt von Purple extrahiert, an das Zielschema angepasst und in ein CRM oder Data Warehouse geladen werden.

Ausgearbeitete Beispiele

Ein Hotel mit 200 Zimmern möchte neue Gast-WiFi-Nutzer automatisch zu seiner Salesforce Marketing Cloud Journey hinzufügen und eine Begrüßungs-E-Mail senden.

Validieren Sie im Purple Portal eine neue Webhook-URL, die auf einen sicheren Endpunkt verweist (z. B. eine serverlose Funktion auf AWS Lambda). 2. Erstellen Sie einen "Online"-LogicFlow, der den Webhook-Knoten enthält und für die Verwendung der validierten URL konfiguriert ist. 3. Weisen Sie diesen LogicFlow der Gast-WiFi-Access-Journey des Hotels zu. 4. Die serverlose Funktion empfängt bei der Gast-Authentifizierung den JSON-Payload, extrahiert die E-Mail-Adresse und den Namen des Nutzers und führt einen API-Aufruf an die Salesforce Marketing Cloud aus, um den Nutzer zur "New Guest"-Journey hinzuzufügen. 5. Die Funktion gibt innerhalb des 10-sekündigen Timeout-Fensters eine "200 OK"-Antwort an Purple zurück.

Kommentar des Prüfers: Diese Lösung nutzt korrekt das Echtzeit-Webhook-Muster, das sich ideal für sofortige Aktionen wie das Versenden einer Begrüßungs-E-Mail eignet. Die Verwendung einer serverlosen Funktion ist eine kosteneffiziente und skalierbare Methode zum Hosten des Listener-Endpunkts. Eine Alternative wäre das Abfragen des /visitors-API-Endpunkts, was jedoch zu einer Verzögerung von bis zu 24 Stunden führen würde und für eine Echtzeitanforderung erheblich ineffizienter wäre.

Eine Einzelhandelskette mit 50 Filialen möchte ein zentrales Dashboard in Power BI erstellen, um Besuchertrends an allen Standorten zu analysieren.

Erstellen Sie ein Skript (z. B. in Python), das nach einem nächtlichen Zeitplan ausgeführt wird. 2. Das Skript authentifiziert sich bei der Purple Portal API unter Verwendung des API-Schlüssels des Unternehmens. 3. Es iteriert durch jede der 50 Standort-IDs und ruft für jede den Endpunkt /visitors auf, um alle Besucherdaten des Vortrags abzurufen. 4. Das Skript transformiert und lädt diese Daten in ein zentrales Data Warehouse (z. B. Azure SQL oder BigQuery). 5. Power BI wird mit dem Data Warehouse verbunden, um das standortübergreifende Analyse-Dashboard zu erstellen.

Kommentar des Prüfers: Dies ist ein klassischer ETL-Prozess (Extract, Transform, Load) und die korrekte Anwendung des Polling-Musters der REST API. Er eignet sich für die zeitversetzte, großflächige Datenaggregation für Business Intelligence. Die Verwendung eines zentralen Data Warehouse ist eine Best Practice für Performance und Skalierbarkeit bei der Verarbeitung von Daten aus mehreren Quellen. Da die Purple API keine Ratenbegrenzungen (Rate Limits) aufweist, kann das Skript alle 50 Standorte ohne Drosselungsprobleme verarbeiten.

Übungsfragen

Q1. Ein Stadion möchte VIP-Dauerkarteninhaber identifizieren, wenn sie sich mit dem WiFi verbinden, und eine Benachrichtigung an das Dashboard des nächstgelegenen Hospitality-Managers senden. Welches Integrationsmuster sollten sie verwenden und warum?

Hinweis: Berücksichtigen Sie die erforderliche Geschwindigkeit der Benachrichtigung und ob die Aktion durch ein Ereignis ausgelöst wird.

Musterlösung anzeigen

Sie sollten das Webhook-Muster (Push) verwenden. Dies ist eine Echtzeitanforderung: Wenn sich der VIP verbindet, wird sofort ein Webhook an einen Dienst gesendet, der die E-Mail- oder MAC-Adresse des Benutzers mit der Dauerkarteninhaber-Datenbank abgleicht. Wenn eine Übereinstimmung gefunden wird, sendet er eine Benachrichtigung an das entsprechende Hospitality-Dashboard. Ein REST API-Muster (Pull) wäre zu langsam, da es auf periodischem Polling basiert und Verzögerungen von Minuten oder Stunden verursachen könnte.

Q2. Sie haben die Aufgabe, einen täglichen Bericht über die 10 am häufigsten besuchten Standorte Ihrer nationalen Café-Kette zu erstellen. Wie würden Sie die erforderlichen Daten von Purple abrufen?

Hinweis: Handelt es sich um eine Echtzeit- oder eine Batch-Berichtsanforderung? Welchen Endpunkt würden Sie abfragen?

Musterlösung anzeigen

Dies ist eine Batch-Berichtsaufgabe, daher ist das REST API-Muster (Pull) angemessen. Ein geplantes Skript würde täglich ausgeführt, den Endpunkt /visitors für jeden Standort abfragen, die Besuchszahlen für den Vortag aggregieren und dann die Top 10 berechnen. Die nahezu sofortige Benachrichtigung durch Webhooks ist hier nicht erforderlich. Da keine Ratenbegrenzungen vorliegen, können alle Standorte in einem einzigen Skriptdurchlauf ohne Drosselungsprobleme abgefragt werden.

Q3. Ihr Webhook-Listener-Endpunkt schlägt fehl. Sie überprüfen die Protokolle und sehen einen Timeout-Fehler. Was ist laut der Dokumentation von Purple die wahrscheinlichste Ursache und welches sind die zwei unmittelbaren Folgen?

Hinweis: Denken Sie an die Leistungsanforderungen eines Listeners und daran, was Purple tut, wenn eine Payload nicht zugestellt werden kann.

Musterlösung anzeigen

Die wahrscheinlichste Ursache ist, dass der Listener länger als 10 Sekunden benötigt, um die eingehende JSON-Payload zu verarbeiten und eine 200-OK-Antwort zurückzugeben. Die zwei unmittelbaren Folgen sind: (1) Purple bricht den aktuellen Sendeversuch ab und reiht die Anfrage für einen erneuten Versuch in 3 Stunden wieder ein, was die Datenbereitstellung verzögert; und (2) wenn dies über einen längeren Zeitraum anhält, deaktiviert Purple den Webhook automatisch vollständig, was eine manuelle Neuverifizierung im Portal erfordert, bevor er wieder aktiviert werden kann.

Weiterlesen in dieser Reihe

CommScope Ruckus Integration mit Purple WiFi: Einrichtungs- und Konfigurationshandbuch

Dieses technische Referenzhandbuch bietet einen maßgeblichen Konfigurationsleitfaden für die Integration von CommScope Ruckus-Architekturen mit Purple WiFi. Es beschreibt Schritt-für-Schritt-Bereitstellungen für Guest WiFi Captive Portals, sicheres Mitarbeiter-WiFi über 802.1X und mandantenfähige Netzwerkisolierung mithilfe von Ruckus Dynamic PSK.

Allied Telesis Access Points Integration mit Purple WiFi

Dieses Handbuch bietet eine umfassende Konfigurationsanleitung für die Integration von Allied Telesis Access Points der TQ-Serie mit Purple WiFi. Es behandelt die externe Captive Portal-Weiterleitung, die 802.1X-RADIUS-Authentifizierung und die dynamische VLAN-Steuerung mithilfe von Private Pre-Shared Keys (PPSK) für sichere Multi-Tenant-Bereitstellungen.

Grandstream GWN Access Points Integration mit Purple WiFi

Dieses maßgebliche technische Handbuch beschreibt die Integration von Grandstream GWN Access Points mit dem Purple Guest WiFi und der Analytics-Plattform. Es umfasst die Konfiguration des Grandstream Captive Portal, die RADIUS AAA-Einstellungen, die Einrichtung des Walled Garden, die sichere 802.1X-Authentifizierung für Mitarbeiter mit dynamischer VLAN-Steuerung sowie die Multi-Tenant-PPSK-Segmentierung – eine praxisnahe Schritt-für-Schritt-Anleitung für MSPs und IT-Teams, die WiFi für Gäste und Mitarbeiter in großem Stil bereitstellen.