Purple Portal API: O Que Pode Fazer Com Ela

Uma referência técnica para gestores de TI e arquitetos de rede sobre como tirar partido da Purple Portal API. Este guia detalha os endpoints disponíveis, a autenticação e casos de uso do mundo real para integrar dados de WiFi de convidados com sistemas empresariais, de forma a melhorar a business intelligence e a eficiência operacional. Abrange tanto os padrões de integração REST API como Webhook, com estudos de caso concretos dos setores da hotelaria, retalho e eventos.

📖 9 min de leitura📝 2,212 palavras🔧 2 exemplos práticos❓ 3 perguntas de prática📚 9 definições principais

Ouça este guia

Ver transcrição do podcast

Bem-vindo ao Purple Technical Briefing. Sou o Senior Content Strategist aqui na Purple e, nos próximos dez minutos, vou dar-lhe uma visão geral concisa e prática da nossa Portal API — o que é, o que pode fazer com ela e como tirá-lo o máximo partido para obter o maior impacto de negócio. Isto destina-se a gestores de TI, arquitetos e diretores de operações que precisam de saber como transformar o seu WiFi de convidados de uma simples utilidade num poderoso ativo de dados.

Comecemos pelo contexto. Tem WiFi de convidados em todos os seus locais. Todos os dias, centenas ou milhares de pessoas ligam-se. Fornecem o seu email, talvez o seu nome, e aceitam os seus termos. Trata-se de dados primários valiosos. O Purple Portal oferece-lhe excelentes painéis de controlo para visualizar estes dados, mas o verdadeiro poder surge quando liga esses dados ao resto do seu ecossistema de negócios. É aí que entra a Portal API. É a ponte que permite aos seus sistemas comunicar programaticamente com a nossa plataforma.

Agora, entremos nos detalhes técnicos. A Portal API é uma interface RESTful padrão. A autenticação é simples e segura, utilizando uma API Key direta. Não precisa de se preocupar com fluxos OAuth complexos para a comunicação servidor para servidor. Crucialmente, não existem limites de taxa de utilização (rate limits). Construímo-la para a escala empresarial, por isso, quer esteja a gerir um único hotel ou uma cadeia nacional de quinhentas lojas de retalho, a API consegue lidar com o seu volume.

Tem duas formas principais de extrair dados. Primeiro, o método de recolha (pull): endpoints REST padrão. Pense em endpoints como visitantes e locais. Pode escrever um script para chamar estes endpoints de forma agendada, extrair todos os dados de visitantes das últimas vinte e quatro horas e carregá-los no seu armazém de dados (data warehouse) para análise. Esta é a sua solução ideal para business intelligence, para criar aqueles painéis de visão geral em Power BI ou Tableau.

Mas a parte realmente entusiasmante é o método de envio (push): Webhooks. Isto é para o tempo real. Configura um endpoint de escuta do seu lado e, no momento em que um convidado se autentica no seu WiFi, enviamos-lhe um payload JSON com todos os seus detalhes — nome, email, em que local se encontra, o seu número de visitas e até o método de autenticação que utilizou, quer tenha sido um formulário de registo, início de sessão social ou outro. É quase instantâneo. Isto é o que permite uma interação imediata e personalizada. É a diferença entre enviar um email de marketing amanhã ou enviar uma notificação de boas-vindas com uma oferta única no preciso segundo em que um cliente fiel entra pela sua porta.

Permita-me falar sobre os campos de dados que obtém. O payload do Webhook está estruturado em quatro objetos principais. O objeto client fornece-lhe o endereço MAC e o user agent. Os objetos company e venue fornecem-lhe os identificadores e as coordenadas geográficas da localização específica. O objeto session fornece-lhe o timestamp de autenticação. E o objeto user é onde está o verdadeiro valor: nome, apelido, e-mail, género, data de nascimento, número de telemóvel, código postal e uma contagem de visitas por venue mostrando as datas da primeira e da última visita. Também pode capturar campos personalizados a partir do seu formulário de registo no Captive Portal; por isso, se perguntar aos convidados pelo número do programa de fidelização ou pelo número do quarto num hotel, isso também é enviado.

Agora, na versão um ponto sete da API, há uma melhoria importante que vale a pena notar. O campo de cancelamento de subscrição distingue agora claramente os utilizadores que optaram ativamente por não receber marketing após terem estado subscritos, daqueles que simplesmente nunca optaram por aderir. Isto é fundamental para a conformidade com o GDPR e para uma segmentação precisa. Não vai querer tratar um subscritor inativo da mesma forma que alguém que nunca esteve no seu funil de marketing.

