Acesso a Dados em Tempo Real

Extraia dados de análise do Zenovay para criar seus próprios dashboards e ferramentas de monitoramento.

O Zenovay não expõe uma stream WebSocket pública. O dashboard renderiza atividade de visitantes em tempo real internamente, mas para suas próprias integrações o padrão suportado é o polling da API Externa. Este guia mostra como fazer isso de forma eficiente.

Onde os dados em tempo real ficam

Caso de uso	Melhor abordagem
Veja visitantes ao vivo você mesmo	A aba Vista ao Vivo no seu dashboard (atualiza em tempo real)
Dashboard personalizado	Polling da API Externa
Dados históricos	API Externa com um filtro range
Incorporar um contador de visitantes ao vivo em seu site	O recurso Widgets (um widget HTML autossuficiente)

Para ver quem está em seu site agora, abra o dashboard do seu site e selecione a aba Vista ao Vivo — ela atualiza automaticamente. As seções abaixo cobrem a construção de sua própria integração externa na API.

Polling da API Externa

Para dados de análise, use a API Externa com sua chave de API. A URL base é:

https://api.zenovay.com/api/external/v1

Autentique-se com um destes headers:

X-API-Key: zv_YOUR_API_KEY
Authorization: Bearer zv_YOUR_API_KEY

Análise Recente

O endpoint de resumo de análise aceita um parâmetro de query range (24h, 7d, 30d, 90d, 1y — padrão 7d):

const API_KEY = process.env.ZENOVAY_API_KEY;
const WEBSITE_ID = 'your-website-id';

async function getRecentAnalytics() {
  const response = await fetch(
    `https://api.zenovay.com/api/external/v1/analytics/${WEBSITE_ID}?range=24h`,
    {
      headers: { 'X-API-Key': API_KEY }
    }
  );

  return await response.json();
}

Cada resposta da API Externa é envolvida em um envelope { success, data, timestamp }, e os totais ficam sob data.summary:

{
  "success": true,
  "data": {
    "summary": {
      "total_visitors": 1247,
      "total_page_views": 3891,
      "unique_visitors": 1102
    },
    "time_range": "24h",
    "daily_stats": [ /* ... */ ]
  },
  "timestamp": "2026-06-13T00:00:00.000Z"
}

Dados de Visitantes

async function getVisitors() {
  const response = await fetch(
    `https://api.zenovay.com/api/external/v1/analytics/${WEBSITE_ID}/visitors`,
    {
      headers: { 'X-API-Key': API_KEY }
    }
  );

  return await response.json();
}

Dentro do envelope data, isto retorna um array visitors mais um objeto pagination (limit, offset, has_more). Use os parâmetros de query limit e offset para paginar através dos resultados.

Construindo um Dashboard Personalizado

Exemplo React

import { useState, useEffect } from 'react';

function LiveDashboard({ websiteId, apiKey }) {
  const [analytics, setAnalytics] = useState(null);

  // Atualize o resumo de análise em um intervalo que respeite seu limite de taxa
  useEffect(() => {
    async function fetchAnalytics() {
      try {
        const response = await fetch(
          `https://api.zenovay.com/api/external/v1/analytics/${websiteId}?range=24h`,
          {
            headers: { 'X-API-Key': apiKey }
          }
        );
        const body = await response.json();
        // As respostas são envolvidas em um envelope { success, data, timestamp }.
        setAnalytics(body.data);
      } catch (error) {
        console.error('Analytics fetch error:', error);
      }
    }

    fetchAnalytics();
    const interval = setInterval(fetchAnalytics, 5 * 60 * 1000);
    return () => clearInterval(interval);
  }, [websiteId, apiKey]);

  return (
    <div>
      {analytics && (
        <div>
          <h2>Últimas 24 horas</h2>
          <p>Visitantes: {analytics.summary.total_visitors}</p>
          <p>Visualizações de Página: {analytics.summary.total_page_views}</p>
          <p>Visitantes Únicos: {analytics.summary.unique_visitors}</p>
        </div>
      )}
    </div>
  );
}

Considerações sobre Limites de Taxa

Os limites de taxa da API Externa são por chave de API, e a API é apenas com pagamento — a linha Free é mostrada por completude, mas chaves do tier Free não podem chamá-la.

Plano	Requisições/minuto	Intervalo de Polling Recomendado
Free	Não disponível	—
Pro	30	A cada 5 minutos
Scale	60	A cada 2 minutos
Enterprise	120	A cada minuto

As respostas incluem os headers X-RateLimit-Limit e X-RateLimit-Remaining (no caminho de fallback), então você pode lê-los e fazer backoff conforme se aproxima do limite.

Melhores Práticas

• Não faça polling mais rápido do que seu limite de taxa de plano permite — dados de análise são atualizados na ordem de minutos, não segundos.
• Armazene em cache as respostas localmente entre os pollings.
• Implemente tratamento de erros com backoff exponencial.
• Para ver visitantes ao vivo você mesmo, use a aba Vista ao Vivo em vez de fazer polling — ela é construída para isso.

Próximos Passos

• Referência da API REST
• Visão Geral da API
• Obtendo uma Chave de API