Como funciona a medição

As análises de documentação geralmente mentem das mesmas quatro maneiras: rastreadores contabilizados como leitores, abas em segundo plano contabilizadas como leitura, as próprias visitas do proprietário contabilizadas como público e porcentagens citadas com base em um punhado de visitas. Esta página descreve o mecanismo, para que você possa verificar cada um desses pontos por conta própria antes de agir com base em um número.

O que você obtém#

Cada métrica no painel de análise do Docsbook é derivada de um único fluxo de eventos, com uma única definição de visita e uma única definição de ser humano — não de um conjunto de contadores independentes que podem divergir. Quando não é possível afirmar um número com honestidade, você recebe um travessão, o rótulo "não medido" ou uma porcentagem suprimida, nunca um 0 apresentado com confiança. E nada é armazenado nos navegadores dos seus leitores para produzir qualquer uma dessas informações.

O que é coletado e o que deliberadamente não é#

O Docsbook registra 36 eventos nomeados docs.* no seu site de documentação — visualizações de página, segmentos de tempo de leitura, títulos rolados até ficarem visíveis, pesquisas, ações do chat de IA, cópias, cliques de navegação, cliques em links externos, votos de feedback e saídas. A lista completa está na referência de eventos rastreados.

Cada evento contém o projeto ao qual pertence, o caminho da página e todos os itens aplicáveis entre: segundos, âncora do título, referenciador, host de destino, idioma, User-Agent e o país/região/cidade/coordenadas que a borda resolveu a partir da solicitação. O IP do leitor é anexado no lado do servidor, no endpoint de ingestão, nunca pelo navegador.

Como um visitante e uma visita são definidos#

Um visitante é sha256(secret salt + project + IP), truncado para 16 caracteres hexadecimais. Essa é toda a identidade. Ela é estável — a mesma pessoa na próxima semana terá o mesmo identificador — e tem escopo: o salt é um segredo no servidor e o nome do projeto faz parte da entrada, portanto o ID não pode ser associado ao tráfego de nenhum outro site, incluindo outro projeto do Docsbook.

Uma visita é reconstruída a partir dos eventos, não rastreada com um cookie de sessão. Os eventos de um visitante são ordenados por tempo e separados sempre que há um intervalo superior a 30 minutos. Esse é um intervalo de inatividade, não um bloco fixo de tempo, de propósito: o agrupamento em blocos divide uma visita que atravessa um limite, portanto um leitor ativo das 12:29 às 12:31 seria registrado como duas visitas.

Como bots e rastreadores são filtrados#

A filtragem é executada em duas camadas independentes, porque se sabe que qualquer uma delas, sozinha, pode falhar.

1. User-Agent. Uma expressão regular que abrange rastreadores, spiders, navegadores headless, clientes HTTP baseados em scripts, ferramentas de SEO e agentes que buscam prévias de links, além de todos os bots de IA na tabela do classificador. Duas strings literais de UA são fixadas porque foram observadas rastreando em grande volume enquanto se identificavam como telefones comuns — um dispositivo de referência Googlebot Smartphone e uma versão antiga do iOS.
2. Comportamento. Uma visita que não produziu nenhum evento que somente um runtime JavaScript pode emitir — nenhum segmento de tempo de leitura, nenhuma visualização de título, nenhuma saída, nenhum clique — não executou JavaScript e é um rastreador, independentemente do que seu User-Agent diga.

Além disso, sua própria equipe é excluída de todas as métricas de leitores. Um visitante cujo IP também enviou um beacon de sessão administrativa para este projeto nos últimos 30 dias é identificado como proprietário e removido das métricas de leitores — mantido separado do sinalizador de bot, porque é uma pessoa real, apenas não faz parte do seu público. Opcionalmente, uma lista de permissões de IP no servidor remove o tráfego interno antes mesmo que ele seja gravado.

As visitas de bots e proprietários são mantidas e rotuladas, não excluídas, para que o painel possa mostrar a divisão em vez de reduzir silenciosamente seus números.

Como o tempo de leitura é realmente calculado#