Vamos falar sobre os padrões de integração em maior detalhe. Para o padrão de pull da REST API, o seu fluxo de trabalho típico é um script agendado, talvez em Python ou Node.js, que corre todas as noites. Este autentica-se com a sua chave de API, consulta o endpoint de visitantes para cada venue, transforma os dados no formato pretendido e carrega-os numa base de dados central. Este é um processo ETL clássico. Para um operador multi-site, iria iterar pelos IDs das suas venues e agregar os dados de forma centralizada.

Para o padrão de push do Webhook, a arquitetura é ligeiramente diferente. Precisa de um endpoint acessível publicamente e protegido por SSL. Uma função serverless é ideal aqui — AWS Lambda, Azure Functions ou Google Cloud Functions. É económica, dimensiona-se automaticamente e lida com a concorrência que veria num local movimentado. Quando a função recebe o pedido POST da Purple, deve analisar o JSON, executar a sua lógica de negócio — talvez uma pesquisa no CRM ou uma verificação de fidelização — e retornar uma resposta duzentos OK o mais rápido possível.

Isto leva-me ao requisito de implementação mais importante: o seu listener deve responder no prazo de dez segundos. Se não o fizer, a Purple colocará o pedido novamente na fila e tentará de novo após três horas. Falhas persistentes farão com que o Webhook seja desativado automaticamente por motivos de segurança. Portanto, mantenha o seu listener leve. Faça o processamento mínimo necessário para retornar uma resposta rápida e, se precisar de fazer um processamento pesado, envie o evento para uma fila interna e processe-o de forma assíncrona.

Agora, vejamos alguns cenários do mundo real para tornar isto concreto.

Considere um hotel com duzentos quartos. Querem registar automaticamente os novos convidados WiFi numa jornada de email de boas-vindas na sua plataforma de marketing. A solução é simples: configure um Webhook, crie um listener serverless simples e, quando os dados de um novo utilizador chegarem, verifique se já existem na plataforma de marketing. Caso contrário, adicione-os e acione a jornada de boas-vindas. O hotel também pode utilizar o campo de contagem de visitas para distinguir os visitantes frequentes de quem os visita pela primeira vez e adaptar a comunicação em conformidade. Um convidado habitual poderá receber uma oferta de recompensa de fidelização em vez de uma mensagem de boas-vindas genérica.

Agora considere uma cadeia de retalho nacional com cinquenta lojas. Querem um painel central que mostre as tendências de tráfego pedonal em todas as localizações. Aqui, o padrão de pull da API REST é a escolha certa. Um script noturno consulta o endpoint de visitantes para cada uma das cinquenta localizações, agrega os dados e carrega-os num data warehouse. A equipa de analítica cria então os seus painéis de controlo com base nisto. Conseguem ver quais as lojas que têm as taxas mais elevadas de novos visitantes, quais têm os melhores rácios de visitantes recorrentes e como os tempos de permanência se correlacionam com o desempenho de vendas.

Permita-me agora abordar alguns erros comuns e como os evitar.

O primeiro erro é o tratamento de eventos duplicados. Uma única visita de um convidado pode acionar múltiplos eventos de autenticação — por exemplo, se deixarem o ecrã do telemóvel bloquear e este se voltar a ligar, ou se fizerem roaming entre pontos de acesso. O seu listener deve ser idempotente. Antes de realizar uma ação como o envio de um email, verifique se já processou um evento para esse utilizador no dia de hoje.

O segundo erro é não validar o URL do seu listener antes de o colocar em produção. A Purple exige que valide o endpoint no portal antes de este poder receber dados. Certifique-se de que o seu listener está ativo e a retornar o cabeçalho wifiWebhookListener correto antes de o associar a um LogicFlow.

O terceiro erro é ignorar o estado de subscrição. Verifique sempre o campo unsubscribed antes de adicionar um utilizador a uma lista de marketing. O envio de comunicações de marketing para alguém que optou por não as receber é uma violação do GDPR com consequências significativas.

Passamos agora para uma sessão rápida de perguntas e respostas.

Posso sincronizar isto com o meu CRM personalizado? Sim. Se o seu CRM tiver uma API, pode utilizar um listener de Webhook como middleware para formatar os dados da Purple e enviá-los para o seu sistema. Os IDs retornados no payload do Webhook correspondem aos da API REST, pelo que também pode fazer chamadas de acompanhamento para obter detalhes adicionais, se necessário.

Como lido com um utilizador que visita várias localizações na minha propriedade? A API fornece contagens de visitas por ID de localização, para que possa monitorizar facilmente o percurso de um cliente em toda a sua propriedade e criar um perfil cross-site abrangente.

Existe um limite para o número de URLs de Webhook que posso configurar? Não. Pode validar e utilizar tantos URLs de listener quantos necessitar, o que é útil se diferentes equipas ou sistemas precisarem de receber os mesmos dados de eventos.

