Analytics
Reading, scroll and engagement on posts with a cookieless script under 2 KB.
The @postream/analytics package measures the blog's posts with a light script (under 2 KB gzipped, no dependencies and no cookies). The numbers show up in the panel, under Analytics, per site and per post.
The site key
The analytics key is the site id, shown under Analytics → Installation. It is public and goes in the blog's HTML: it is not the API key (neither sk_ nor pk_). What protects collection is the origin. Events are only accepted:
- from
https://<site domain>and its subdomains, over https; - from the public API's domains allowed in the browser (the same ones as the publishable key);
- from
localhost,127.0.0.1and[::1], only with Allow localhost ticked, for development.
Anything else, and collection answers 403 FORBIDDEN.
Install
<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>Optional attributes: data-spa="false" (do not count history.pushState as a new page) and data-auto="false" (do not send the first pageview; call postream.pageview()).
import { PostreamAnalytics } from "@postream/analytics/next";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
{children}
<PostreamAnalytics siteKey="SITE_KEY" endpoint="https://api.postream.blog/collect" />
</body>
</html>
);
}App Router navigations go through history.pushState and already count as pageviews.
Link the page to the post
On the post page, link the page to the Postream post. The panel then shows the page under the right post and language, even if the URL changes:
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)}>{/* body */}</article>;
}postMeta generates <meta name="postream:post|slug|locale">; postAttributes generates data-postream-post|slug|locale on the body element. Scroll and sections read are measured inside that element.
Events
| Event | When |
|---|---|
pageview | Load and each SPA navigation. |
scroll | 25, 50, 75 and 100% of the post body, once each. |
section | Each H2 of the body that comes into view, once. |
read | Full read: 75% of the body or the last H2 seen. |
engage | Time with the tab visible and a sign of activity. |
cta | Click on an element with data-postream-cta="Label". |
internal / outbound | Click on a link to the same host / another host. |
Custom events: postream.track("newsletter_signup", { plan: "free" }) in the script or the package's track. Do not send personal data in the properties.
Proxy on the blog's domain
Ad blockers often block third-party domains. Forward a path on the blog to the collector and point the endpoint at it:
module.exports = {
async rewrites() {
return [{ source: "/stats/collect", destination: "https://api.postream.blog/collect" }];
},
};Then use endpoint="/stats/collect". The proxy must pass on the visitor's IP (X-Forwarded-For or CF-Connecting-IP) and keep the page's Origin, which the collector checks.
Privacy
No cookies, localStorage or device identifier. The IP is never stored: the visitor is a daily hash (the day's salt + site + IP + User-Agent), and the salt is deleted the next day. Bots and automated browsers are discarded.