[🛠] Adicionar um contador de visitas a um blog no GitHub Pages

✨ Resumo do GPT-5.5 　

Registro de como conectei um Cloudflare Worker e D1 dentro da faixa gratuita a um blog estático no GitHub Pages, preservando os valores acumulados existentes do GA enquanto mostrava as visitas de hoje e as visualizações por post.

Fiquei com vontade de colocar um contador de visitas no blog.

Não porque a funcionalidade em si seja impressionante. Na verdade, é o contrário. Ela parece uma função óbvia demais, mas em um blog estático feito com GitHub Pages ela não vem naturalmente junto.

O Google Analytics já estava instalado. Como operador, eu podia entrar no GA e ver a quantidade de visitantes e visualizações. Só que esses números não apareciam dentro do blog. Quem visita não consegue saber se este blog ainda está sendo lido hoje, nem quanto os posts recentes foram lidos.

Eu queria aquela sensação pequena dos indicadores do Naver Blog, como Hoje, Acumulado e visualizações por post aparecendo discretamente. Não era tanto um número para vaidade, mas um sinal de que o blog não é uma página estática morta, e sim algo que continua sendo lido.

Então o problema era simples.

Será que dava para manter as vantagens de um blog estático gratuito e adicionar só uma parte dinâmica bem pequena para as estatísticas de visita?

Primeiro defini as condições

Eu não queria aumentar a estrutura só para colocar um contador de visitas.

Desde o começo, defini algumas condições.

• Manter o fluxo de escrita com GitHub Pages e Jekyll.
• Não usar servidor pago.
• Resolver dentro da faixa gratuita, fosse com Cloudflare ou Firebase.
• Exibir de forma discreta perto do perfil.
• Fazer com que não fique estranhamente comprido no mobile.
• Mostrar não só as estatísticas do blog inteiro, mas também as visualizações por post.
• Não jogar fora os valores acumulados existentes do GA.

A última condição era especialmente importante.

Se eu adicionasse um contador novo e as visualizações começassem do 0, ficaria estranho. O blog já estava em operação, e o GA já tinha visualizações acumuladas de antes. Mas continuar lendo só do GA também ficava distante da sensação de contador que eu queria.

Achei que bastaria ler o GA

No começo, pensei que ler a API do Google Analytics resolveria.

Como o GA já tinha os dados, parecia que bastaria um Cloudflare Worker chamar a API do GA e devolver os números. Na prática, criei uma conta de serviço, dei permissão na propriedade do GA e consegui fazer as chamadas da API.

Mas, quando conectei de fato, não era o que eu queria.

GA é uma ferramenta de análise. É boa para o operador olhar o fluxo depois, mas ficou meio ambígua como contador de visitas que reage diretamente na tela do blog. O número de Hoje era especialmente problemático. Se eu acabasse de entrar no blog e, mesmo assim, o valor de hoje aparecesse como 0, do ponto de vista do visitante parecia simplesmente quebrado.

Os nomes das métricas também confundiam. Active users e page views são valores diferentes. Se eu tentasse capturar a quantidade de visitantes de forma rigorosa, o número pareceria conservador demais. Se usasse page view, a sensação ficava mais natural, mas o rótulo precisava de cuidado.

No fim, a decisão foi simples.

Usar o GA como valor base histórico e contar por conta própria os incrementos daqui em diante.

Separei o baseline e o incremento

A estrutura final ficou assim.

Visualizações públicas = baseline do GA + incremento do Cloudflare D1

O baseline do GA é o número já acumulado. Define-se uma data de referência e salva-se o total de visualizações do site inteiro e as visualizações por post até aquele momento.

A partir daí, o Cloudflare Worker conta diretamente. Quando uma pessoa entra no blog, o JavaScript chama o Worker, e o Worker registra no D1 os incrementos de hoje, do mês, do total e por page path.

Resumindo, fica assim.