O que acontece se o meu recetor ficar inativo para manutenção? A Purple tentará novamente as entregas falhadas, pelo que poderá receber uma acumulação de eventos quando o seu recetor voltar a estar online. O seu recetor precisa de lidar com isto de forma flexível, processando eventos que possam chegar fora da ordem cronológica.

Para resumir tudo o que abordámos hoje, a API do Purple Portal é a sua chave para desbloquear o imenso valor dos seus dados de WiFi de convidados. Utilize a REST API para extrair dados para relatórios e análises. Utilize Webhooks para enviar dados em tempo real para um envolvimento imediato e personalizado do cliente. Lembre-se do princípio fundamental: push para tempo real, pull para relatórios.

O seu próximo passo é analisar a documentação da API no nosso portal de suporte. Se tiver uma licença Engage, gere uma chave de API e comece a explorar com o Postman. Crie um recetor de Webhook simples. Veja os dados a entrar. Esse é o momento em que o potencial desta ferramenta se torna cristalino.

Obrigado por ouvir o Purple Technical Briefing. Se desejar falar com um dos nossos arquitetos de soluções sobre os seus requisitos específicos de integração, visite purple dot ai e reserve uma demonstração. Até à próxima.

Principais Conclusões

✓A API do Portal Purple fornece acesso programático aos dados de WiFi de convidados utilizando autenticação simples por Chave de API, sem limites de taxa.
✓Requer uma licença Engage e opera atualmente na versão v1.7, que melhorou a conformidade com o GDPR através de um tratamento mais claro do estado de subscrição cancelada.
✓Utilize a REST API (pull) para exportações de dados em lote, processos ETL e painéis de análise.
✓Utilize Webhooks (push) para ações em tempo real baseadas em eventos, tais como sincronizações de CRM, mensagens personalizadas e acionadores de fidelização.
✓Os listeners de Webhook devem ser protegidos por SSL, responder no prazo de 10 segundos e ser concebidos para lidar com eventos duplicados de forma idempotente.
✓Os principais casos de utilização abrangem o setor da hospitalidade (enriquecimento de CRM em tempo real), retalho (análises multicanais) e eventos (dados de afluência verificados para patrocinadores).
✓A API permite que as organizações transformem a sua infraestrutura de WiFi de um centro de custos num ativo de dados estratégico com um ROI claro e mensurável.

Resumo Executivo

Para os líderes de TI em recintos multi-site — hotéis, cadeias de retalho, estádios e centros de conferências — a rede WiFi de convidados é mais do que uma simples comodidade. É uma fonte rica e continuamente atualizada de dados primários (first-party) que pode impulsionar um impacto comercial mensurável no marketing, nas operações e na experiência do cliente. A Purple Portal API fornece a interface programática necessária para desbloquear este valor à escala. Permite que as equipas técnicas vão além dos painéis de análise integrados e criem integrações robustas e automatizadas que alimentam os sistemas de negócio principais diretamente com dados de visitantes em conformidade com o GDPR, desde plataformas de CRM e ferramentas de automação de marketing até programas de fidelização e armazéns de business intelligence.

Este guia é uma referência prática e acionável para arquitetos de soluções, gestores de TI e programadores seniores. Detalha o modelo de autenticação, os endpoints disponíveis, os padrões de integração e os cenários de implementação no mundo real que demonstram como a Purple WiFi API pode transformar uma implementação de WiFi de um centro de custos num ativo estratégico de dados. Quer esteja a avaliar a API pela primeira vez ou a planear uma integração pronta para produção, este documento fornece a fundamentação técnica e os quadros de decisão necessários para avançar com confiança.

Análise Técnica Detalhada

Autenticação e Versionamento da API

A Purple Portal API utiliza autenticação por API Key, um modelo simples e seguro, ideal para integrações server-to-server. Ao contrário dos fluxos de trabalho do OAuth 2.0, que requerem a troca e renovação de tokens, a autenticação por API Key envolve a inclusão de um segredo estático nos cabeçalhos dos pedidos. Esta simplicidade reduz o esforço de integração sem comprometer a segurança, desde que a chave seja guardada de forma segura e rodada periodicamente como parte da sua política padrão de gestão de credenciais.

A versão de produção atual é a v1.7, que introduziu várias melhorias importantes em relação à v1.6.2. Mais significativamente, a propriedade unsubscribed no objeto de dados do utilizador distingue agora claramente entre um utilizador que cancelou ativamente a subscrição de marketing após ter estado subscrito, e um utilizador que nunca se subscreveu. Esta distinção é crítica para a conformidade com o GDPR e para uma segmentação precisa de audiências. Adicionalmente, os endpoints Visitors e Venues devolvem agora uma resposta HTTP 200 OK quando não são encontrados dados, em vez de um 404 Not Found, o que anteriormente causava confusão na lógica de monitorização e tratamento de erros.

