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.1e[::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()).
import { PostreamAnalytics } from "@postream/analytics/next";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="pt-BR">
<body>
{children}
<PostreamAnalytics siteKey="SITE_KEY" endpoint="https://api.postream.blog/collect" />
</body>
</html>
);
}Navegações do App Router passam por history.pushState e já contam como 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
| Evento | Quando |
|---|---|
pageview | Carregamento e cada navegação SPA. |
scroll | 25, 50, 75 e 100% do corpo do post, uma vez cada. |
section | Cada H2 do corpo que entra na tela, uma vez. |
read | Leitura completa: 75% do corpo ou o último H2 visto. |
engage | Tempo com a aba visível e sinal de atividade. |
cta | Clique em elemento com data-postream-cta="Rótulo". |
internal / outbound | Clique 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:
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.