Analítica
Lectura, scroll y engagement de los posts con un script sin cookies de menos de 2 KB.
El paquete @postream/analytics mide los posts del blog con un script liviano (menos de 2 KB gzip, sin dependencias y sin cookies). Los números aparecen en el panel, en Analítica, por sitio y por post.
La clave del sitio
La clave de la analítica es el id del sitio, que se muestra en Analítica → Instalación. Es pública y va en el HTML del blog: no es la clave de la API (ni sk_ ni pk_). Lo que protege la recolección es el origen. Solo se aceptan eventos:
- de
https://<dominio del sitio>y de sus subdominios, por https; - de los dominios permitidos en el navegador de la API pública (los mismos de la clave publicable);
- de
localhost,127.0.0.1y[::1], solo con Permitir localhost marcado, para desarrollo.
Fuera de eso, la recolección 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 opcionales: data-spa="false" (no contar history.pushState como página nueva) y data-auto="false" (no enviar el primer pageview; llama a postream.pageview()).
import { PostreamAnalytics } from "@postream/analytics/next";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="es">
<body>
{children}
<PostreamAnalytics siteKey="SITE_KEY" endpoint="https://api.postream.blog/collect" />
</body>
</html>
);
}Las navegaciones del App Router pasan por history.pushState y ya cuentan como pageview.
Vincular la página al post
En la página del post, vincula la página al post de Postream. Así el panel muestra la página bajo el post y el idioma correctos, aunque la URL cambie:
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)}>{/* cuerpo */}</article>;
}postMeta genera <meta name="postream:post|slug|locale">; postAttributes genera data-postream-post|slug|locale en el elemento del cuerpo. El scroll y las secciones leídas se miden dentro de ese elemento.
Eventos
| Evento | Cuándo |
|---|---|
pageview | Carga y cada navegación SPA. |
scroll | 25, 50, 75 y 100% del cuerpo del post, una vez cada uno. |
section | Cada H2 del cuerpo que entra en pantalla, una vez. |
read | Lectura completa: 75% del cuerpo o el último H2 visto. |
engage | Tiempo con la pestaña visible y señal de actividad. |
cta | Clic en un elemento con data-postream-cta="Etiqueta". |
internal / outbound | Clic en un enlace del mismo host / de otro host. |
Eventos propios: postream.track("newsletter_signup", { plan: "free" }) en el script o track del paquete. No envíes datos personales en las propiedades.
Proxy en el dominio del blog
Los bloqueadores de anuncios suelen frenar los dominios de terceros. Redirige una ruta del blog a la recolección y apunta el endpoint a ella:
module.exports = {
async rewrites() {
return [{ source: "/stats/collect", destination: "https://api.postream.blog/collect" }];
},
};Después usa endpoint="/stats/collect". El proxy tiene que reenviar la IP del visitante (X-Forwarded-For o CF-Connecting-IP) y mantener el Origin de la página, que la recolección verifica.
Privacidad
Sin cookies, localStorage ni identificador en el dispositivo. La IP nunca se guarda: el visitante es un hash diario (salt del día + sitio + IP + User-Agent), y el salt se borra al día siguiente. Los robots y los navegadores automatizados se descartan.