Endpoints Disponíveis

A Portal Company API expõe três categorias principais de endpoints com os quais as equipas de TI irão interagir regularmente.

Endpoint	Método	Finalidade
`/visitors`	GET	Recuperar perfis de visitantes convidados, incluindo dados de contacto, dados demográficos e histórico de visitas
`/venues`	GET	Recuperar dados ao nível do recinto e metadados de configuração
`/unsubscribes`	GET	Recuperar uma lista de utilizadores que optaram por não receber comunicações de marketing

Todos os endpoints devolvem dados em formato JSON. O endpoint visitors é o mais commumente utilizado, pois expõe toda a riqueza dos dados do perfil de visitante recolhidos durante o percurso de autenticação no Captive Portal. Isto inclui o primeiro nome, apelido, endereço de email, género, data de nascimento, número de telemóvel, código postal, fornecedor de autenticação (por exemplo, formulário de registo, login social), contagem de visitas por local e quaisquer campos personalizados configurados na splash page.

Limites de Débito (Rate Limits)

Uma vantagem arquitetural fundamental da Purple Portal API é que não existem limites de débito. A plataforma foi concebida para suportar qualquer volume de pedidos ou transações, tornando-a adequada para implementações em grande escala, onde os scripts podem necessitar de processar milhares de registos de locais ou milhões de perfis de visitantes. Isto remove uma restrição comum que complica o design de integração com outras plataformas e elimina a necessidade de limitação de pedidos (request throttling) ou lógica de back-off no seu código de cliente.

Padrões de Integração: Pull vs. Push

A Purple WiFi API suporta dois padrões de integração fundamentalmente diferentes, cada um adequado a diferentes casos de utilização. Compreender qual o padrão a aplicar num determinado cenário é a decisão arquitetural mais importante que irá tomar.

O padrão pull da REST API envolve o seu sistema fazer pedidos a pedido (on-demand) ou agendados aos endpoints da API para recuperar dados. Esta é a abordagem correta para processamento em lote, relatórios e business intelligence. Um script ETL noturno que extrai todos os dados de visitantes do dia anterior e os carrega num armazém de dados (data warehouse) é um exemplo canónico. O padrão pull dá-lhe controlo total sobre quando e quantos dados recupera.

O padrão push de Webhook envolve a Purple enviar dados para o seu sistema no momento exato em que um evento específico ocorre — especificamente, quando um visitante se autentica na rede WiFi. O seu sistema deve expor um endpoint HTTP acessível publicamente e protegido por SSL (um 'listener') que possa receber e processar estes payloads POST em JSON. O padrão de Webhook é a escolha correta para qualquer caso de utilização que exija dados em tempo quase real, como o envio de uma mensagem de boas-vindas personalizada, a atualização do estado de 'última vez visto' de um cliente num CRM ou a notificação de um gestor hoteleiro de que um cliente VIP chegou.

Estrutura do Payload do Webhook

O payload JSON entregue por um Webhook da Purple está estruturado em quatro objetos principais, cada um fornecendo uma dimensão diferente de contexto para o evento de autenticação.

Objeto	Campos Principais	Descrição
`client`	`mac`, `userAgent`	Identificadores ao nível do dispositivo
`company`	`id`, `name`, `uniqId`	Os detalhes da conta da sua empresa
`venue`	`id`, `name`, `latitude`, `longitude`	O local específico onde ocorreu a autenticação
`session`	`authenticationTime`	Timestamp ISO 8601 do evento de autenticação
`user`	`email`, `firstName`, `lastName`, `gender`, `provider`, `visitCountForVenues`, `customFields`	Dados completos do perfil de visitante

O objeto user.visitCountForVenues é particularmente valioso para operadores de múltiplos locais. Fornece uma contagem de visitas por local juntamente com os timestamps firstVisit e lastVisit, permitindo-lhe identificar visitantes de primeira viagem versus clientes recorrentes leais no momento da autenticação — sem quaisquer chamadas de API adicionais.

Guia de Implementação

Pré-requisitos e Configuração

O acesso à Portal API requer uma licença Engage. Uma vez licenciado, gere a sua Chave de API a partir das definições do portal Purple. Para o desenvolvimento e testes iniciais, o Postman é a ferramenta recomendada; a Purple fornece um guia de configuração dedicado para configurar as variáveis de ambiente e cabeçalhos de pedido corretos. Um ficheiro de demonstração PHP também está disponível para equipas que prefiram um ponto de partida de scripting no lado do servidor.

Configurar uma Integração de Webhook