O rastreador inicia um cronômetro quando uma página é montada e faz sua leitura quando o leitor sai — em pagehide, em visibilitychange → hidden no iOS (onde pagehide não é confiável) e na navegação dentro do site. Cada leitura emite um docs.read_time segmento e reinicia o cronômetro, portanto uma página à qual se retorna produz dois segmentos em vez de um único período contado duas vezes. Segmentos com menos de 3 segundos não são emitidos.

A entrega é feita por navigator.sendBeacon para um endpoint de mesma origem, agrupada em lotes de até 100 eventos por beacon. O transporte de registro comum aplica um debounce de dois segundos sobre fetch, que não sobrevive ao fechamento de uma aba — o tempo de leitura, as visualizações de títulos e as saídas são os eventos que precisam sobreviver a isso, portanto seguem pelo caminho do beacon.

Em seguida, cada segmento é limitado a 300 segundos antes que qualquer soma seja feita. Este é o número mais importante desta página. O emissor continua contando enquanto uma aba de desktop permanece em segundo plano e, em uma análise de 11.176 sessões reais em 7 espaços de trabalho, 40 segmentos individuais excederam duas horas, o percentil 99 foi de 81.342 segundos e a soma dos segmentos brutos inflou o tempo total de leitura em aproximadamente trinta vezes — 1.268.422 segundos contra 42.160 após o limite. O mesmo limite é aplicado por toda interface que apresenta um valor de tempo, portanto o painel, a coluna por página, a camada de metas e as ferramentas MCP não podem divergir.

A média do tempo de leitura por página divide o total limitado pela quantidade de segmentos, não pela quantidade de visitas: um leitor que mudou para outra aba e voltou contribui com dois segmentos para uma visita, e calcular a média por visita atribuiria o dobro do crédito a essa visita.

Como o tráfego de assistentes de IA é distinguido do tráfego humano#

As solicitações são classificadas em três grupos que nunca são mesclados:

Um nome de bot de IA não reconhecido é tratado como treinamento — a alegação que menos promete a você. A classificação é feita pelo User-Agent, na ordem em que a primeira correspondência vence, portanto Applebot-Extended nunca é absorvido por Applebot.

Amostragem, limites e retenção#

Não há amostragem. Nenhum valor no painel é extrapolado a partir de um subconjunto do tráfego. O que existe, em vez disso, é um limite rígido: a reconstrução de sessões lê no máximo 50.000 eventos por janela e, quando atinge esse limite, o resultado contém uma truncated que os consumidores devem apresentar, pois as taxas calculadas com base em uma janela truncada estão erradas. Uma consulta que falha também é reportada como falha, e não como zero — um painel vazio e uma leitura interrompida são respostas diferentes.

Os eventos do leitor são mantidos por 30 dias, em todos os planos. Trinta dias é o ponto em que os dados terminam, não um nível: é o período de retenção do armazenamento de eventos. Todo seletor de período no produto lê a mesma constante, portanto nenhum controle pode oferecer uma janela que os dados não conseguem preencher. O registro de uso de IA é um armazenamento separado e é mantido por mais tempo — 90 dias, com remoção diária — para que uma cobrança contestada ainda possa ser reconstruída depois que os relatórios deixarem de exibi-la; de qualquer forma, nenhum relatório oferece mais de 30 dias desse registro.

Onde os dados ficam#

Os dados do Search Console exibidos no painel são obtidos do Google por meio da conexão que você autoriza e são dados do Google, não do Docsbook.

Privacidade e GDPR — o que é fato técnico e o que cabe a você decidir#

Fatos técnicos, verificáveis no comportamento do site:

• A análise do site de documentação do Docsbook não grava nada no dispositivo do leitor e não lê nada dele. Não há cookie de análise nem ID armazenado pelo navegador.
• A identidade do leitor é derivada do IP por meio de um hash com chave, no servidor, associado ao seu projeto. O hash é de mão única; o IP bruto não é exposto por nenhum relatório, exportação ou ferramenta MCP.
• Nenhum identificador é compartilhado entre projetos, e nenhum é vendido, distribuído ou usado para criar um perfil entre sites.
• A retenção é de 30 dias e é aplicada pelo armazenamento, não por um filtro de relatório.

