Pular para o conteúdo principal

FAQ - Integração Dataoris via Webhook

Perguntas frequentes sobre a integração do Dataoris​

Geral​

O que é necessário para começar a usar o Dataoris?​

Para usar o Dataoris, você precisa:

  1. Integrar o SDK da Group Link no seu aplicativo móvel (Android e/ou iOS)
  2. Fornecer um endpoint webhook (HTTPS) para receber os eventos
  3. Definir as células H3 (Cell IDs) que deseja monitorar
  4. Aguardar a configuração pela equipe da Group Link

Posso usar o Dataoris sem integrar o SDK?​

Não. A integração do SDK é obrigatória. É através do SDK que os eventos de geolocalização são capturados e enviados. Sem o SDK integrado no aplicativo, não haverá eventos para serem enviados ao webhook.

Quanto tempo leva para configurar a integração?​

Após enviar as informações necessárias (endpoint webhook, cell IDs) para nossa equipe, a configuração é concluída em até 2 dias úteis.

Sobre o SDK​

Qual SDK devo integrar?​

Você deve integrar o SDK de acordo com a plataforma do seu aplicativo:

  • Android nativo: Android SDK
  • iOS nativo: iOS SDK
  • React Native: React Native SDK
  • Flutter: Flutter SDK

Você pode integrar em múltiplas plataformas se seu aplicativo estiver disponível em mais de uma.

Onde encontro a documentação do SDK?​

A documentação completa do SDK está disponível em SDK Documentation.

O SDK funciona em segundo plano?​

Sim, o SDK da Group Link funciona em segundo plano para detectar eventos de entrada das áreas monitoradas, respeitando as limitações de cada plataforma (iOS/Android).

Sobre Células H3​

O que são células H3?​

Células H3 são hexágonos que representam áreas geográficas específicas usando o sistema de indexação espacial H3 do Uber. Cada célula tem um identificador único.

Como escolho as células H3 que quero monitorar?​

Você pode:

  1. Usar ferramentas online como H3 Geo para explorar e identificar células
  2. Fornecer coordenadas geográficas (latitude/longitude) e nossa equipe converterá em Cell IDs
  3. Solicitar ajuda da nossa equipe para identificar as células corretas

Posso monitorar múltiplas células?​

Sim, você pode monitorar quantas células H3 desejar. Basta fornecer a lista de Cell IDs na configuração.

Posso adicionar ou remover células depois?​

Sim, você pode solicitar alterações nas células monitoradas entrando em contato com nossa equipe através do email suporte@grouplinkone.com.

Sobre o Webhook​

Meu webhook precisa ter autenticação?​

Atualmente não é obrigatório, mas recomendamos preparar seu endpoint para receber autenticação via API Key no header, pois essa funcionalidade será implementada em breve.

Que tipo de requisição é enviada ao webhook?​

  • Método HTTP: POST
  • Content-Type: application/json
  • Body: JSON com os dados do evento

Meu endpoint precisa retornar algo específico?​

Seu endpoint deve retornar um status HTTP 2xx (200, 201, 204, etc.) para confirmar que recebeu o evento. O conteúdo da resposta não é importante, apenas o status HTTP.

O que acontece se meu endpoint estiver fora do ar?​

Se seu endpoint retornar erro ou estiver inacessível, tentaremos reenviar o evento:

  • Tentativa 1: Após 1 minuto
  • Tentativa 2: Após 5 minutos
  • Tentativa 3: Após 15 minutos

Após 3 tentativas sem sucesso, o evento será descartado.

Posso receber eventos duplicados?​

Em casos raros (como retentativas após timeout), você pode receber o mesmo evento mais de uma vez. Recomendamos implementar idempotência usando a combinação de mm + created_at + event_type + cell_id.

Qual o tempo de resposta esperado do webhook?​

Recomendamos que seu endpoint responda em menos de 5 segundos. A melhor prática é retornar 200 OK imediatamente e processar o evento de forma assíncrona.

Sobre os Eventos​

Quais tipos de eventos são enviados?​

Os tipos de eventos que existem são:

  • EVENT_IN: Quando o usuário entra em uma área monitorada

Com que frequência os eventos são enviados?​

Os eventos são enviados em tempo real assim que detectados pelo SDK. A frequência depende do movimento dos usuários nas áreas monitoradas..

Qual a latência entre o evento real e o recebimento no webhook?​

Normalmente de poucos segundos, mas pode variar dependendo da conectividade do dispositivo móvel do usuário.

Como identifico qual usuário gerou o evento?​

O campo mm é um identificador pseudônimo único por dispositivo. Se você precisar associar a um usuário específico do seu sistema, pode implementar identificação de usuário através do SDK (veja documentação do SDK para User Identification).

O que é o campo origin nos eventos?​

O campo origin indica como o evento foi detectado:

  • "beacon": Detecção via Bluetooth beacon
  • "gps": Detecção via GPS
  • "network": Detecção via rede (Wi-Fi/Celular)

Privacidade e Segurança​

Os dados dos usuários são seguros?​

Sim. O SDK não acessa informações pessoais dos usuários. Apenas dados de geolocalização anonimizados são coletados para detectar eventos de entrada/saída das áreas monitoradas.

O mm (identificador do dispositivo) é reversível?​

Não. O mm é um hash unidirecional do device ID, garantindo a privacidade do usuário.

O webhook usa HTTPS?​

Sim, exigimos que seu endpoint webhook use HTTPS para garantir a segurança na transmissão dos dados.

Testes e Debug​

Como posso testar se a integração está funcionando?​

  1. Certifique-se de que o SDK está integrado e rodando no seu app
  2. Use o próprio dispositivo com o app instalado
  3. Visite fisicamente uma das áreas monitoradas (Cell IDs configurados)
  4. Verifique se os eventos estão chegando no seu webhook

Como debugar problemas com eventos não recebidos?​

Verifique:

  1. O SDK está corretamente integrado e inicializado no app?
  2. O app tem as permissões necessárias (localização, bluetooth)?
  3. Você está realmente dentro da área da célula H3 monitorada?
  4. Seu endpoint webhook está acessível e respondendo corretamente?
  5. Verifique os logs do seu endpoint para ver se as requisições estão chegando

Posso ver um log dos eventos enviados?​

Entre em contato com nossa equipe através do suporte@grouplinkone.com para solicitar logs de eventos para debug.

Custos e Limites​

Existe um limite de eventos que posso receber?​

Não há limite técnico imposto por nós. O número de eventos depende de quantos usuários do seu aplicativo transitam nas áreas.

Como funciona a cobrança?​

Entre em contato com nossa equipe comercial para informações sobre custos e planos.

Suporte​

Não encontrei a resposta para minha pergunta. O que faço?​

Entre em contato com nossa equipe de suporte:

Nossa equipe responde em até 1 dia útil.

Onde encontro mais documentação técnica?​