A implementação de uma integração de Webhook envolve cinco passos. Primeiro, crie e implemente o seu endpoint de escuta num URL acessível publicamente e protegido por SSL. Uma função serverless (AWS Lambda, Azure Functions ou Google Cloud Functions) é uma escolha arquitetonicamente sólida: escala automaticamente, incorre em custos mínimos a volumes baixos e lida com pedidos concorrentes sem configuração. Segundo, valide o URL de escuta no portal Purple navegando para Gestão > Locais > Webhooks. A Purple enviará um pedido de teste para confirmar que o endpoint está acessível e devolve o cabeçalho wifiWebhookListener: 1 obrigatório. Terceiro, crie ou edite um LogicFlow no portal e adicione um Nó de Ação Webhook, selecionando o seu URL validado. Quarto, certifique-se de que o LogicFlow está definido para o estado 'Online'. Quinto, associe o LogicFlow ao Access Journey relevante. A partir deste ponto, cada autenticação de visitante nessa jornada irá acionar o seu Webhook.

Gestão de Tentativas e Idempotência

O seu recetor de escuta deve ser concebido para lidar com a realidade dos sistemas distribuídos. A Purple tentará novamente uma entrega de Webhook falhada após três horas se o seu recetor não responder (o tempo limite excede os 10 segundos) ou devolver um estado de erro. Isto significa que o seu recetor pode receber o mesmo evento várias vezes. Além disso, uma única visita de um visitante pode acionar múltiplos eventos de autenticação — por exemplo, quando um dispositivo se volta a ligar depois de o ecrã bloquear, ou quando um utilizador se desloca entre pontos de acesso. A sua lógica de processamento deve, por isso, ser idempotente: aplicar o mesmo evento duas vezes deve produzir o mesmo resultado que aplicá-lo uma única vez. Um padrão de implementação comum é verificar se uma ação (como o envio de um e-mail de boas-vindas) já foi realizada para um determinado ID de utilizador dentro de uma janela de tempo definida antes de a executar.

Melhores Práticas

Vários princípios devem orientar qualquer implementação em produção da Purple Portal API. Implemente sempre com base na versão mais recente da API (v1.7) e atualize os caminhos do seu URL e a lógica de análise de respostas quando novas versões forem lançadas. Trate a sua chave de API (API Key) como uma credencial confidencial: armazene-a num gestor de segredos (como o AWS Secrets Manager ou o Azure Key Vault) em vez de no código-fonte ou em variáveis de ambiente em sistemas partilhados. Para os recetores de Webhooks, implemente o registo estruturado de cada payload recebido e respetiva resposta para facilitar a depuração e as auditorias. Respeite os campos unsubscribed e unsubscribedDate no objeto de utilizador; processar ações de marketing para utilizadores que optaram por não as receber constitui uma violação do GDPR. Por fim, teste a sua integração contra toda a gama de casos limite: utilizadores sem endereço de e-mail, utilizadores com campos personalizados nulos e eventos de autenticação que chegam fora da ordem cronológica.

Resolução de Problemas e Mitigação de Riscos

O modo de falha mais comum numa integração de Webhooks é um recetor lento ou indisponível. Se o endpoint falhar consistentemente em responder no prazo de 10 segundos, a Purple desativará automaticamente o Webhook após um período prolongado de inatividade, exigindo uma nova verificação manual no portal. Para mitigar este risco, implemente um endpoint de verificação de estado (health check) no mesmo servidor do seu recetor e inclua-o na monitorização da sua infraestrutura. Certifique-se de que o seu recetor realiza apenas um processamento síncrono mínimo antes de retornar uma resposta 200 OK; transfira qualquer processamento pesado ou chamadas de API secundárias para uma fila assíncrona.

Para integrações de REST API, o principal risco é a obsolescência dos dados nos sistemas secundários se o trabalho de extração programado falhar silenciosamente. Implemente alertas nos seus scripts de ETL para notificar a equipa de operações se uma execução falhar ou não produzir resultados inesperadamente. Ao migrar da API v1.6.2 para a v1.7, audite todo o código que faça referência ao campo unsubscribed e ao endpoint Unsubscribes, uma vez que o nome da propriedade foi corrigido de unsubcribers para unsubscribers na v1.7.

ROI e Impacto no Negócio

O caso de negócio para a integração com a Purple Portal API está bem estabelecido em múltiplos setores. Na hotelaria, os hotéis que utilizam integrações de CRM acionadas por Webhooks relatam melhorias significativas nas taxas de abertura de e-mails para comunicações personalizadas em comparação com campanhas de difusão genéricas, porque a mensagem é entregue no momento de máxima relevância — quando o hóspede está fisicamente no local. No retalho, a ligação dos dados de WiFi de convidados a um programa de fidelização permite aos operadores identificar e recompensar os visitantes de alta frequência, aumentando o gasto médio e as taxas de visitas repetidas. Para grandes espaços públicos e centros de conferências, as análises baseadas em API fornecem os dados detalhados de afluência necessários para justificar as avaliações de patrocínio e otimizar a colocação de concessões.

