When WordPress is only your editor and an Astro or Next.js site shows the posts to readers, your WordPress analytics plugin goes blank. It counts pages WordPress builds for visitors, and on a headless site WordPress builds none. Readers load the front end, and WordPress only answers its API calls.

The usual fix is a separate analytics tool on the front end. That works, but the numbers then live in a different place from your content. A pageview arrives as an address like /blog/my-post/, with no idea which post it shows, who wrote it or when it was published.

There’s another way: send the front end’s pageviews back to WordPress, and match each one to the post it shows.

How it works in Vireo

Vireo Analytics gives you one script tag for the front end. The tag loads Vireo’s tracker from your WordPress site and sends each pageview to it. WordPress matches the page to a post, so Top pages, each post’s own stats screen and the Views column in the admin fill up as they would with a theme.

Vireo only accepts these pageviews from the front-end address you enter. Paste the tag on any other site and it records nothing. It’s free for one front end.

Set it up

  1. In WordPress, go to Vireo Analytics, Settings, Other sites, Headless front end.
  2. Enter the “Front-end site address”: the address readers see, including https://.
  3. Click “Save settings”.
  4. Copy the tag shown under “Add to the front end”.

It looks like this, with your own addresses:

<script defer src="https://cms.example.com/wp-content/plugins/vireo-analytics/assets/js/tracker.js" data-endpoint="https://cms.example.com/..."></script>

Always copy the tag from the settings screen rather than typing it. The endpoint address depends on your host, and the screen shows the one that works for yours.

The tag needs to stay a classic script. The tracker reads its settings from its own tag, and a script that a bundler has turned into a module can’t do that. Both frameworks below leave it alone if you add it the way shown.

Astro

Paste the tag into the layout every page uses, just before </body>:

---
// src/layouts/Base.astro
---
<html lang="en">
  <head>...</head>
  <body>
    <slot />
    <script defer src="https://cms.example.com/wp-content/plugins/vireo-analytics/assets/js/tracker.js" data-endpoint="https://cms.example.com/..."></script>
  </body>
</html>

Astro bundles plain <script> tags, but a tag with attributes other than src is left as written, so this one stays a classic script without any changes.

If you use Astro’s view transitions, the tracker counts each page change on its own, by listening for Astro’s astro:page-load event. Keep the tag in the shared layout so it’s on every page a reader might land on. Astro runs a script from the same address only once per visit, so the tracker doesn’t load twice as readers move around.

Next.js

In the App Router, add it to the root layout with next/script. It passes data- attributes through to the script tag:

// app/layout.tsx
import Script from 'next/script';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>{children}</body>
      <Script
        src="https://cms.example.com/wp-content/plugins/vireo-analytics/assets/js/tracker.js"
        data-endpoint="https://cms.example.com/..."
        data-spa="history"
      />
    </html>
  );
}

Keep data-spa="history" in the tag. Next.js changes pages without reloading, by updating the address through the browser’s History API. With that attribute, each of those changes and each back or forward step counts as a pageview. Without it, only full page loads are counted.

The same attribute works for any other framework whose router uses the History API. If yours does something else, call vireo('pageview') after each new page has rendered.

Match pages to posts

Vireo matches by path. If the front end keeps WordPress’s permalinks, so /my-post/ on the front end is the post at /my-post/ in WordPress, there’s nothing to do.

If the paths differ, for example because the front end puts posts under /blog/, add the post’s WordPress ID to each page’s head:

<meta name="vireo:post-id" content="123">

You already have the ID: it’s id in the REST API and databaseId in WPGraphQL. In Astro, print the tag in the post layout’s head. In Next.js, add it through generateMetadata with other: { 'vireo:post-id': String(post.id) }.

Vireo tries the path first and uses the ID only when the path doesn’t match a post. Pages that aren’t posts, such as your home page or a tag listing, are still counted by address. For anything trickier, a developer can map paths to posts in PHP with the vireo_headless_post_id filter.

Custom events

On a WordPress theme, Vireo prints a small vireo() stub that queues calls until the tracker loads. On a front end there’s no stub, so guard the call:

window.vireo?.('event', 'newsletter_signup');

Events from the front end show up in Top events with everything else. The tracker docs list the rules for event names and values.

Test traffic and Search Console

Pageviews are accepted only from the address you entered, which keeps preview deployments and localhost out of your numbers. A developer can add more addresses with the vireo_headless_allowed_origins filter.

For Search Console, connect the property for the front end’s address, since that’s the site Google indexes. The searches behind each post explains what you get from it.

A front end that isn’t your blog

The headless setting is for a front end that shows your WordPress posts. A separate site, such as a docs site or a landing page built with something else, is a connected site instead: it gets its own numbers, and a site selector on the Overview switches between them. One connected site is free, and it can collect Core Web Vitals with a second tag.