Software de contagem de pessoas e API: Guia de integração para desenvolvedores

O software de contagem de pessoas transforma eventos brutos de sensores em métricas de ocupação, fluxo de pedestres e tempo de permanência, e a integração entre os dois ocorre por meio de uma interface HTTP JSON documentada, em vez de um SDK proprietário.Um desenvolvedor pode obter contagens com uma solicitação POST assinada ou recebê-las em um webhook, e a carga útil é a mesma em ambos os casos.

O guia da API de contagem de pessoas abaixo aborda o modelo de dados, os dois padrões de integração, a autenticação e uma primeira requisição funcional. Os exemplos práticos seguem a interface exposta pelos contadores estéreo 3D da Pyroglaux, e o formato geral se aplica à maioria dos hardwares de contagem modernos.

O que o software de contagem de pessoas realmente recebe?

Em um sistema moderno de contagem de pessoas, o sensor realiza a contagem no próprio dispositivo e emite eventos estruturados, portanto o software de contagem de pessoas nunca processa vídeo.Os frames de profundidade são analisados ​​e descartados no próprio sensor.

Um único evento de cruzamento contém quatro campos: um índice único para o sujeito rastreado, um registro de data e hora UNIX que marca o momento em que o sujeito deixou a zona de detecção, um código de tipo de evento e uma duração de permanência em milissegundos.

Fonte: Especificação da interface HTTP de fluxo de passageiros Pyroglaux, V2.1.5.

Os quatro tipos de eventos são o ponto em que a maioria das pessoas que integram softwares de contagem erram. Tratar cada evento como uma entrada contabiliza duas vezes qualquer pessoa que passe pela porta sem entrar e ignora o código de reentrada que existe justamente para impedir que um cliente recorrente seja contabilizado como um novo visitante.

Como funciona a autenticação da API de contagem de pessoas?

As solicitações são assinadas em vez de conter um token no cabeçalho, usando um resumo MD5 dos parâmetros ordenados concatenados com um segredo de serviço compartilhado.O resumo resultante é convertido para maiúsculas e enviado em um cabeçalho Sign.

As etapas de assinatura são fixas. Ordene cada parâmetro da solicitação em ordem ASCII, anexe o segredo do serviço acordado com o dispositivo, obtenha o hash hexadecimal MD5 dessa string, converta o hash para maiúsculas e coloque o resultado no cabeçalho Sign junto com o tipo de conteúdo JSON padrão.

Uma solicitação de API de contagem de pessoas assinada evita o armazenamento de um token de portador de longa duração em um dispositivo localizado no chão de fábrica. Um segredo de serviço rotacionado invalida todas as solicitações capturadas anteriormente que não possuam uma lista de revogação de tokens.

Puxar ou empurrar: qual padrão de integração se encaixa melhor?

O modelo "pull" é adequado para frotas pequenas e desenvolvimento inicial; o modelo "push" é adequado para painéis de controle em tempo real e propriedades maiores.Ambos retornam o mesmo corpo JSON, portanto o analisador sintático escrito para um padrão funciona sem alterações com o outro.

Quando o software de contagem de pessoas deve consultar o dispositivo?

O software de contagem de pessoas deve realizar uma consulta inicial (polling), pois essa prática é trivial de depurar.Um único comando curl comprova a conectividade, a autenticação e o formato da carga útil antes mesmo de qualquer código de aplicação existir.

O custo da coleta de dados é um dispositivo acessível. O servidor precisa ser capaz de abrir uma conexão interna com cada sensor, o que significa uma VPN, um endereço fixo ou um mapeamento de portas por dispositivo. Acima de aproximadamente 50 dispositivos, esse inventário se torna o principal ônus de manutenção.

Em que situações o sensor deve pressionar em vez de empurrar?

A configuração push transforma o sensor em cliente, de modo que o dispositivo só precisa de acesso à rede de saída.Não são necessárias regras de firewall de entrada nem agenda de endereços por dispositivo.

O dispositivo recebe um URL de destino por meio de um endpoint de configuração, após o qual os eventos de cruzamento são enviados para esse URL à medida que ocorrem. A latência cai do intervalo de polling para quase tempo real, o que é importante para limites de ocupação e exibição de filas em tempo real.

Como fazer o primeiro pedido?

Três endpoints da API de contagem de pessoas abrangem quase todas as integrações: contagens em tempo real, totais históricos e a lista bruta de eventos.O dispositivo escuta em uma porta fixa e aceita solicitações POST RESTful com um corpo JSON.

Fonte: Especificação da interface HTTP de fluxo de passageiros Pyroglaux, V2.1.5. Consulte a documentação atual do dispositivo para obter os caminhos exatos, pois os nomes dos endpoints variam entre as gerações de firmware.

Ao realizar uma primeira requisição a um software de contagem de pessoas, recomenda-se solicitar um pequeno lote de eventos em vez de um dia inteiro. Enviar um índice inicial de zero com uma quantidade de 100 retorna, no máximo, 100 registros, e a resposta informa quantos registros estavam realmente disponíveis.

Cada resposta da API de contador de pessoas contém um objeto de resultado com um indicador de erro, um código numérico e uma mensagem legível para humanos. Verificar o indicador de erro antes de analisar a carga útil impede que um resultado vazio seja interpretado silenciosamente como zero visitantes.

Quais são os limites que vale a pena conhecer antes de construir?

O armazenamento no dispositivo é um buffer, não um banco de dados.Um dispositivo de contagem normalmente retém cerca de três dias de histórico, o que é suficiente para sobreviver a uma interrupção de rede durante um fim de semana, mas não o suficiente para servir como sistema de registro.