A ausência de limites de taxa na Purple WiFi API significa que o custo de integração escala com a sua infraestrutura, não com o volume de dados que processa. Para uma cadeia de retalho nacional que processa centenas de milhares de autenticações diárias, esta é uma vantagem material sobre as plataformas que cobram por chamada de API ou impõem limites de processamento. O custo total de propriedade para uma integração de API da Purple bem estruturada é, portanto, principalmente o custo de desenvolvimento único e o custo de infraestrutura contínuo do recetor, ambos tipicamente recuperados logo no primeiro trimestre apenas através da melhoria das taxas de conversão de marketing.

Casos de Estudo

Caso de Estudo 1: Hotelaria — Whitbread Group

A Whitbread, a maior empresa de hotéis e restaurantes do Reino Unido, opera milhares de pontos de acesso WiFi de convidados em todo o seu portfólio de Premier Inn e restaurantes. Ao integrar a Purple Portal API com a sua plataforma de CRM, o grupo conseguiu criar um perfil unificado de hóspede que combinava dados de reservas online com o comportamento de visitas físicas registado no Captive Portal de WiFi. A integração de Webhooks é acionada a cada autenticação de convidado, enriquecendo o registo de CRM com o carimbo de data/hora da última visita, localização do espaço e informações do dispositivo. Isto permite à equipa de marketing segmentar as audiências por recência, frequência e localização, e acionar campanhas de reativação altamente personalizadas. O principal resultado técnico foi a redução do tempo entre a chegada de um hóspede e a sua entrada numa jornada de marketing ativa de 24 horas (sob o modelo anterior de consulta em lote) para menos de 60 segundos.

Caso de Estudo 2: Retalho — Retalhista de Moda Multilocal

Um retalho nacional de moda com mais de 80 lojas implementou a Purple Portal API para colmatar uma lacuna crítica na sua estratégia de dados de clientes: possuíam dados sólidos de e-commerce, mas praticamente nenhum conhecimento sobre o comportamento dos visitantes em loja física. Ao ligar a Purple guest WiFi API ao seu armazém de dados existente através de um processo diário de ETL, construíram pela primeira vez uma visão de cliente multicanal. O endpoint /visitors foi consultado para cada loja todas as noites, e os dados foram combinados com os registos de transações de e-commerce utilizando o endereço de e-mail como chave comum. No prazo de três meses, a equipa de análise identificou que os clientes que se ligavam ao WiFi da loja tinham um valor médio de encomenda 34% superior na sua compra online seguinte, fornecendo um caso de negócio convincente para um maior investimento na experiência digital em loja. A integração não exigiu alterações na infraestrutura de e-commerce existente, demonstrando a natureza de baixa fricção do padrão de extração da REST API.

Case Study 3: Events — Conference Centre

Um grande centro de conferências no Reino Unido utilizou a Purple Portal API para fornecer aos patrocinadores, pela primeira vez, dados verificados de afluência. Anteriormente, os relatórios dos patrocinadores dependiam de contagens manuais de pessoas e leituras de crachás, que exigiam muita mão de obra e eram imprecisos. Ao expor contagens de visitantes agregadas e anonimizadas por zona (mapeadas para IDs de locais na plataforma Purple) através da API, a equipa de eventos pôde fornecer aos patrocinadores dashboards em tempo real que mostravam o tempo de permanência e o volume de visitantes nas áreas patrocinadas. Os dados eram extraídos através da REST API a cada 15 minutos durante os eventos e apresentados num portal de patrocinadores personalizado. Esta funcionalidade contribuiu diretamente para um aumento de 22% nas taxas de renovação de patrocínios no primeiro ano, uma vez que os patrocinadores podiam agora quantificar o alcance das suas ativações com dados de primeira parte verificados.

Definições Principais

Webhook

Um mecanismo automatizado onde um servidor envia uma notificação de dados em tempo real (um push) para outra aplicação quando ocorre um evento específico, através de um pedido HTTP POST.

No contexto da Purple, um Webhook envia um payload JSON com dados do visitante para o seu sistema no momento em que um convidado se autentica na rede WiFi. Isto é fundamental para atualizações de marketing e CRM em tempo real.

REST API

Um estilo arquitetural padronizado para criar serviços web que permite a um sistema solicitar (ou extrair) dados de outro utilizando métodos HTTP padrão, tais como GET e POST.

