Postream

Carregando o índice…

Documentação: Analytics

Analytics

Leitura, rolagem e engajamento dos posts com um script sem cookies de menos de 2 KB.

O pacote @postream/analytics mede os posts do blog com um script leve (menos de 2 KB gzip, sem dependências e sem cookies). Os números aparecem no painel, em Analytics, por site e por post.

A chave do site

A chave do analytics é o id do site, mostrado em Analytics → Instalação. Ela é pública e vai no HTML do blog: não é a chave da API (nem sk_, nem pk_). O que protege a coleta é a origem. Só são aceitos eventos:

  • de https://<domínio do site> e dos subdomínios dele, em https;
  • dos domínios permitidos no navegador da API pública (os mesmos da chave publicável);
  • de localhost, 127.0.0.1 e [::1], só com Permitir localhost marcado, para desenvolvimento.

Fora disso, a coleta responde 403 FORBIDDEN.

Instalar

<script async src="https://cdn.jsdelivr.net/npm/@postream/analytics/dist/postream.js"
  data-key="SITE_KEY"
  data-endpoint="https://api.postream.blog/collect"></script>

Atributos opcionais: data-spa="false" (não contar history.pushState como nova página) e data-auto="false" (não mandar o primeiro pageview; chame postream.pageview()).

Ligar a página ao post

Na página do post, ligue a página ao post do Postream. Com isso o painel mostra a página sob o post e o idioma certos, mesmo se a URL mudar:

import { postAttributes, postMeta } from "@postream/analytics";
import { postMetadata } from "@postream/seo";
 
export async function generateMetadata({ params }: Props) {
  const { locale, slug } = await params;
  const post = await postream.getPost(slug, { locale });
  return post ? { ...postMetadata(post, seo), other: postMeta(post) } : {};
}
 
export default async function BlogPost({ params }: Props) {
  // ...
  return <article {...postAttributes(post)}>{/* corpo */}</article>;
}

postMeta gera <meta name="postream:post|slug|locale">; postAttributes gera data-postream-post|slug|locale no elemento do corpo. Rolagem e seções lidas são medidas dentro desse elemento.

Eventos

EventoQuando
pageviewCarregamento e cada navegação SPA.
scroll25, 50, 75 e 100% do corpo do post, uma vez cada.
sectionCada H2 do corpo que entra na tela, uma vez.
readLeitura completa: 75% do corpo ou o último H2 visto.
engageTempo com a aba visível e sinal de atividade.
ctaClique em elemento com data-postream-cta="Rótulo".
internal / outboundClique em link do mesmo host / de outro host.

Eventos próprios: postream.track("newsletter_signup", { plan: "free" }) no script ou track do pacote. Não mande dados pessoais nas propriedades.

Proxy no domínio do blog

Bloqueadores de anúncio costumam barrar domínios de terceiros. Encaminhe um caminho do blog para a coleta e aponte o endpoint para ele:

next.config.js
module.exports = {
  async rewrites() {
    return [{ source: "/stats/collect", destination: "https://api.postream.blog/collect" }];
  },
};

Depois use endpoint="/stats/collect". O proxy precisa repassar o IP do visitante (X-Forwarded-For ou CF-Connecting-IP) e manter o Origin da página, que a coleta confere.

Privacidade

Sem cookies, localStorage ou identificador no aparelho. O IP nunca é gravado: o visitante é um hash diário (salt do dia + site + IP + User-Agent), e o salt é apagado no dia seguinte. Robôs e navegadores automatizados são descartados.