Brandfine Docs
WordPress

Analytics auto-inject

Enable Brandfine analytics on your WordPress site with one toggle. Pageviews flow into your Brandfine analytics dashboard automatically — no cookies, no consent banner.

When analytics is active on the workspace you've connected, the plugin can auto-inject the Brandfine analytics tracker into every public WordPress page. Pageviews + sources + referrers flow into your Brandfine analytics dashboard.

Why "auto"-inject

The npm SDK requires the customer to call bf.analytics.install() in their site code. WordPress sites don't run JS at build time (usually), so the equivalent is a wp_head hook that the plugin fires when:

  1. Analytics is active on the connected workspace
  2. The "Enable on this site" toggle is on (separate from the workspace-level activation — you might run multiple WordPress sites pointing at the same workspace and want analytics on some but not others)

The script is identical to what the npm SDK emits — same data-website-id, same provider (Umami today). A site moving from a custom Next.js frontend to WordPress keeps the same analytics without losing history.

Enable

Step 1 — Activate analytics on the workspace

Brandfine CMS → workspace's SEO & Analytics → Analytics → Enable analytics. This provisions an analytics site (Umami "website") and creates the Brandfine ↔ analytics-backend bridge.

Step 2 — Toggle on for this WordPress site

WP admin → Brandfine → scroll to Analytics on this site → Enable on this site.

A confirmation message appears. From the next page render onward, the tracker <script> is in <head> for every public page.

Verify it's working

  1. Open any public page on the WordPress site in your browser
  2. View Source → search for data-brandfine="wp-plugin"
  3. You should see a line like: 
    <script defer src="…/script.js" data-website-id="…" data-brandfine="wp-plugin"></script>
  4. Refresh the page once more to fire a pageview
  5. In the Brandfine analytics dashboard, click Check now or wait ~5 seconds — the workspace should flip from "Waiting" to "Connected" and the pageview shows up

How the cache works

The plugin caches the upstream analytics config (the websiteId + scriptUrl) in a WP transient for 60 seconds. This keeps API load proportional (one call per minute per site) while keeping the disable / re-enable self-heal window short enough that customers don't notice it. Negative caching on upstream failures is 15 seconds.

If you disable and re-enable analytics in Brandfine (which provisions a fresh analytics-backend site), the WordPress tracker switches to the new site ID within 60 seconds — no intervention needed.

If you ever need to bust the cache immediately:

wp transient delete brandfine_analytics_config

Or in WP admin → Brandfine → Disconnect → reconnect with the same key.

Disable

WP admin → Brandfine → Disable on this site. The wp_head hook stops emitting the script tag immediately. No new pageviews flow into Brandfine. Existing data in the analytics backend stays put.

Privacy

Brandfine's analytics tracker is cookie-free and doesn't collect personally-identifiable data. You don't need a consent banner for it under GDPR/CCPA in most jurisdictions. (Always confirm with your own legal counsel for your specific use case.)

On this page

Why "auto"-injectEnableStep 1 — Activate analytics on the workspaceStep 2 — Toggle on for this WordPress siteVerify it's workingHow the cache worksDisablePrivacy