As equipas de TI utilizam a REST API da Purple para escrever scripts que extraem dados em massa de visitantes e locais para análise em ferramentas de business intelligence como o Power BI ou o Tableau.

API Key Authentication

Um modelo de segurança onde o acesso a uma API é concedido através do fornecimento de um token secreto único (a chave) com cada pedido, normalmente no cabeçalho de Autorização HTTP.

Isto é mais simples do que o OAuth e ideal para integrações servidor para servidor. Os seus scripts devem incluir a API Key válida nos cabeçalhos dos pedidos para aceder aos dados da Purple.

Idempotency

Uma propriedade de uma operação que significa que esta pode ser aplicada várias vezes sem alterar o resultado além da aplicação inicial.

O seu recetor de Webhook deve ser idempotente. Se receber o mesmo evento de autenticação duas vezes (o que pode acontecer devido a tentativas de reenvio ou a ligações repetidas do dispositivo), não deverá, por exemplo, enviar dois e-mails de boas-vindas.

JSON (JavaScript Object Notation)

Um formato leve e baseado em texto para intercâmbio de dados que é fácil de ler por humanos e de analisar e gerar por máquinas.

A API da Purple e os Webhooks fornecem todos os dados em formato JSON. A sua aplicação terá de analisar este JSON para extrair campos como e-mail, nome e número de visitas.

LogicFlow

A ferramenta visual e de arrastar-e-largar da Purple para criar fluxos de trabalho automatizados de marketing e interação que podem desencadear ações com base no comportamento e dados demográficos dos visitantes.

Utiliza o LogicFlow para definir o percurso do convidado. É onde associa o seu Webhook, indicando ao sistema para o acionar quando um utilizador atinge o estado "Online" do seu percurso de acesso.

Captive Portal

A página web que um utilizador vê e com a qual deve interagir antes de lhe ser concedido acesso a uma rede WiFi pública, exigindo normalmente autenticação ou recolha de dados.

A plataforma Purple alimenta o Captive Portal, e os dados introduzidos pelo utilizador nesta página (ex.: nome, e-mail, campos personalizados) são os que ficam disponíveis através da Portal API.

GDPR (General Data Protection Regulation)

Uma lei abrangente de privacidade de dados na União Europeia que regula a recolha, processamento e armazenamento de dados pessoais de residentes na UE.

A API da Purple fornece as ferramentas para criar integrações em conformidade com o GDPR, tais como respeitar o estado de subscrição cancelada de um utilizador e permitir a exportação de dados para pedidos de acesso do titular dos dados. A atualização da API v1.7 melhorou especificamente a clareza do campo de subscrição cancelada para apoiar a conformidade.

ETL (Extract, Transform, Load)

Um processo de integração de dados que envolve a extração de dados de um sistema de origem, a sua transformação para o formato exigido e o seu carregamento num sistema de destino, como um armazém de dados.

O padrão de extração da REST API é normalmente implementado como um processo ETL, onde os dados são extraídos do endpoint /visitors da Purple, transformados para corresponder ao esquema de destino e carregados num CRM ou armazém de dados.

Exemplos Práticos

Um hotel de 200 quartos pretende adicionar automaticamente novos utilizadores de WiFi de convidados à sua jornada do Salesforce Marketing Cloud e enviar um email de boas-vindas.

No Purple Portal, valide um novo URL de Webhook que aponte para um endpoint seguro (por exemplo, uma função serverless no AWS Lambda). 2. Crie um LogicFlow 'Online' que inclua o nó Webhook, configurado para usar o URL validado. 3. Atribua este LogicFlow à jornada de acesso de WiFi de convidados do hotel. 4. A função serverless recebe o payload JSON na autenticação do convidado, extrai o email e o nome do utilizador e faz uma chamada de API para o Salesforce Marketing Cloud para adicionar o utilizador à jornada 'Novo Convidado'. 5. A função devolve uma resposta 200 OK à Purple dentro da janela de limite de tempo de 10 segundos.

Comentário do Examinador: Esta solução utiliza corretamente o padrão de Webhook em tempo real, o que é ideal para ações imediatas como o envio de um email de boas-vindas. Utilizar uma função serverless é uma forma económica e escalável de alojar o endpoint recetor. Uma alternativa seria consultar o endpoint da API /visitors, mas isso introduziria um atraso de até 24 horas e seria significativamente menos eficiente para um requisito em tempo real.

Uma cadeia de retalho com 50 lojas pretende criar um dashboard central no Power BI para analisar as tendências de visitantes em todas as localizações.

Crie um script (por exemplo, em Python) que seja executado numa base diária programada. 2. O script autentica-se na Purple Portal API utilizando a chave de API da empresa. 3. Itera por cada um dos 50 IDs de locais, fazendo uma chamada ao endpoint /visitors para cada um, de modo a recolher todos os dados de visitantes do dia anterior. 4. O script transforma e carrega estes dados num armazém de dados central (por exemplo, Azure SQL ou BigQuery). 5. O Power BI é ligado ao armazém de dados para criar o dashboard analítico cruzado entre locais.