Três consequências decorrem para qualquer sistema de contagem de pessoas construído nesses dispositivos: 1. Persistir eventos em seu próprio armazenamento ao serem recuperados. 2. Rastrear o último índice ou carimbo de data/hora ingerido com sucesso para que uma reinicialização retome o processo em vez de reiniciá-lo completamente. 3. Conciliar os totais diários com o endpoint histórico, pois a consulta agregada e a lista de eventos são calculadas separadamente no dispositivo.

A deriva do relógio merece atenção em qualquer sistema de contagem de pessoas com múltiplas unidades. Os registros de data e hora são provenientes do relógio do dispositivo, portanto, um sensor dessincronizado produz eventos que são classificados incorretamente em relação aos dados do PDV (Ponto de Venda). Configure um servidor de tempo durante o comissionamento, em vez de após o primeiro relatório com informações incorretas.

Como os dados chegam a uma ferramenta de BI?

A integração de dados de fluxo de pedestres deve armazenar os eventos de forma bruta e agregá-los no momento da leitura.Inserir intervalos horários pré-agregados no sistema de armazenamento é tentador, mas torna impossível responder a perguntas posteriores sobre tempo de permanência ou reentrada.

Um esquema mínimo viável para a integração de dados de fluxo de pessoas consiste em uma linha por evento, contendo o ID do dispositivo, o ID da zona, o registro de data e hora, o tipo de evento e o tempo de permanência. O fluxo de pessoas por hora, a conversão em relação aos dados do caixa e a distribuição do tempo de permanência são todos derivados dessa única tabela por meio de SQL padrão.

Um software de contagem de pessoas que combina transações de caixa com base no ID do dispositivo e na hora gera a taxa de conversão diretamente. As equipes de varejo que aplicam essa métrica devem ler o [texto incompleto/texto incompleto].Glossário de métricas de varejopara as definições que o painel de controle precisará.

O software de contagem de pessoas lida com dados pessoais?

Um sistema de contagem baseado em profundidade que transmite apenas contagens não processa dados pessoais, pois nenhuma imagem e nenhum identificador saem do sensor.A carga útil descrita acima contém um índice com escopo para uma sessão, um carimbo de data/hora e uma duração.

Duas decisões de design mantêm o software de contagem de pessoas nessa posição. Manter o processamento de profundidade no dispositivo, em vez de transmitir os quadros para um servidor para análise. Evitar a associação do índice de sessão a qualquer registro de cliente ou funcionário, já que essa associação criaria dados pessoais onde não existem.

Algumas versões do firmware oferecem recursos de reidentificação que permitem que softwares de contagem de pessoas eliminem a duplicação do mesmo visitante ao longo do dia, e esses recursos alteram a análise. Considere qualquer capacidade de desduplicação como uma revisão de privacidade separada, e não como uma atualização automática.

Perguntas frequentes sobre software e APIs de contagem de pessoas

É necessário um SDK para usar uma API de contagem de pessoas?

Não, uma requisição HTTP POST assinada com um corpo JSON é suficiente para a API de contagem de pessoas.Qualquer linguagem com um cliente HTTP e uma função MD5 pode ser integrada. Os SDKs dos fornecedores encapsulam a mesma interface e são convenientes, mas não necessários, e evitar um SDK mantém a integração portátil entre gerações de dispositivos.

Com que frequência o software de contagem de pessoas deve consultar um dispositivo?

Cada intervalo de um a cinco minutos atende à maioria das necessidades de relatórios.Aumentar a frequência de consultas raramente ajuda, pois o fluxo de pedestres é registrado por travessia e agregado posteriormente. Os painéis de ocupação em tempo real são a exceção, e nesses casos deve-se usar notificações push em vez de consultas mais rápidas.

O que acontece com as contagens durante uma interrupção de rede?

O dispositivo armazena eventos localmente e disponibiliza o conteúdo em espera assim que a conectividade for restabelecida.Um período de retenção típico é de aproximadamente três dias. Um sistema de ingestão que rastreia o último índice processado recupera a lacuna automaticamente; um sistema de ingestão que sempre solicita os registros mais recentes perde permanentemente o período de indisponibilidade.

Vários sistemas podem acessar a mesma API de contador de pessoas?

Sim, a interface pull não mantém estado e suporta leitores simultâneos.Cada chamador fornece um índice inicial ou um intervalo de tempo, permitindo que um pipeline de BI e um painel de controle em tempo real consultem o mesmo dispositivo. Os destinos de push geralmente são limitados a um pequeno número, portanto, o fan-out é melhor gerenciado por um relay em sua própria infraestrutura.

Como é calculado o tempo de permanência?

O tempo de permanência (stayTime) é registrado por evento em milissegundos, medido desde a entrada até a saída da zona de detecção.Tempo de permanência em uma zona não é o mesmo que tempo de permanência na loja. Medir quanto tempo um visitante permanece na loja requer um evento de entrada e um evento de saída correspondente, ou um recurso de reidentificação que vincule os dois.

O que um teste de integração de software de contagem de pessoas deve verificar primeiro?

Atravesse a porta um número conhecido de vezes e compare a contagem.Dez passagens controladas em cada direção validam a atribuição de direção, o mapeamento do tipo de evento e o tratamento do registro de data e hora em um único exercício. Qualquer discrepância nesta etapa é um problema de configuração, não um problema de código.

Próximos passos

Inicie qualquer integração de dados de fluxo de pessoas com um único dispositivo, um script de coleta de dados e dez visitas controladas. Assim que os números coincidirem, decida se a implementação precisa ser feita por push e projete o armazenamento de eventos antes de expandir para além de um único local.

A Pyroglaux publica a especificação completa da interface HTTP com cada dispositivo e não restringe a integração a um processo de assinatura. Navegue pelo catálogo.alcance do sensor de contagem 3DouSolicite a documentação da API e uma unidade de exemplo para desenvolvedores..