O que não afirmamos. O Docsbook não declara que executá-lo torna seu site isento de consentimento, em conformidade com o GDPR ou isento de qualquer regra nacional. Duas coisas que seu próprio consultor jurídico precisa decidir:

1. Se a exigência de consentimento da ePrivacy se aplica. O Artigo 5(3) da Diretiva 2002/58/CE (conforme alterada) condiciona "o armazenamento de informações ou o acesso a informações já armazenadas no equipamento terminal" ao consentimento. O Docsbook não armazena nem lê nada no dispositivo, que é o gatilho mencionado nessa disposição — mas as Diretrizes 2/2023 do EDPB sobre o Escopo Técnico do Art. 5(3) dedicam uma seção especificamente ao "Rastreamento baseado apenas em IP", portanto trate "sem cookie, portanto sem consentimento" como um argumento, não como uma resposta definitiva.
2. Se você ainda precisa de uma base legal sob o GDPR. Um endereço IP que identifica um leitor é um dado pessoal independentemente da questão do cookie, portanto seu aviso, sua base legal e seus termos com os operadores dos fornecedores acima são de sua responsabilidade. Os próprios critérios de isenção da CNIL para medição de audiência são uma lista de verificação útil neste caso, e o Docsbook atende a vários deles (editor único, sem vinculação entre sites, finalidade limitada à medição de audiência) e não a todos — notavelmente, ele não trunca o último byte do IP antes de armazená-lo.

Por que esta é a maneira correta#

Limites e questões em aberto#

• Cada contagem de visitantes é uma estimativa, e o produto deixa isso claro em suas próprias respostas. Um IP com hash reúne todos os usuários por trás de um único NAT corporativo em um só leitor e divide um único usuário que se desloca entre vários. Leia os números de visitantes como uma tendência; nunca os cite como uma contagem de pessoas.
• O tempo de leitura é limitado, não condicionado à visibilidade. No desktop, uma aba deixada aberta em segundo plano continua acumulando segundos até que o limite de 300 segundos a interrompa. Isso é honesto quanto à direção do seu erro — o tempo de leitura é tendencioso para cima, limitado —, mas não é a mesma medição que o tempo de engajamento baseado em foco do GA4, e esta documentação não afirma que seja.
• Os filtros de bots são heurísticas sem uma etapa de verificação. O Docsbook não faz nenhuma verificação de DNS reverso ou de intervalos de IP publicados da identidade alegada por um rastreador, portanto um User-Agent falsificado é classificado pelo valor declarado. A camada comportamental detecta o caso comum que uma expressão regular de UA não identifica; nenhuma das camadas é um controle de segurança.
• A exclusão do proprietário depende de um único beacon. Um colega que lê a documentação, mas nunca abriu o painel de administração a partir daquele IP nos últimos 30 dias, é contado como leitor.
• A Geo-IP resolve a rede, não a pessoa. Uma VPN corporativa coloca um leitor na cidade onde o túnel termina; uma rede móvel pode estar a cem quilômetros de distância.
• Em questão: "sem cookie" não é o mesmo que "sem necessidade de consentimento". O que é verificável é que a análise do site de documentação do Docsbook não armazena nem lê nada no navegador, e que a identidade do leitor é um hash com salt no lado do servidor. O que não está definido é a consequência jurídica: o EDPB abriu explicitamente a questão do rastreamento baseado apenas em IP nos termos do Art. 5(3), e nenhuma fonte pública a resolve para um caso com hash, de primeira parte e de 30 dias. Considere a conclusão de conformidade como algo que cabe ao seu assessor jurídico determinar.
• Trinta dias é um teto rígido. Não é possível obter comparação ano a ano, leitura sazonal ou qualquer coorte com mais de quatro semanas a partir destes dados.

Relacionado#

• Referência de eventos rastreados — os 36 eventos descritos nesta página
• Visão geral da análise — o painel que essas definições produzem
• Tempo de leitura — o recorte aplicado a um relatório
• Metas e funis — o que se considera que uma visita alcançou
• Países — resolução geográfica e seus limites na prática