Comentário do Examinador: Este é um processo clássico de ETL (Extração, Transformação e Carregamento) e constitui a utilização correta do padrão de consulta (polling) da REST API. É adequado para agregação de dados em grande escala e que não requeira tempo real para efeitos de business intelligence. A utilização de um armazém de dados central é uma boa prática para o desempenho e escalabilidade ao lidar com dados de múltiplas origens. A ausência de limites de taxa (rate limits) na Purple API significa que o script pode processar todos os 50 locais sem preocupações de limitação de tráfego.

Perguntas de Prática

Q1. Um estádio pretende identificar os detentores de bilhetes de época VIP quando estes se ligam ao WiFi e enviar uma notificação para o painel de controlo do gestor de hospitalidade mais próximo. Que padrão de integração devem utilizar e porquê?

Dica: Considere a velocidade necessária da notificação e se a ação é acionada por um evento.

Ver resposta modelo

Devem utilizar o padrão Webhook (push). Trata-se de um requisito em tempo real: quando o VIP se liga, um Webhook é acionado imediatamente para um serviço que procura o e-mail ou o endereço MAC do utilizador na base de dados de detentores de bilhetes de época. Se for encontrada uma correspondência, envia uma notificação para o painel de hospitalidade relevante. Um padrão REST API (pull) seria demasiado lento, pois depende de consultas periódicas e poderia introduzir atrasos de minutos ou horas.

Q2. Tem a tarefa de criar um relatório diário dos 10 locais mais visitados na sua cadeia nacional de cafés. Como recuperaria os dados necessários da Purple?

Dica: Trata-se de um requisito de relatório em tempo real ou em lote? Que endpoint consultaria?

Ver resposta modelo

Trata-se de uma tarefa de relatório em lote, pelo que o padrão REST API (pull) é adequado. Um script agendado correria diariamente, consultaria o endpoint /visitors para cada local, agregaria a contagem de visitas do dia anterior e, em seguida, calcularia os 10 primeiros. Não há necessidade da notificação quase instantânea fornecida pelos Webhooks. A ausência de limites de taxa significa que todos os locais podem ser consultados numa única execução de script sem preocupações de limitação.

Q3. O seu endpoint de listener de Webhook está a falhar. Verifica os registos e vê um erro de timeout. Qual é a causa mais provável de acordo com a documentação da Purple e quais são as duas consequências imediatas?

Dica: Pense nos requisitos de desempenho de um listener e no que a Purple faz quando não consegue entregar um payload.

Ver resposta modelo

A causa mais provável é o listener estar a demorar mais de 10 segundos a processar o payload JSON de entrada e a retornar uma resposta 200 OK. As duas consequências imediatas são: (1) a Purple deixará de tentar enviar o pedido atual e irá colocá-lo novamente na fila para uma tentativa de reenvio em 3 horas, o que significa que a entrega dos dados é atrasada; e (2) se isto continuar por um período prolongado, a Purple desativará automaticamente o Webhook por completo, exigindo uma nova verificação manual no portal antes de poder ser reativado.

Continue a ler esta série

Integração do CommScope Ruckus com o Purple WiFi: Guia de Instalação e Configuração

Este guia de referência técnica fornece um manual de configuração autoritativo para integrar arquiteturas CommScope Ruckus com o Purple WiFi. Detalha implementações passo a passo para Captive Portals de Guest WiFi, WiFi seguro para funcionários via 802.1X e isolamento de rede multi-tenant utilizando Ruckus Dynamic PSK.

Integração de Access Points Allied Telesis com Purple WiFi

Este guia fornece um manual de configuração abrangente para integrar access points Allied Telesis da Série TQ com o Purple WiFi. Abrange o redirecionamento de Captive Portal externo, autenticação RADIUS 802.1X e direcionamento dinâmico de VLAN usando Private Pre-Shared Keys (PPSK) para implementações multi-tenant seguras.

Integração de Pontos de Acesso Grandstream GWN com o Purple WiFi

Este guia de referência técnica detalha como integrar os pontos de acesso Grandstream GWN com a plataforma de Guest WiFi e analítica da Purple. Abrange a configuração do Captive Portal da Grandstream, definições de RADIUS AAA, configuração de walled garden, autenticação segura de funcionários 802.1X com direcionamento dinâmico de VLAN e segmentação PPSK multi-tenant — fornecendo orientações práticas e passo a passo para MSPs e equipas de TI que implementam WiFi para convidados e funcionários em grande escala.