Postream

Cargando el índice…

Documentación: Analítica

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.1 y [::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()).

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

EventoCuándo
pageviewCarga y cada navegación SPA.
scroll25, 50, 75 y 100% del cuerpo del post, una vez cada uno.
sectionCada H2 del cuerpo que entra en pantalla, una vez.
readLectura completa: 75% del cuerpo o el último H2 visto.
engageTiempo con la pestaña visible y señal de actividad.
ctaClic en un elemento con data-postream-cta="Etiqueta".
internal / outboundClic 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:

next.config.js
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.