Valores acumulados existentes: baseline do Google Analytics
Novo incremento: Cloudflare Worker + D1
API pública: Cloudflare Worker
Exibição no blog: Jekyll include + JavaScript

Gostei desse método porque ele não descarta nenhum dos dois lados.

Ele preserva os dados existentes do GA. Ao mesmo tempo, os contadores futuros reagem imediatamente na tela do blog.

Por que Cloudflare Worker e D1

Firebase também era uma opção. Mas, para uma função desse tamanho, o lado da Cloudflare era mais simples.

GitHub Pages é um site estático, então não há lugar para colocar código de servidor. O Worker preenche esse espaço vazio com uma peça pequena. O D1 é baseado em SQLite, então era suficiente para armazenar números simples como os de um contador de visitas.

A condição de custo também encaixava. Um contador de visitas para blog pessoal pode ser tratado dentro da faixa gratuita. Se muita gente aparecer de repente, existe a possibilidade de uma parte da contagem oscilar um pouco, mas os posts em si não quebram. Para começo de conversa, isso não é um sistema de pagamento nem um livro contábil financeiro.

O que eu queria não era contabilidade exata, mas mostrar o fluxo de que o blog está sendo lido.

Bloqueei bots e visitas duplicadas com moderação

Quando se coloca um contador em uma página pública, bots também podem aumentar os números.

É difícil bloquear perfeitamente. E, se eu bloquear com rigidez demais, acabo me afastando da sensação de contador que eu queria. Eu preferia algo que contasse de forma um pouco generosa, como no Naver Blog.

Então o Worker tratou só algumas coisas.

• Excluir user-agents que são bots evidentes.
• Não contar novamente, dentro de um certo intervalo de tempo, a mesma combinação de visitante e página.
• Acumular as visualizações por post do mesmo modo, com base no path.

Ou seja, ajustei para um contador público de visitas, não para uma ferramenta de análise rigorosa.

Coloquei pequeno na tela

No começo, tentei mostrar as estatísticas em várias células. Mas a UI que fica ao lado do perfil precisa ser pequena. Quando aparecem números demais, a primeira tela do blog fica mais bagunçada.

Então, no fim, deixei três valores.

Hoje / Mês / Total

Hoje dá a sensação de que o blog está sendo lido agora. Mês mostra a escala recente. Total mostra o tempo que o blog foi acumulando.

Nas listas de posts, coloquei visualizações em cada post.

10 visualizações

Esse valor também usa a mesma estrutura das estatísticas gerais.

Visualizações por post = baseline por post do GA + incremento por post do Cloudflare D1

Por exemplo, se um post tinha 9 visualizações segundo o GA e foi lido mais uma vez depois da mudança para o contador novo, a tela mostra 10 visualizações.

Isso foi o mais natural. As visualizações passadas não são descartadas, e as visualizações futuras se acumulam imediatamente.

Resultado

Como resultado, números assim apareceram perto do perfil do blog.

Hoje 1 / Mês 66 / Total 4,944

E as listas de posts mostram visualizações assim.

10 visualizações

Olhando só para a funcionalidade, ela é pequena. Mas gosto bastante desse trabalho.

O problema era claro. Um blog no GitHub Pages não tinha contador de visitas. O GA existia, mas não era suficiente como contador na tela pública. Mesmo assim, eu não queria criar um servidor grande só por causa de um blog.

Então preservei os dados existentes do GA como baseline e adicionei uma estrutura que conta diretamente apenas os incrementos posteriores com Cloudflare Worker e D1.

As vantagens do blog estático ficaram como estavam. Escrevo em Markdown, publico com GitHub Pages, e o custo de manutenção fica praticamente zero. Em vez disso, coloquei uma pequena peça serverless exatamente na parte que faltava.

Se mais tarde eu mostrar este blog como portfólio, acho que trabalhos como este podem ser até mais fáceis de explicar. Não é uma funcionalidade grandiosa, mas nasceu de um incômodo real, limitou custo e complexidade, e chegou até uma forma operável.